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 update system print the summary last.

dot update <subcommand> [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, installs mise tools, restarts pitchfork daemons still running an old mise binary, updates Pi extensions, rebuilds again, runs agents sync, backfills the init marker, reloads agents (as dot reload agents), and refreshes shell modules. It never restarts the shell: the running shell applies a changed generated config or deployed Omarchy plugin itself. 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 agent 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 update system

Run omarchy update, which then runs the Dotfiles and Topgrade updates

dot update system [flags]

Hand over to omarchy update. Its post-update hook runs dot update system –omarchy-hook, which selects and runs the other steps in order: Dotfiles, GitHub CLI extensions, and Topgrade, while Omarchy still holds its sudo authorisation, so the whole update asks for the password once. Interactive runs pre-select Dotfiles and GitHub CLI extensions; Topgrade steps start unselected. Non-interactive runs and –yes select every step. Cancelling the prompt skips them.

–step runs only the steps given, here and without omarchy update.

Options

Examples

dot update system
dot update system --yes
dot update system --step dotfiles --step github-cli

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, except between 01:00 and 07:00. 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

Import dependency policy from other tools

dot deps import <subcommand> [flags]

Options

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 http

Local HTTP helpers

dot http <subcommand> [flags]

Options

dot http forward

Forward HTTP and websockets to another server without proxy headers

dot http forward [flags]

Listens on 127.0.0.1 and forwards HTTP requests and websockets to the target origin, dropping Host and X-Forwarded-* headers so a server that doesn’t trust this machine as a proxy accepts them. Use it behind a local HTTPS proxy, such as a pitchfork daemon, to reach a plain HTTP server from an HTTPS page. With –cors-origin and –cors-suffix, requests from an HTTPS origin under the suffix reach the target as coming from –cors-origin, and the allowed origin in the response is set back to theirs, for targets whose CORS list only matches exact origins.

Options

Examples

dot http forward --port 8126 --target http://homeassistant.local:8123
dot http forward --port 8126 --target http://homeassistant.local:8123 --cors-origin https://serve.ha-frontend.localhost --cors-suffix .ha-frontend.localhost

dot status

Run work under a pinned terminal status header

dot status <subcommand> [flags]

Options

dot status run

Run a command or pitchfork daemon under a pinned status header

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

Pins a header to the top of the terminal with the state (Setting up, Starting, Running, Done, Stopped or Failed), the URL and the elapsed time, and keeps the terminal title in step with a spinner while work is in progress. –setup runs in an interactive zsh first. With –pitchfork, an already running daemon prompts before restarting (–attach follows it instead), its logs are followed once it is ready, and Ctrl+C stops it. –background returns once the daemon is ready. Without a TTY, state changes print as lines.

Options

Arguments

Examples

dot status run --title 'Lint' -- pnpm lint
dot status run --title 'Core' --url https://dev.example.localhost --setup 'script/bootstrap' --pitchfork core/dev

dot updates

Check watched package, Dotfiles and skills 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, all dot-managed repositories and whether the managed skills checkout is behind timmo001/skills main, writes the cache atomically under a shared lock, and notifies the Omarchy shell. status –json prints the cached sections and the bar and footer output for other readers such as the OpenCode skill-updates plugin. Scheduled refreshes respect AUR HTTP-error backoff; manual refreshes retry immediately. Use –package-file, –cache-dir and –timeout 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 status --json

dot updates refresh

Refresh package, Dotfiles and skills 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”, counted from the latest of the last completed run, the last boot or resume, and one interval before the first calendar run due after those, so sleep, power off and gaps in the schedule are not missed runs), 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. A job can summarise each run by printing a line containing “[RESULT] “ followed by a short outcome; the last such line per invocation becomes that run’s summary in status, run logs, notifications and the timmo.services panel. 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. Timer services with ExecCondition=dot services schedule check run only at their calendar times, or within –grace of one, not as later catch-up runs after boot or resume; those runs show as skipped. dot services start always runs them.

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 stop

Stop a registered job’s running service, leaving its timer scheduled

dot services stop [flags] <unit>

Options

Arguments

Examples

dot services stop notes-capture-daemon.service

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

Inspect a registered job’s recent runs

dot services run <subcommand> [flags]

Options

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 services schedule

Timer schedule checks for registered jobs

dot services schedule <subcommand> [flags]

Options

dot services schedule check

Skip a timer’s catch-up run after boot or resume (used by ExecCondition=)

dot services schedule check [flags]

Options

Examples

dot services schedule check
dot services schedule check --grace '4 hours'

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 hdr

Switch the primary monitor between HDR and SDR

dot hdr <subcommand> [flags]

The primary monitor is HDMI-A-2 on the desktop host and the focused monitor elsewhere. On sets 10-bit output with HDR colour management and doubled SDR brightness, and saves the setting so a Hyprland reload keeps it; off restores 8-bit sRGB. Either does nothing when the monitor is already there. The hdr-on and hdr-off scripts wrap these for launchers that take a script path, such as Heroic’s per-game before and after launch scripts.

Options

Examples

dot hdr on
dot hdr off

dot hdr on

Switch the primary monitor to HDR

dot hdr on [flags]

Options

Examples

dot hdr on

dot hdr off

Switch the primary monitor back to SDR

dot hdr off [flags]

Options

Examples

dot hdr off

dot tunnel

Run shared Cloudflare tunnels on one machine at a time

dot tunnel <subcommand> [flags]

Runs cloudflared with the token in ~/.config/dot/tunnels/.token, checking every 15 seconds which connectors the tunnel has, through the Cloudflare API with the token in ~/.config/dot/tunnels/cloudflare-api-token (Account > Cloudflare Tunnel > Read). The connector whose live connections opened first keeps the tunnel. A machine that finds another connector stops its own cloudflared and waits until none is left, so a laptop that wakes from sleep after another machine took over gives the tunnel back. Health is written to $XDG_STATE_HOME/dot/tunnels//status.json for the status field of a dot services descriptor: ok while serving, warning while another machine holds the tunnel or the API can’t be checked. Without an answer from the API it never starts cloudflared, and keeps a running one going.

Options

Examples

dot tunnel run timmo

dot tunnel run

Run a Cloudflare tunnel on one machine at a time (used by dot-tunnel@.service)

dot tunnel run [flags] <name>

Options

Arguments

Examples

dot tunnel run timmo

dot stow

Re-stow public/private dotfiles

dot stow [flags]

Options

dot omarchy

Manage Omarchy plugins and the shell layout

dot omarchy <subcommand> [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.

For a repository that keeps its plugin in a subfolder, pass add –path with that folder. The submodule holds the whole repository, and the registry’s path entry tells stow and update which folder to validate and deploy.

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

Sync shared files into plugin checkouts

dot omarchy plugin sync <subcommand> [flags]

Options

dot omarchy plugin sync components

Copy shared panel components into standalone plugin checkouts

dot omarchy plugin sync components [flags]

Options

dot omarchy shell

Manage the Omarchy shell

dot omarchy shell <subcommand> [flags]

Options

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 session

Inspect and move agent sessions

dot session <subcommand> [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. Without a session ID it reads the current session: $OPENCODE_SESSION_ID, which OpenCode sets for its shell and Code Mode tools, else the OpenCode session Herdr reports for this pane. It never guesses from the focused pane or working directory. 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
dot session status ses_example --json
dot session status ses_example --warn-at 80

dot session send

Queue a session on the HA box to pick up on another machine

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

Exports the session and its subagent sessions with opencode2 session export, adds a patch of uncommitted changes (untracked files included) and uploads them over SSH to the queue folder set in ~/.config/dot/session-queue.yml. Attachments are kept relative to the session’s directory, then the home directory, so take restores them to the same place on the other machine without overwriting anything. The original session is left as it is.

Options

Arguments

Examples

dot session send
dot session send ses_example --json
dot session send -a /tmp/opencode/my-task -a screenshot.png

dot session queue

List sessions waiting in the queue

dot session queue [flags]

Options

Examples

dot session queue
dot session queue --json

dot session take

Pick up a queued session on this machine

dot session take [flags] [<entry-id>]

Claims the entry so no other machine can take it, imports the sessions into this machine’s checkout of the same repository, offers to apply the patch when HEAD matches and the tree is clean, then opens the session in its Herdr workspace with a draft prompt pasted in but not sent.

Options

Arguments

Examples

dot session take

dot session remove

Take sessions out of the queue without picking them up

dot session remove [flags] [<entry-id...>]

Moves pending entries to removed/ in the queue folder, so no machine can take them but they can still be recovered by hand. The original sessions are left as they are.

Options

Arguments

Examples

dot session remove
dot session remove 20261029T165219-laptop-ses_example

dot session current

Print the current OpenCode 2 session’s ID

dot session current [flags]

Reads $OPENCODE_SESSION_ID, which OpenCode sets for its shell and Code Mode tools, else the OpenCode session Herdr reports for this pane. Fails when neither names a session.

Options

Examples

dot session current
dot session current --json

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 agent detect 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 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 agent

Agent harness tooling: instruction sync, linting, tools and detection

dot agent <subcommand> [flags]

Options

dot agent sync

Mirror AGENTS.md to agent harness instruction files

dot agent sync [flags]

Mirror _{/.config/opencode/AGENTS.md to each agent harness’s instruction file, then trust each tracked repository from private dot-git.yml in Claude Code (}/.claude.json) so it opens without the workspace trust prompt. Each repository is trusted once, the first time its checkout exists; dot remembers it in its state directory, so untrusting it in Claude Code later sticks. Runs as part of dot update and dot init.

Options

Examples

dot agent sync

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 the configured agent_lint commands in parallel from the repository root under dot run –timeout, reporting results in config order. Deleted files and submodule changes are left out. Paths narrow the changed files. –all uses every tracked and untracked file that is not ignored instead, so commands run without changes. –only runs just the named commands and reports only those. 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 agent lint --all --only Typecheck --json

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 tools

List the dot commands exposed to agents as Code Mode tools

dot agent tools [flags]

List the dot commands that the OpenCode cli-tools plugin exposes as typed Code Mode tools under tools.dot.*. The list is opt-in and kept in dot/src/commands/AgentTools.ts; each entry’s input schema is generated from the command’s arguments and flags. –json prints the manifest the plugin reads: tool name, command path, summary, read or write access, pinned state, timeout, whether the command has –json, the input JSON Schema, and how each input maps back to an argument or flag. Write tools ask for permission through dot.write.

Options

Examples

dot agent tools
dot agent tools --json

dot agent detect

Detect whether an AI coding agent is running dot

dot agent detect [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 agent detect. 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 agent detect
dot agent detect --quiet
dot agent detect --json
dot agent detect && echo running under an agent

dot notes

Integrate with the notes tool

dot notes <subcommand> [flags]

Options

dot notes capture

Manage the notes capture Worker

dot notes capture <subcommand> [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

Set up pacman package repositories

dot setup <subcommand> [flags]

Options

dot setup private

Set up private package sources

dot setup private <subcommand> [flags]

Options

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

Set up public package sources

dot setup public <subcommand> [flags]

Options

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

Work across tracked Git repositories

dot git <subcommand> [flags]

Options

dot git 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 <subcommand> [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 log show --path ~/repos/example --sha abc1234
dot git log show --path ~/repos/example --from def5678 --sha abc1234
dot git log show --path ~/repos/example --changes uncommitted

dot git log show

Return changed files and a diff preview as JSON for the Git panel, for one commit, a commit range or a repository’s local changes

dot git log show [flags]

Options

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, or work-time for links.work during work hours and links.personal otherwise. When links is set, links.sites rules come first and unselected links follow the same routing as dot link open. Without links or a selection, uses the desktop default, and –work-time selects the work browser during work hours outside calendar leave. –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 dot-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 and exits 2 when some notifications could not be inspected but nothing failed. Opening GitHub returns to the review without dismissing anything. The dot-notifications-dismiss.timer user timer runs all-mode every 15 minutes; dot services start dot-notifications-dismiss.timer runs it now.

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; with –refresh the output is still printed, then the command exits non-zero naming each repository that could not be refreshed. 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 --finding ONE --finding TWO --impact none
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 issues

Track open issues for enabled repositories, independently of GitHub notifications

dot git issues [flags]

Opt in with issues.enabled in private dot-git.yml. Open issues exclude pull requests and are ordered by latest update. Rules under the top-level issues.exclude list hide matching issues, such as a Dependency Dashboard; each rule matches when every field it sets (title, author, label and optional repo) matches, case-insensitively. Queries fetch at most every five minutes unless –refresh is supplied. Failed fetches retain the last successful list and report an error.

Options

Examples

dot git issues --panel-json
dot git issues --refresh
dot git issues --open

dot link

Route links to the work or personal browser, or to the Git panel

dot link <subcommand> [flags]

Options

dot link open

Open a link in the work or personal browser, or a dot:// link in the Git panel

dot link open [flags] [<args...>]

Routes a single HTTP or HTTPS link using links in dot-git.yml: the first matching links.sites rule, then the browser of the tracked repository a GitHub link belongs to, otherwise links.personal. A site rule or repository can select work-time, which opens links.work during work time outside calendar leave and links.personal otherwise. A site rule can be limited to some OMARCHY_HOST values with hosts, and can set a Hyprland workspace: the link opens in the browser’s window there that was focused last, found by its links.window_classes pattern, or in a new window moved there. With –background, a link placed on a workspace leaves focus and the cursor where they were; link-open-background runs this for PLANNOTATOR_BROWSER, so reviews Plannotator opens by itself don’t pull focus. Anything else, including no arguments, goes to links.personal unchanged. The link-browser desktop entry runs this as the default web browser, so xdg-open and Omarchy’s browser launcher use it. A dot://git/issue/// or dot://git/pull/… link opens that item in the Git panel when the panel lists it, and its GitHub page through the same routing otherwise; the dot-link desktop entry handles the dot:// scheme. Failures are also sent as a desktop notification.

Options

Arguments

Examples

dot link open https://github.com/home-assistant/frontend
dot link open --background http://localhost:38080/
dot link open dot://git/issue/timmo001/dotfiles/1076
dot link open -- --incognito

dot link git

Print the dot:// links that open GitHub issues and pull requests in the Git panel

dot link git [flags] <urls...>

Read-only. For each URL, reports the dot://git/<issue|pull>/// link (null when the URL isn’t a GitHub issue or pull request), whether the Git panel lists the item, read from the panel’s cache, and, when it does, a Markdown icon link to put after the GitHub link. Agents add that icon link wherever they share GitHub issue and pull request links. Prints JSON with –json or when run under an AI agent, otherwise one line per URL.

Options

Arguments

Examples

dot link git https://github.com/timmo001/dotfiles/issues/1079
dot link git https://github.com/timmo001/dotfiles/pull/1080 --json

dot link native-host

Native messaging host for the dot links Chromium extension

dot link native-host [flags] [<origin...>]

Chromium runs this through the link-native-host wrapper; it isn’t for running by hand. Reads one length-prefixed JSON request on stdin: resolve {url} replies with the page’s dot:// link, whether the Git panel lists it, counting a pull request’s tabs such as /changes, and the name of its tracked checkout, open {url} opens it in the Git panel and fails rather than opening the browser when the panel doesn’t list it, review {url} opens a pull request, from any of its tabs, in a Plannotator review through uwsm-app, agent {url} starts an OpenCode agent on an issue or pull request in its tracked checkout through dot herdr repo open, with a prompt that loads the repository’s matching skills and differs for items you opened, are assigned or (for issues) own the repository of, and clear-deps starts dot-notifications-dismiss.service now instead of waiting for its timer. dot stow builds the extension in chromium-extension/ and writes the host manifest into each browser in links.extension.user_data_dirs in dot-git.yml.

Options

Arguments

dot mcp

Manage agent MCP server configs

dot mcp <subcommand> [flags]

Options

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 maps in dot-git.yml turn named servers on (true) or off (false) for that checkout using generated, Git-ignored .opencode/opencode.jsonc files; unlisted servers keep their mcp.yml default. Repository opencode_skills maps allow (true) or deny (false) named skills in the same file, so skills denied globally can be listed only where they are useful. Removing every override removes the 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. Claude Code’s user scope is updated through the claude CLI instead of a file. Some agent harnesses are documented stubs and are not written.

Options

Examples

dot mcp sync

dot private

Work with the private package repository

dot private <subcommand> [flags]

Options

dot private pkg

Manage private packages

dot private pkg <subcommand> [flags]

Options

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 my-package --install
dot private pkg publish --skip-build --no-git my-package

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 <subcommand> [flags]

Options

Examples

dot skills updates --json
dot skills updates --update --skill agentic-workflows --no-commit

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 skills check

Check adapted imports against upstream

dot skills check [flags]

Options

Examples

dot skills check --skill agentic-workflows

dot skills consumers

Manage repositories that receive shared skill copies

dot skills consumers <subcommand> [flags]

Options

dot skills consumers add

Share skills with a repository through consumers.yml, push the change and install them there straight away

dot skills consumers add [flags] <skill...>

Options

Arguments

Examples

dot skills consumers add code-review testing
dot skills consumers add --repo timmo001/ha-bridge writing-style

dot skills consumers remove

Stop sharing skills with a repository through consumers.yml, push the change and remove the copies there straight away. Dropping the last skill, or –all, also drops its entry.

dot skills consumers remove [flags] [<skill...>]

Options

Arguments

Examples

dot skills consumers remove writing-style
dot skills consumers remove --repo timmo001/ha-bridge --all

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 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. –open keeps only repositories with an open Herdr workspace, and fails when the Herdr server cannot be reached. 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 list --open --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, including an optional release watching template from its release_templates. 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 dot 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 pr

Watch, list, 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 pr list

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

dot pr list [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 pr list --panel-json
dot pr list --refresh
dot pr list --open

dot brief

Daily brief of GitHub work in the Plannotator Inbox

dot brief <subcommand> [flags]

Options

dot brief run

Build the daily brief and post it to the Plannotator Inbox

dot brief run [flags]

Collect open PRs and issues you’re involved in, unread notifications and failing CI, score each with the decision model in brief.yml, apply its rules, during work time summarise what people’s comments ask of you on the top few with opencode2, then post the report to the “Daily brief” Inbox thread. Items ticked in the last report stay hidden until they have new activity. During work time work items come first; outside it they’re left out, except crossover items. At work time the report also shows the window since the last work day, today’s and the next work day’s meetings from the work.calendar in brief.yml, an area tag in emoji form on each item, and context such as merged or stale, followed by Resolved, Your tasks, sections for the areas you work in (from the labels on your recent PRs and reviews) and the work.scopes searches.

Options

Examples

dot brief run
dot brief run --dry-run

dot brief dismiss

Hide a brief item until it has new activity

dot brief dismiss [flags] <id>

Options

Arguments

Examples

dot brief dismiss pr:timmo001/dotfiles#12

dot brief follow-up

Hide ticked items and start agents for notes left on the daily brief

dot brief follow-up [flags]

Read the brief’s Inbox thread for new replies. Items ticked in a reply are hidden straight away, with a reply confirming it. Each note starts an OpenCode agent through dot herdr repo open, in the checkout of the item it names by B number, or the dotfiles checkout otherwise, with the note and the item’s context as its prompt. –watch holds one Inbox connection open and waits for replies instead of checking once; the dot-brief-follow-up user service runs it.

Options

Examples

dot brief follow-up
dot brief follow-up --dry-run
dot brief follow-up --watch

dot report

Configurable reports from code scans, GitHub searches and file checks

dot report <subcommand> [flags]

Options

dot report run

Run a report and post it to the Plannotator Inbox

dot report run [flags] <name>

Read ~/.config/dot/reports/.yml and run its sections in order. A code section keeps a shallow clone of a GitHub repository under the dot cache, tests each included file against named regexes, puts it in the first bucket whose patterns match, and counts per-file metrics. A github section runs a GitHub issue or pull request search, with {since} set to the last run’s date, and can drop results the decision model in models.decision finds irrelevant. A checks section tests whether a file still matches a pattern and shows each finding while it holds. The run is compared with the last one, an optional OpenCode model in models.summary writes a short paragraph about what changed, and the page is saved under ~/.local/state/dot/reports// and attached to a message in the report’s Inbox thread. The message ends with a question so it waits in the Inbox, and the next run withdraws it if it’s still open. With work_time_only, a real run outside work time (days off, out of hours or calendar leave) posts nothing and exits 3.

Options

Arguments

Examples

dot report run hass-removal
dot report run hass-removal --dry-run

dot report list

List report files and whether they’re valid

dot report list [flags]

Options

Examples

dot report list

dot launch

Launch desktop apps

dot launch <subcommand> [flags]

Options

dot launch floating

Launch floating windows

dot launch floating <subcommand> [flags]

Options

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 plannotator

Plannotator tooling

dot plannotator <subcommand> [flags]

Options

dot plannotator inbox

Open the Plannotator Inbox in its own window, starting it first when it is stopped

dot plannotator inbox [flags]

Runs plannotator inbox –background, which starts a stopped Inbox detached and prints the running one’s loopback URL, then opens that address in a Qt WebEngine window (~/.local/share/plannotator-inbox/Inbox.qml, run by the qml runtime). A running window is raised instead of duplicated. –url opens another base address, such as an HTTPS front in front of the Inbox; without it, the window opens the Inbox’s own loopback URL, which needs no login. The Inbox is still started first. –thread shows one thread (the Inbox’s #thread= fragment), in the running window when there is one. The timmo.plannotator-inbox bar plugin, dot workspace setup and the Plannotator Inbox desktop entry run this. Failures are also sent as a desktop notification.

Options

Examples

dot plannotator inbox
dot plannotator inbox --thread thr_01
dot plannotator inbox --url https://inbox.plannotator.localhost

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 repository workspaces

dot herdr repo <subcommand> [flags]

Options

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. –after-prefix places a newly created workspace after the last workspace whose label starts with the prefix, keeping related workspaces together. Without it, a new workspace whose label starts with a [tag] joins that tag’s group, and one whose label extends an existing one by a whole word (Dotfiles Private after Dotfiles) joins that group. A herdr_after label in dot-git.yml takes priority: the workspace opens straight after the nearest open workspace in its herdr_after chain, or straight before the first open workspace that chains back to it. –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 pane

Move panes between tabs

dot herdr pane <subcommand> [flags]

Options

dot herdr pane move

Move a pane into another tab, beside a chosen pane

dot herdr pane move [flags] [<pane>]

Moves the focused pane, or a pane ID or live agent name, into another tab or out into a new tab. On a terminal, anything the flags leave open is asked for: which pane when its tab has several, the destination (filterable across every workspace, current workspace first: each workspace’s tabs with their panes and agents, then a new tab there), which pane to split beside when the destination has several, and the split direction, offering first the one that suits that pane’s shape. Without a terminal, or with –json, the focused panes are used, –split defaults to auto and –to is required. –to new opens a new tab in the pane’s workspace, or in –workspace. Esc, Ctrl+C or Ctrl+D cancels. Moving into another workspace gives the pane a new ID, which the output reports; agent names follow the pane.

Options

Arguments

Examples

dot herdr pane move
dot herdr pane move reviewer --to 2 --split auto
dot herdr pane move --to new
dot herdr pane move --to new --workspace Dotfiles

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 homeassistant

Aliases: dot ha

Run Home Assistant Core and frontend dev servers

dot homeassistant <subcommand> [flags]

Runs the pitchfork daemons and frontend suites behind the Home Assistant dev setup, configured in $XDG_CONFIG_HOME/dot/homeassistant.yml. Interactive runs go through dot status run and, under Herdr, open in the repository’s workspace. Under an agent, commands skip setup, Herdr and prompts: they reuse a running daemon and fail with a message instead of stopping a conflicting one. Commands act on the frontend checkout they run in: in a linked worktree, core, build and serve are that worktree’s own daemons, under the pitchfork namespace ha-frontend- from a generated, untracked pitchfork.local.toml, and stop with no targets only stops those. status with no targets also lists every worktree’s daemons.

Options

Examples

dot ha c dev
dot ha f serve prod
dot ha status

dot homeassistant core

Aliases: dot homeassistant c

Run Home Assistant Core

dot homeassistant core <subcommand> [flags]

Options

dot homeassistant core dev

Run Core serving the local frontend build

dot homeassistant core dev [flags]

Runs setup, then starts the Core pitchfork daemon, which starts the frontend build it depends on. Stops the frontend serve daemon first after asking. Under an agent, it skips setup, Herdr and prompts, and only starts the daemon when nothing conflicts. In a linked frontend worktree, it starts a throwaway Core dev instance for that worktree instead, at https://dev..ha-frontend.localhost: Core from the Core checkout’s virtual environment, serving the worktree’s own watch build, with its config in /.ha-dev/config copied from frontend.worktree.config, and onboarding done with the user dev and password dev. It runs in the background, and –latest is refused there.

Options

Examples

dot homeassistant core dev
dot ha c dev --latest --background
dot ha c dev --fresh

dot homeassistant core setup

Update Core’s dev branch and bootstrap its virtual environment

dot homeassistant core setup [flags]

On a clean tree, switches to dev, pulls it and fetches upstream/dev; –latest also rebases onto upstream/dev and pushes. Then creates the virtual environment if needed and runs script/bootstrap. Refuses to run under an agent.

Options

Examples

dot homeassistant core setup --latest

dot homeassistant frontend

Aliases: dot homeassistant f

Run Home Assistant frontend builds and dev servers

dot homeassistant frontend <subcommand> [flags]

Every command here takes the frontend’s build lock, so each stops the frontend pitchfork daemons first after asking. Lint, format, type checks and unit tests don’t take the lock; run them with pnpm directly.

Options

dot homeassistant frontend dev

Run the frontend watch build that Core serves

dot homeassistant frontend dev [flags]

Options

Examples

dot homeassistant frontend dev
dot ha f dev --background

dot homeassistant frontend serve

Run the frontend dev server against another Core

dot homeassistant frontend serve [flags] [<target>]

Writes the Core URL for the serve daemon, starts the target’s own daemon when it has one, then starts the serve daemon. Stops the frontend build daemon first after asking. In a linked frontend worktree, it starts that worktree’s own serve daemon at https://serve..ha-frontend.localhost.

Options

Arguments

Examples

dot ha f serve prod
dot ha f serve https://core.example.com --background

dot homeassistant frontend build

Run the frontend production build

dot homeassistant frontend build [flags]

Options

Examples

dot ha f build

dot homeassistant frontend gallery

Run the frontend gallery dev server

dot homeassistant frontend gallery [flags]

Options

Examples

dot ha f gallery --background

dot homeassistant frontend demo

Run the frontend demo dev server

dot homeassistant frontend demo [flags]

Options

Examples

dot ha f demo --background

dot homeassistant frontend e2e

Run the frontend e2e app dev server

dot homeassistant frontend e2e [flags]

Options

Examples

dot ha f e2e --background

dot homeassistant frontend test

Run frontend tests

dot homeassistant frontend test <subcommand> [flags]

Options

dot homeassistant frontend test e2e

Run the frontend e2e tests

dot homeassistant frontend test e2e [flags] [<suite>]

Options

Arguments

Examples

dot ha f test e2e
dot ha f test e2e app

dot homeassistant dev

Run Core and the frontend build in their Herdr workspaces

dot homeassistant dev [flags]

Options

Examples

dot ha dev
dot ha dev --background

dot homeassistant status

Show the Home Assistant dev servers

dot homeassistant status [flags] [<target...>]

Options

Arguments

Examples

dot ha status
dot ha status core serve

dot homeassistant stop

Stop Home Assistant dev servers

dot homeassistant stop [flags] [<target...>]

Options

Arguments

Examples

dot ha stop
dot ha stop gallery

dot homeassistant logs

Print or follow a Home Assistant dev server’s logs

dot homeassistant logs [flags] <target>

Options

Arguments

Examples

dot ha logs core
dot ha logs serve --follow

dot reload

Reload the desktop shell and services, or selected parts

dot reload [flags] [<part...>]

Reload parts of the desktop that can go stale after suspend or a change. With no parts, reloads everything except agents. agents reloads the OpenCode service’s config and, through Herdr, types /reload-plugins into idle Claude Code sessions and /reload into idle Pi sessions; busy sessions are left alone, and dot update runs it after a full update. keyboard re-arms the keyboard backlight. upnext rechecks Up Next sources, restarting its service if the recheck fails; it runs alongside the other parts because the YouTube check takes several seconds. shell clears a workspace mutation lock left by a dot workspace command stuck on a shell menu, regenerates shell.json, restarts the Omarchy shell and refreshes shell modules. updates refreshes available updates. doctor starts the dot doctor check.

Options

Arguments

Examples

dot reload
dot reload --no-auto-open
dot reload shell
dot reload shell updates
dot reload agents

dot workspace

Set up and lay out desktop workspaces

dot workspace <subcommand> [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

Examples

dot help
dot help git commit