Command Reference

Every dot command, alias, flag and example, generated from the CLI command tree.

This page lists every dot command from the same Effect command tree that powers parsing, help, dispatch, and shell completions.

dot init

Run one-time first-use machine setup

dot init [flags]

Run the one-time first-use setup workflow for a fresh machine. Init prepares repos, stow links, mise tools, packages, and machine hooks, and trusts mise configs in tracked repos. After init completes, reboot so the Omarchy session picks up host env, then run dot doctor. Before the bounded workflow starts, init updates or clones the optional private overlay according to DOT_ALLOW_PRIVATE. Use dot update for ongoing maintenance.

Options

Examples

dot init --noninteractive
dot init --host laptop --noninteractive
dot init --force --noninteractive

dot install

Ensure prerequisites, then backup/adopt dotfiles

dot install [flags]

Options

dot update

Aliases: dot up

Self-update, pull repos, stow dotfiles, rebuild. Phase flags are inclusive: passing any of –pull, –stow, or –app runs only the selected phases. Internal –no-self-update, –post-hook-repo and –started-at flags support the active self-update handoff; internal –summary-file lets system-update print the summary last.

dot update [flags]

A full update pulls the public dotfiles, installs Bun dependencies, rebuilds and relaunches dot, then scans and pulls tracked repositories, trusting mise configs only in repositories it freshly clones. It moves the dot-managed skills checkout to the latest skills main before rebuilding skill-maintenance. Pulls are fast-forward-only and never stash or rebase: Git refuses an update if local edits would be overwritten or histories have diverged. It regenerates completions, installs missing public Arch/AUR packages, runs the required MCP sync, stows, rebuilds again, runs agents sync, backfills the init marker, and refreshes shell modules. The shell restarts only when its generated config or a deployed Omarchy plugin changed. It finishes with a summary of updated repositories and every completed or skipped step, in order.

Phase flags are inclusive: passing any of –pull, –stow, or –app runs only the selected phases. Scoped runs skip full-update package reconciliation, agents sync, and init-marker backfill.

Use –repo PATH (repeatable) to pull selected repositories, restore their pinned submodules and run configured post-update commands after HEAD changes. Changed public or private dotfiles also rebuild, stow and sync agent instructions once per batch. Add –pull to only pull and run post-update commands, skipping the dotfiles rebuild and stow. Herdr plugins are refreshed only inside Herdr. The Git panel uses –no-reload to skip shell reload and module refresh.

Options

Exit codes

0   Update completed, or no actionable updates were found
1   Fatal workflow failure
2   Update check could not finish
10  Update check found pulls, pending pins or stow changes
11  Legacy Hypr migration is required

dot system-update

Select and run Dotfiles, Omarchy, and Topgrade updates

dot system-update [flags]

Select maintenance steps interactively, then run them in order: Dotfiles, Omarchy, and Topgrade. Interactive runs pre-select Dotfiles and Omarchy; extra Topgrade steps start unselected. Non-interactive runs and –yes select every step. Cancelling the prompt exits without running updates.

Options

Examples

dot system-update
dot system-update --yes

dot deps

Validate and publish grouped native dependency updates

dot deps <subcommand> [flags] [<repository>]

Read native policy and manifests from a pinned remote target, preserving the caller’s checkout. Exclude whole groups covered by any open dependency PR, including failed, pending and draft PRs. –all bypasses only PR inventory and exclusion. –dry-run discovers updates without repository scripts, installs, checks or writes to Git. Bare dot deps starts groups by priority and prepares and validates them concurrently in isolated worktrees, bounded by –concurrency. Check commands share the same concurrency cap across groups; setup and shared Git operations are serialised. A command’s optional skipFor exclusions apply only when every updated dependency matches; mixed or unknown groups retain checks. The first ready group takes the publication slot and publishes one checked commit without creating PRs or waiting for hosted CI. Host permissions are read from $XDG_CONFIG_HOME/dot/dependencies.yml (default ~/.config/dot/dependencies.yml), keyed by owner/repository with trusted and allowBypass booleans. Required hosted checks must have equivalent validation.checks mappings; protected direct pushes require explicit allowBypass permission and existing account rights. Workflow edits require a credential with workflow write access. Unsupported policy remains blocking. Git-backed claims serialise each repository/target across machines and service or manual runs. Publication atomically advances the ownership record and target; target movement rebuilds and revalidates, up to three attempts per group. Failed work and per-group logs remain under $XDG_STATE_HOME/dot/dependencies. Clean published worktrees are removed, including submodules. Setup/check mutations and commit-hook mutations prevent publication. Independent groups continue after failures, including groups sharing files; a partial run exits non-zero. A normal invocation authorises passing updates, regardless of Renovate automerge policy.

Options

Arguments

Examples

dot deps --dry-run
dot deps owner/repository --dry-run
dot deps --dry-run --all --target main

dot deps service

Run one cross-machine dependency service interval

dot deps service [flags]

Run configured repositories sequentially under one Git-backed service claim. Configuration supplies coordinationRepository, repositories, intervalMinutes and concurrency. Every repository requires host trust. Shared state prevents overlapping machine runs and records the next eligible interval. Repository/target claims also cover manual dot deps runs. Claims renew every 30 seconds and expire after two minutes; a lost claim interrupts work, and dependency publication atomically checks its target claim. State is stored on dedicated dot-deps-state branches. The user timer runs hourly at ten past. Exit status 2 means completed with unsuccessful update groups (warning); 3 means the shared interval was skipped. –no-cooldown ignores the shared interval and each repository’s interval but never an active claim; dot services start dot-deps.timer applies it to that one start automatically. Startup, policy and service failures exit 1. Local configuration validation with –dry-run performs no remote writes. Policy is read from published target commits, so repository policies must be pushed before enabling the service.

Options

Examples

dot deps service --dry-run
dot deps service
dot deps service --no-cooldown

dot deps import-renovate

Import Renovate policy into dot-deps.yml with an editor schema

dot deps import-renovate [flags] [<directory>]

Create dot-deps.yml and its editor schema from a repository’s JSON Renovate config, migrating an existing dot-deps.json policy. The first import resolves presets with an isolated, pinned Renovate runtime. Later imports replace explicit override sections, including edits within them, while preserving the native base policy and local check mappings. Unsupported settings are recorded as publication blockers. Importing creates no commits or PRs. Ordinary previews use the saved native policy without running Renovate or refreshing presets.

Options

Arguments

Examples

dot deps import-renovate
dot deps import-renovate /path/to/repository

dot run

Run a command with a deadline and process-group cleanup

dot run [flags] <command> [<args...>]

Pass the executable and its arguments after –. Standard input, output and errors are inherited. Completion, timeout and SIGINT/SIGTERM/SIGHUP all release the owned process group, first with SIGTERM and then SIGKILL after the cleanup grace period. Use foreground commands: processes that deliberately leave the group or send work to an existing server are outside this ownership. For isolated OpenCode jobs, pass run –standalone.

Options

Arguments

Exit codes

Child exit code on completion
124  Execution deadline exceeded
125  Process execution failed
128 + signal number on interruption

Examples

dot run --timeout '5 minutes' -- opencode2 run --standalone 'Process this capture'

dot updates

Check watched package and Dotfiles updates for the status bar

dot updates <subcommand> [flags]

Read cached status immediately and refresh it in the background after 15 minutes. Refresh checks watched repository/AUR packages and all dot-managed repositories, writes the cache atomically under a shared lock, and notifies the Omarchy shell. Scheduled refreshes respect AUR HTTP-error backoff; manual refreshes retry immediately. Use –package-file, –cache-dir, –timeout, and status –cache-max-age to override defaults.

Options

Examples

dot updates status
dot updates refresh

dot updates status

Print cached status-bar JSON and refresh stale data in the background

dot updates status [flags]

Options

Examples

dot updates status

dot updates refresh

Refresh package and Dotfiles status and notify the shell

dot updates refresh [flags]

Options

Examples

dot updates refresh
dot updates refresh --dot-only

dot services

Monitor registered systemd user services and timers

dot services <subcommand> [flags]

Each job registers itself with a YAML descriptor in ~/.config/dot/services.d/, shipped by the stow package that owns the unit. A descriptor names the unit and its monitoring policy: label, history, failAfter (consecutive failures before a job counts as failed), staleAfter (a duration such as “1 hour”; not reported until the first run after boot or resume), restartLimit ({ count, within }) for long-running services, notify, logs ({ dir, file }) for jobs that keep their own run logs, and repository (a GitHub owner/repo slug from dot-git.yml) naming the repository that logs and agents open in. A long-running service can add status ({ file }) pointing at a JSON file it writes with health (“ok”, “warning”, “degraded” or “failed”), summary and updated (epoch milliseconds); while systemd sees the service as healthy, a report from its current run replaces the health and summary. Without repository, the repository containing the unit’s executable is used, falling back to the public dotfiles. Optional exitStatuses maps non-zero exit codes to “warning” or “skipped”, for example { “2”: “warning”, “3”: “skipped” }. Warnings break the failure streak and count as completed work for staleness; skipped invocations retain the last completed outcome. These are monitor classifications; systemd still records non-zero exits. Run history comes from the user journal. Units with OnFailure=dot-service-failed@%n.service call dot services notify, which raises a desktop notification once failAfter is reached and refreshes the timmo.services panel.

Options

Examples

dot services status
dot services logs dot-deps.timer

dot services status

Show the health of registered user services

dot services status [flags]

Options

Examples

dot services status
dot services status --json

dot services start

Run a registered job now, or restart a long-running service

dot services start [flags] <unit>

Options

Arguments

Examples

dot services start dot-deps.timer

dot services logs

Open a registered job’s logs in a Herdr tab for the repository that owns it

dot services logs [flags] <unit>

Options

Arguments

Examples

dot services logs notes-capture-daemon.service

dot services run-logs

Print the journal output of a registered job’s most recent runs, newest first, with its latest run log

dot services run-logs [flags] <unit>

Options

Arguments

Examples

dot services run-logs dot-deps.timer
dot services run-logs skill-updates-agent.timer --count 5 | wl-copy

dot services investigate

Open an agent in a registered job’s repository, briefed with its recent runs, logs, file locations and commands to investigate them

dot services investigate [flags] <unit>

Options

Arguments

Examples

dot services investigate skill-updates-agent.timer --agent opencode2

dot services notify

Notify when a registered job has failed (used by OnFailure=)

dot services notify [flags] <unit>

Options

Arguments

Examples

dot services notify dot-deps.service

dot fans

Control chassis fans from a Home Assistant temperature

dot fans <subcommand> [flags]

Reads ~/.config/dot/fans.yml: entity (a Home Assistant temperature sensor), device (a liquidctl –match string), channels (a list such as fan1 and fan2), ramp ({ from, to } in °C) and speed ({ min, max } in percent). Watches the entity through ha-bridge and ramps the channels linearly from speed.min at ramp.from to speed.max at ramp.to, in 5% steps. An unavailable or non-numeric reading, no reading within 30 seconds, or a stopped watcher sets speed.max until readings resume; the watcher restarts after 15 seconds. Health is written to $XDG_STATE_HOME/dot/fans/status.json for the status field of a dot services descriptor. Stopping hands the device back to motherboard control with liquidctl initialize.

Options

Examples

dot fans run

dot fans run

Control chassis fans from a Home Assistant temperature (used by dot-fans.service)

dot fans run [flags]

Options

Examples

dot fans run

dot stow

Re-stow public/private dotfiles

dot stow [flags]

Options

dot omarchy-plugin

Manage Omarchy plugin submodules. The manage-omarchy-plugin compatibility wrapper may pass trailing 0/1 confirmation and commit-offer values to update and remove.

dot omarchy-plugin <subcommand> [flags]

Import, update, or remove Omarchy plugins managed as dotfiles submodules. The Omarchy plugin lifecycle hook calls this command through the manage-omarchy-plugin compatibility wrapper.

sync-components copies the shared panel components in omarchy/.config/omarchy/components into the plugin directories set by omarchy_components entries in the private dot-git.yml, since published plugins cannot import files from dotfiles. Pass –check to report out-of-date copies without writing.

Options

Exit codes

0   Managed operation completed or was skipped
1   Managed operation failed
20  Plugin is unmanaged; continue with Omarchy's normal operation

Examples

dot omarchy-plugin update timmo.clock --yes
dot omarchy-plugin remove timmo.clock
dot omarchy-plugin sync-components --check

dot omarchy-plugin add

Import a validated plugin checkout

dot omarchy-plugin add [flags] <id> <url> <checkout>

Options

Arguments

dot omarchy-plugin update

Update one or all managed plugins

dot omarchy-plugin update [flags] [<id>] [<confirm>]

Options

Arguments

dot omarchy-plugin remove

Remove a managed plugin

dot omarchy-plugin remove [flags] <id> [<confirm>] [<save>]

Options

Arguments

dot omarchy-plugin sync-components

Copy shared panel components into standalone plugin checkouts

dot omarchy-plugin sync-components [flags]

Options

dot session-status

Query an OpenCode 2 session’s model, variant and context pressure

dot session-status [flags] <session-id>

Read-only OpenCode 2 session inspection through the configured launcher. Pass the exact session ID supplied in the agent’s environment context; it is not inferred from the focused pane, working directory or a guessed shell variable. Reports the selected model and variant, supported variants, model limits, latest completed assistant token measurement, its age, the latest completed compaction, and separately labelled cumulative usage and cost. Context tokens include non-cached input, cache reads and writes, output and reasoning, matching OpenCode’s display. Input usage includes non-cached and cached input. Pressure uses whichever percentage is higher: context-window usage or input-limit usage. Current usage is unknown after compaction without a new measurement, after a model/variant switch, or with a staged revert. Later tool results and messages are not counted. Looks back through at most 20 messages per type and marks incomplete lookups. –warn-at defaults to 70 percent: a workflow heuristic, not a proven cognitive degradation threshold. The command does not change models, compact or open sessions.

Options

Arguments

Examples

dot session-status ses_example --json
dot session-status ses_example --warn-at 80

dot snapshot

Save a CPU and memory snapshot with process rankings

dot snapshot [flags]

Print a Markdown CPU and memory summary with a usage-filtered process tree. –sort mem defaults to an 80 MiB measured subtree PSS cutoff; –sort cpu defaults to 1% of one core. Adjust these with –min-memory-mib and –min-cpu. Each tree row shows aligned memory and CPU totals beside the process name. Totals include hidden children, so small workers can qualify together; parent and child totals overlap. Expand the largest remaining qualifying branch until –limit visible processes are reached (default: 40, including ancestors). Zero-usage branches are omitted. The saved report adds CPU, memory and process-name rankings with the same cutoffs and per-table limit, plus pressure measurements. Interactive human runs open it in $EDITOR (vi if unset). The internal dot is-agent check automatically selects JSON. JSON retains all sampled processes and the complete processTree, and reportSelection identifies visible PIDs, cutoffs, the limit and omitted count. Missing measurements are null; unavailable parents are marked. CPU is sampled over approximately one second; 100% per process means one logical CPU. PSS divides shared pages between processes. Reports are saved in the system temporary directory ($TMPDIR, normally /tmp), named dot-snapshot-.md or .json. Existing output files are never overwritten.

Options

Examples

dot snapshot
dot snapshot --sort cpu
dot snapshot --limit 40
dot snapshot --min-memory-mib 50

dot omarchy-shell-config

Regenerate the Omarchy shell layout

dot omarchy-shell-config [flags]

Regenerate ~/.config/omarchy/shell.json from Omarchy’s shipped default and the host-specific dotfiles layout without running the full stow flow.

Options

Examples

dot omarchy-shell-config

dot firewall

Reconcile managed ufw firewall rules

dot firewall [flags]

Ensure the managed ufw allow rules are present with their exact source, destination, interface/direction, and purpose comment. Missing rules are added, stale-comment rules are deleted and re-added, then ufw is reloaded once. A source-restricted rule does not satisfy a managed any-source rule.

Options

Examples

dot firewall

dot doctor

Run parallel health checks for dependencies, repositories, stow integrity, services, packages, browser configuration, hardware video, firewall rules, and OpenCode/Herdr integration. A timestamped report is always written under ~/.local/state/dot/logs/.

dot doctor [flags]

Run health checks on the dotfiles system. All checks run in parallel and each section streams to the terminal as it finishes, followed by a grouped summary. A timestamped log is always written under ~/.local/state/dot/logs/.

Options

Checks performed

Dependencies and configured gh extensions
Repositories, origin HEAD, git config, and stow integrity
OpenCode, Herdr, notifications, timers, and UWSM integration
Omarchy host links, browser flags/extensions, and hardware video
Public/private packages, pacman hooks, and managed firewall rules

Exit codes

0  No critical errors (warnings may still be present)
1  One or more critical errors found

dot clean

Unstow managed dotfiles

dot clean [flags]

Options

dot agents-sync

Mirror AGENTS.md to agent harness instruction files

dot agents-sync [flags]

Options

dot notes-capture-sync

Sync watched repositories to the notes capture picker

dot notes-capture-sync [flags]

Regenerate the notes capture repository picker from repositories with GitHub notifications enabled in the private dot-git.yml configuration. Updates only CAPTURE_REPOSITORIES in the ignored capture/wrangler.local.jsonc file, creating it from the deploy template when needed. Mirrors non-secret settings from the active Worker, then deploys when the live picker differs.

Options

Examples

dot notes-capture-sync

dot setup-private-repo

Sync and register the private pacman repository

dot setup-private-repo [flags]

Sync the private Arch package repo mirror, write the private pacman repo snippet, and add the Include line to /etc/pacman.conf when it is missing. This repairs Omarchy pacman.conf refreshes that remove local repository includes. Privileged writes prefer pkexec and fall back to sudo.

Options

Examples

dot setup-private-repo

dot setup-public-repo

Trust and register the public timmo pacman repository

dot setup-public-repo [flags]

Download the public signing key, require its pinned full fingerprint, locally sign it in pacman’s keyring, and register the signed [timmo] repository before the other package repositories. The command fails before changing trust or pacman configuration when the repository is unavailable or the downloaded fingerprint does not match.

Options

Examples

dot setup-public-repo

dot git-diff

Aliases: dot diff

Show repository change state across all tracked repositories.

dot git-diff [flags]

Modes

(default)       Text summary of repos with changes
--bar-json      JSON output for status bars
--panel-json    Full JSON panel snapshot

Options

Examples

dot git-diff
dot git-diff --bar-json
dot git-diff --panel-json

dot git-log

Show recent commits across managed repositories

dot git-log [flags]

Lists the latest commits on each managed checkout’s branch, including fetched upstream commits that are not pulled yet. Results are cached per repository and only re-read when HEAD or the upstream ref moves; –refresh re-reads everything.

Options

Examples

dot git-log
dot git-log --panel-json

dot git-web

Open a Git web action using the repository’s configured browser

dot git-web [flags]

Resolves repository browser settings from dot-git.yml, including linked worktrees. URL-only actions use the GitHub repository in the URL. Named browsers are argument lists under browsers; each repository can select one with browser. Without a selection, uses the desktop default. –work-time selects the work browser during work hours outside calendar leave, otherwise the desktop default. –browser overrides the selection. The Git panel uses –work-time for web actions and –browser work for Alt+Enter and Alt+click.

Options

Examples

dot git-web
dot git-web --browser work
dot git-web --url https://github.com/example/project/issues/1

dot git-commit

Commit staged changes through the guarded gateway. Subjects must be one line, have no trailing full stop, and stay within the hard length limit. Explicit –path scopes never imply git add -A; –amend keeps the existing message unless –message is supplied.

dot git-commit [flags]

Create a commit through dot’s guarded gateway instead of raw git commit. The subject is validated as a single line with no trailing full stop and a length limit, then the staged set (or an explicit –path scope) is committed. It never runs git add -A.

Pass –amend to rewrite the previous commit instead of creating a new one; it keeps the existing message unless you pass –message. With –push, an amend force-pushes with –force-with-lease, never a plain force.

In repositories opted into agent Oxlint, the files being committed are linted and only findings on added or modified lines are reported. Warnings print and the commit continues; errors refuse the commit until they are fixed or –skip-agent-oxlint is passed. Agents are routed here by the git-commit skill and blocked from raw git commit in the OpenCode permission config.

Modes

(default)  Commit the staged set
--path     Commit only named files
--amend    Rewrite the previous commit
--dry-run  Preview the plan without changes

Options

Message guards

Single line      Rejects multi-line messages
No em/en-dash    Rejects em/en-dashes; use a hyphen
No full stop     Rejects a trailing full stop
Warn over 60     Warns on stderr, still commits
Reject over 120  Fails; shorten the subject

Base branch guard

Refuses commits to the base branch of a repo you do not own.
Owners you control are listed in git config dot.owner. Work on a feature branch.
For a maintained fork with an owned origin, opt in one exact branch with git config --local dot.maintainedForkBranch <branch>.
The exception requires owned origin fetch and push targets; global settings are ignored.

Examples

dot git-commit -m "Add commit gateway"
dot git-commit -m "Scope to one file" --path src/git/commands/Status.ts
dot git-commit -m "Commit and push" --push
dot git-commit --amend
dot git-commit --amend -m "Reword the previous commit"
dot git-commit -m "Preview only" --dry-run

dot git-notifications

Open the authenticated GitHub notification inbox. Without output, query or action flags, this opens the Omarchy shell panel. –all and –participating return filtered bar JSON.

dot git-notifications <subcommand> [flags]

Modes

(default)       Open the shell notification panel
--bar-json      Status-bar JSON

Options

Examples

dot git-notifications
dot git-notifications --bar-json
dot git-notifications --participating
dot git-notifications dismiss --dry-run
dot git-notifications --mark-read 12345

dot git-notifications dismiss

Show a coloured repository summary, then review merged dependencies followed by remaining unread notifications. Done queues work in the background while progress appears above the next choices. Every repository offers Done, Open on GitHub, Skip and Stop. Stop ends the questions and finishes queued work before a completion and issues summary. –repo selects a single notification stack. Bar hiding preferences do not restrict this inbox.

dot git-notifications dismiss <subcommand> [flags]

Options

Examples

dot git-notifications dismiss
dot git-notifications dismiss --repo owner/repository
dot git-notifications dismiss --dry-run
dot git-notifications dismiss dependencies --mode all
dot git-notifications dismiss remaining

dot git-notifications dismiss dependencies

Review unread merged Renovate/Dependabot updates regardless of CI results. All-mode excludes unverifiable CI. Opening GitHub returns to the review without dismissing anything.

dot git-notifications dismiss dependencies [flags]

Options

dot git-notifications dismiss remaining

Review all other unread notifications per repository, including PRs with unresolved CI and their reasons. This pass always requires a choice before dismissal.

dot git-notifications dismiss remaining [flags]

Options

dot git-releases

Compare enabled repositories with their latest published stable release, explain impact and retain local reviews.

dot git-releases <subcommand> [flags]

Read the last local snapshot, collecting one on first use. –refresh fetches immutable release and branch refs immediately; –scheduled follows each repository’s local-time cron and records attempted minutes. Draft and prerelease releases are excluded. Before the first stable release, the comparison covers the full history with the same quiet rules, and the first version is 0.1.0 (1.0.0 for a major impact), today’s CalVer or the upstream fork base. Failed checks retain previous evidence marked stale. Quiet changes remain inspectable. Desktop notifications require –notify and honour configured minimum impact and cooldown. –open opens the release review, optionally selected by –repo, without fetching.

Local reviews require the displayed snapshot ID. Finding overrides follow exact evidence; an overall override follows the release-relevant comparison. Changed evidence invalidates its review. Use –impact auto to clear an override. Extra CI-only commits do not repeat delivery. Incomplete or stale evidence cannot be reviewed.

Options

Policy

Optional releases config selects oxlint-rules or system-bridge and a watched branch.
Private overrides precede preset rules; the first match wins for each fact.
Match paths with globs, change_types, exact dependencies, roles, submodules or explicit subjects regexes.
Selectors are ANDed; values within each selector are ORed. Explicit path overrides match either rename endpoint.
Preset rename impact is the highest affected old/new boundary; both endpoints must be quiet for a quiet rename.
Subject selectors follow surviving source lines or individual structured values, excluding reverted intent.
Each net fact is classified once; any attributed subject can match the first applicable ordered rule.
Every override supplies impact (none/patch/minor/major) and a readable reason.
Dependency versions never imply consumer minor or major changes.
Notification enabled/minimum_impact/cooldown_minutes are stored for future explicit delivery.

Examples

dot git-releases
dot git-releases --refresh --panel-json
dot git-releases --scheduled --notify --panel-json
dot git-releases --open --repo example/project
dot git-releases review --repo example/project --snapshot ID --finding FINDING --impact patch
dot git-releases review --repo example/project --snapshot ID --impact auto
dot git-releases publish --repo example/project --snapshot ID --notes-file notes.md
dot git-releases publish --repo example/project --snapshot ID --notes-file notes.md --notes-mode replace --confirm PLAN

dot git-releases review

Review exact local release evidence without publishing anything

dot git-releases review [flags]

Options

dot git-releases publish

Preview version changes, validation, pushes and release notes. –interactive explains and confirms in the terminal; –confirm PLAN executes a reviewed plan with live progress. –notes-file supplies hand-written notes.

dot git-releases publish [flags]

Requires an explicit private releases.publish recipe. The preview is read-only. Confirmation binds the reviewed snapshot, version files, commands and target. Preparation runs in an isolated worktree. Only agreed version changes, plus any releases.publish.generated_files the commands regenerate (such as a lockfile), are committed through dot git-commit, then the version commit and tag are pushed atomically. GitHub release notes are generated from the previous stable release (or the full history for a first release), unless –notes-file supplies hand-written notes. The file must exist and not be empty; its text is shown in the preview and bound to the plan, so pass the same –notes-file on confirmation and an edited file needs a new preview. –notes-mode prepend (default) puts the file before the generated notes, editing the release straight after creation; replace uses only the file. Progress includes command output and a saved log. Release creation does not wait for GitHub publication jobs; follow the returned Actions URL. Failed preparation is retained for inspection. Refresh and preview again after resolving a failure.

Options

dot git-pull-requests

Track open pull requests for enabled repositories, independently of GitHub notifications

dot git-pull-requests [flags]

Opt in with pull_requests.enabled in private dot-git.yml. Open PRs include drafts and automation, ordered by latest update. Use –repo –ignore to hide a PR locally from the panel and all PR counters. Successful refreshes remove ignored entries once they close, merge or disappear. A non-draft PR is ready when at least one CI check passes and none fail, remain pending or are cancelled; failed check names are shown in the panel. Queries fetch at most every five minutes unless –refresh is supplied. Failed fetches retain the last successful list and ignore entries, and report an error.

Options

Examples

dot git-pull-requests --panel-json
dot git-pull-requests --refresh
dot git-pull-requests --open

dot mcp-sync

Regenerate MCP configs for all harnesses from the spec

dot mcp-sync [flags]

Regenerate each active harness’s native MCP config from the private spec (mcp.yml). Repository opencode_mcp lists in dot-git.yml opt into named servers using generated, Git-ignored .opencode/opencode.jsonc files; removing an opt-in removes its generated config. Existing unowned or tracked configs are preserved and reported as conflicts. Global configs are written into the stowed private source tree; run dot stow after. Some agent harnesses are documented stubs and are not written.

Options

Examples

dot mcp-sync

dot private-pkg-publish

Build and publish a private package

dot private-pkg-publish [flags] <package-name>

Build and publish a mapped private package into the private pacman repo.

Options

Arguments

Examples

dot private-pkg-publish twitch-notifications --install
dot private-pkg-publish --skip-build --no-git twitch-notifications

dot skills

Maintain imported agent skills

dot skills <subcommand> [flags]

Options

dot skills validate

Validate the standalone skills repository

dot skills validate [flags]

Options

dot skills import

Import or refresh a reviewed skill snapshot

dot skills import [flags] <name>

Options

Arguments

dot skills updates

Check/apply imported skill updates

dot skills updates [flags]

Options

Examples

dot skills updates --json
dot skills updates --update --skill browser-control --no-commit

dot skills check

Check adapted imports against upstream

dot skills check [flags]

Options

Examples

dot skills check --skill browser-control

dot skills updates-agent

Run skill update automation

dot skills updates-agent <subcommand> [flags]

Options

dot skills updates-agent github

Run GitHub skill update automation

dot skills updates-agent github [flags]

Options

dot skills updates-agent device

Run local device skill update automation

dot skills updates-agent device [flags]

Options

dot completions

Generate shell completions

dot completions [flags] [<shell>]

Generate the managed dot and skill-maintenance completion files for the selected shell so the next dot stow installs them.

Options

Arguments

Examples

dot completions zsh
dot completions bash
dot completions fish

dot is-agent

Detect whether an AI coding agent is running dot

dot is-agent [flags]

Detect whether dot is running under an agent harness from agent environment variables, falling back to a Linux /proc process-ancestry check. Exits 0 when an agent is detected and 1 otherwise, so scripts can branch with if dot is-agent. Set DOT_AGENT=1 to force detection on or DOT_AGENT=0 to force it off.

Modes

(default)  Print the detected agent, or a no-agent message
--quiet    Print only the provider id (nothing when no agent)
--json     Print the detection result as JSON

Options

Examples

dot is-agent
dot is-agent --quiet
dot is-agent --json
dot is-agent && echo running under an agent

dot repo

List and induct tracked repositories in private dot-git.yml

dot repo <subcommand> [flags]

Options

dot repo list

List tracked repositories and shortcuts from private dot-git.yml

dot repo list [flags] [<query>]

Read-only lookup of the repositories and path shortcuts configured in private dot-git.yml, the same list behind the prefix+s picker and repository shortcuts. Reads the config directly, so it does not depend on the generated picker cache. Each entry reports name, path, github (null for shortcuts), aliases, kind, whether the checkout exists and whether it is the deepest tracked path containing the working directory. Each entry also reports herdr: live state from the shared Herdr server (HERDR_SOCKET_PATH or the default socket), with open, the workspaces labelled with the repository name or inside its worktrees (id, label, focused, tabCount, paneCount, agentStatus, checkoutPath, linkedWorktree), and the agents running in them (name, agent, status, workspaceId, paneId, focused, cwd). herdr is null when the server cannot be reached; agent status is a snapshot. A query matches name, aliases, GitHub slug or repository name, and path, case-insensitively, with exact matches first. Prints JSON with –json or when run under an AI agent, otherwise an aligned table. Exits 1 when a query matches nothing, and fails when private config is unavailable or invalid.

Options

Arguments

Examples

dot repo list
dot repo list notes
dot repo list arch-repo --json

dot repo search

Fuzzy-search tracked repositories and shortcuts

dot repo search [flags] <query...>

Ranks tracked repositories from private dot-git.yml by fuzzy match on name, aliases, GitHub repository name, GitHub slug, directory name and path (path matches count for less). Each whitespace-separated term must match some field, with typo and partial-word tolerance loose enough for ambiguous queries, though a term found only inside other words (her in weather) scores lower; matches under 40 or more than 20 points below the best are dropped. Returns the top 5 by default; use –limit to change that or –all for every close match, such as a whole group of repositories. Results carry the same fields as dot repo list, including herdr, plus score (1 to 100) and matched (the fields that matched), highest score first. JSON is { results, hint }, where hint says how many more matches –limit or –all would show and is omitted when there are none; the table ends with the same hint. Prints JSON with –json or when run under an AI agent, otherwise an aligned table. Exits 1 when nothing matches.

Options

Arguments

Examples

dot repo search pacman
dot repo search omarchy clock
dot repo search notse --limit 3 --json
dot repo search ha --all

dot repo induct

Induct a local repository into private dot git config with a preview before committing

dot repo induct [flags] [<path>]

The terminal wizard asks for Normal (first and default) or Home Assistant, then every repository field using private dot-git-presets.yml defaults and local Git identity. Flags prefill the wizard. With –noninteractive, flags override preset defaults and the command only previews; repeat the reviewed options with –commit to save. Each run validates the complete config and shows the exact diff. The config must be tracked and clean; active commit hooks are refused. Existing entries and formatting are preserved. Commits through dot git-commit without pushing or including unrelated staged files. Repositories already inducted are rejected; use agent-oxlint –opt-in to enable their agent pass.

Options

Arguments

Examples

dot repo induct
dot repo induct ~/repos/example --noninteractive --preset normal --name Example --aliases example
dot repo induct ~/repos/example --noninteractive --preset normal --name Example --aliases example --commit

dot agent-oxlint

Run the advisory generic Oxlint pass on JavaScript and TypeScript changes in an opted-in repository. Repository-owned Oxlint takes precedence. Use –changed normally, explicit paths to lint whole files, or –all when explicitly requested. Pass –force to run despite those skips.

dot agent-oxlint [flags] [<path...>]

Run the generic @timmo001/oxlint-rules recommended config from a dot-managed cache without changing the target repository. The current repository must set agent_oxlint: true in private dot-git.yml. Repositories with their own Oxlint config, dependency, script, or local binary are skipped because their local setup takes precedence. Pass –force to run anyway. Diagnostics are advisory and do not make these personal rules authoritative for the host repository. –changed compares the working tree and untracked files with HEAD, prints only findings on added or modified lines, and exits non-zero when any remain. Paths with –changed limit that comparison to those files or directories. dot git-commit runs the same check on the files it commits.

Modes

--changed  Lint uncommitted changes, reporting only changed lines; add paths to narrow
<path>...  Lint explicit files or directories in full
--all      Lint the complete repository tree
--force    Run even if opt-in or repository Oxlint would skip
--opt-in   Enable and commit the existing config entry; add paths or --all to also lint

Options

Arguments

Opt-in

--opt-in adds or sets only agent_oxlint: true in an existing private repository entry, preserving all other bytes. If the entry is missing, it offers the repo induct wizard with agent Oxlint prefilled as enabled. Without a terminal it prints induction instructions. The config must be tracked and clean. Active commit hooks are refused rather than bypassed so formatters cannot expand the change. Commits through dot git-commit without pushing; unrelated staged files are excluded. An existing opt-in creates no commit.

Examples

dot agent-oxlint --changed
dot agent-oxlint --changed src/example.ts
dot agent-oxlint src/example.ts
dot agent-oxlint src/one.ts src/two.ts
dot agent-oxlint --all
dot agent-oxlint --force src/example.ts
dot agent-oxlint --opt-in

dot agent-lint

Run the repository’s agent_lint commands from private dot-git.yml on changed files

dot agent-lint [flags] [<path...>]

Collect files changed in the working tree against HEAD, plus untracked files that are not ignored, and run each configured agent_lint command from the repository root under dot run –timeout. Deleted files and submodule changes are left out. Paths narrow the changed files. A run argument of exactly {files} expands to the changed files matching the command’s include globs; commands without it run as they are, but only when a changed file matches. Each result is passed, failed, timed-out or skipped, with the last lines of output for failures. Exits non-zero when any command fails or times out. Repositories without agent_lint print a notice and exit zero.

Options

Arguments

Examples

dot agent-lint
dot agent-lint --json
dot agent-lint src/one.ts src/two.ts --json

dot pr

Watch, read reviews on and queue pull requests

dot pr <subcommand> [flags]

Options

dot pr watch

Watch pull request runs, checks and reviews, streaming progress and a full report

dot pr watch [flags] [<pr...>]

Follow every GitHub Actions run on each pull request’s head commit, including Copilot code review runs, plus external status checks. Superseded runs of the same workflow on the same commit are ignored, and a new push moves the watch to the new head. Progress streams to stdout one line per event; failed job logs and the final review dump go to a Markdown report whose path is printed first and last. Failed jobs are reported as soon as they finish, even while the rest of the run continues. The watch ends after two settled polls, waiting up to five more minutes for requested bot reviews. The review dump lists reviews newest first, unresolved threads with every comment in full, and resolved or minimized threads with only their replies. The command never changes the pull request. Designed for OpenCode 2 background shells: the completion notification carries the short summary and the report holds the detail.

Options

Arguments

Exit codes

0    Everything finished and passed
1    A job or check failed, or the watch could not start
3    Stopped early by --stop-on while other work was still pending
124  Timed out

Examples

dot pr watch
dot pr watch --stop-on failure
dot pr watch 54322 54325 54328 --repo home-assistant/frontend

dot pr reviews

Print a pull request’s reviews and review threads once

dot pr reviews [flags] [<pr...>]

Fetch each pull request’s latest reviews, every review thread with its comments, and bot reviews still requested, then exit. Markdown matches the review dump in dot pr watch reports: reviews newest first, unresolved threads with every comment in full, and resolved or minimized threads with only their replies. –json prints { pullRequests } with number, title, url, owner, name, repo, head, openThreads, botRequests, reviews and threads for each pull request. Read-only; exits 1 when a pull request cannot be resolved or fetched.

Options

Arguments

Examples

dot pr reviews
dot pr reviews --json
dot pr reviews 54322 54325 --repo home-assistant/frontend

dot pr queue

List reviewable pull requests and what was opened, merged or closed recently

dot pr queue [flags]

Run the repository’s review_search from private dot-git.yml (or –search) and classify each pull request deterministically: size from changed lines, failing and pending checks, latest reviews, review decision, unresolved review threads by author, labels, comment count and first-time contributors. –reviewable searches beyond the saved filter, includes PR descriptions, recent comments and thread text, and leaves judgement of those comments to the reviewer. –threads adds each unresolved thread’s comments for the saved search. Effort groups are small (up to 150 changed lines), medium (up to 400) and large; a failing check or requested changes makes a pull request not ready. The activity window lists every pull request merged, closed without merging or opened since –since, newest first, with size and labels, plus the net change in open pull requests. Read-only.

Options

Examples

dot pr queue
dot pr queue --only queue --reviewable --json
dot pr queue --only activity --since 2026-09-19
dot pr queue --sort updated --since 3d --json

dot launch-floating-webapp

Launch one Omarchy webapp and place its new window in the target monitor’s bottom-right corner, or reposition an existing window with –address. Width and height must be positive integers; margins must be non-negative.

dot launch-floating-webapp [flags] [<url>]

Options

Arguments

Exit codes

0  Window placed and its address printed
1  Launch detection, Hyprland query, or placement failed
2  Invalid arguments

dot herdr

Manage the shared Herdr server and repository workspaces

dot herdr <subcommand> [flags]

Options

dot herdr start

Start the default Herdr server with the desktop autostart launch context

dot herdr start [flags]

Options

dot herdr stop

Stop the default Herdr server only when its panes are idle shells. Run outside Herdr; –check also works inside it. Lists active agents, commands, and background jobs, then exits if blocked.

dot herdr stop [flags]

Options

Examples

dot herdr stop --check
dot herdr stop

dot herdr restart

Restart the default Herdr server only when its panes are idle shells. Run outside Herdr; –check also works inside it. Lists active agents, commands, and background jobs, then exits if blocked.

dot herdr restart [flags]

Options

Examples

dot herdr restart --check
dot herdr restart

dot herdr repo-open

Open or focus a repository workspace in the shared Herdr session, attaching a tiled terminal when needed. Commands reuse an idle shell pane by default, checking the focused pane, other panes in its tab, then other tabs before splitting right. –layout vertical always splits right, horizontal splits below, and tab always opens a new tab. –modifiers selects the same behaviour from Qt click/Enter modifiers, with Ctrl taking priority over Alt, then Shift. Placement flags are mutually exclusive. Use –agent to resolve the launcher, label and kind from dot herdr agents; it cannot be combined with a command or –agent-kind. With –agent opencode2, –model creates an OpenCode session on a uniquely matched model before launching the full TUI and sending any prompt. Agent launches wait for readiness and verify the selected kind before naming or prompting. –prompt-file reads the prompt from a file before anything is launched and cannot be combined with –prompt. –no-focus leaves the current view alone. –json reports resource IDs, creation flags, agent details, model and whether the prompt was sent. Without a command or –agent, focus the workspace; an empty command opens a shell using the selected layout.

dot herdr repo-open [flags] <label> <directory> [<tab-label>] [<command>]

Options

Arguments

Exit codes

0  Repository workspace focused or opened
1  Herdr operation failed
2  Invalid arguments

dot herdr model

Switch the model and variant of an existing Herdr OpenCode 2 agent. Validates the model with opencode2 models and any #variant or –variant against the project’s model catalogue before updating the session through the API. Omitting the variant selects the model’s default settings. Does not send a prompt or interrupt a request already in progress.

dot herdr model [flags] <target> <model>

Options

Arguments

dot herdr context

Show context for a locally attached Herdr terminal

dot herdr context [flags]

Shows the selected workspace, tab, pane, directory and Git repository while a local foreground terminal client is connected to the selected Herdr session. Desktop window focus is not required. JSON uses attached: false and null context fields when no terminal is attached. Without –session, uses the SDK’s HERDR_SOCKET_PATH, HERDR_SESSION and default socket selection. Local Linux process and socket checks do not detect remote clients. Probe failures exit non-zero with an error on stderr. –watch emits changed context as newline-delimited JSON, following workspace, tab and pane events with a 30-second fallback. Send refresh followed by a newline on stdin to collect and emit context even when unchanged. Watch failures emit null and an error on stderr; dropped connections reconnect automatically.

Options

Examples

dot herdr context
dot herdr context --json
dot herdr context --watch --json
dot herdr context --session default

dot herdr agents

List installed agent targets shared by repository and release pickers

dot herdr agents [flags]

Options

dot workspace-setup

Launch or reuse desktop apps and rebuild the workspace layout

dot workspace-setup [flags]

Options

Examples

dot workspace-setup
dot workspace-setup --mode=work
dot workspace-setup --mode=normal

dot workspace-relayout

Apply or capture a Hyprland workspace layout

dot workspace-relayout [flags]

Options

dot help

Show this help menu

dot help [flags] [<command>]

Options

Arguments