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. 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 and –post-hook-repo flags support the active self-update handoff.

dot update [flags]

A full update pulls the public dotfiles, installs Bun dependencies, rebuilds and relaunches dot, then scans and pulls tracked repositories. It trusts tracked mise configs, regenerates completions, installs missing public Arch/AUR packages, runs the required MCP sync, stows, rebuilds again, runs agents sync, backfills the init marker, and starts the resume refresh. It finishes with a summary of updated repositories and completed actions.

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. Every mode that reaches the end starts the bounded resume refresh.

Options

Exit codes

0   Update completed, or an update check found nothing behind
1   Fatal workflow failure
2   Update check could not scan repositories
10  Update check found repositories behind upstream
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 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.

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 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-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
--list-changed  Changed repositories as rows
--list-all      All tracked repositories as rows

Options

Examples

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

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. 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.

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 machine-output or action flags, this opens the Omarchy shell panel. –since accepts ISO/RFC dates, epoch timestamps, compact durations such as 2d, and quoted durations such as “2 days ago”.

dot git-notifications [flags]

Modes

(default)       Open the shell notification panel
--raw           Text summary
--bar-json      Status-bar JSON
--list-threads  Notification rows
--bar-filter    Apply watched-repository filtering

Options

Examples

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

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. 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 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 generated release notes. –interactive explains and confirms in the terminal; –confirm PLAN executes a reviewed plan with live progress.

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 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. 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 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 single private spec (mcp.yml), keeping agent harness MCP configs aligned. Writes into the stowed private source tree; run dot stow after. Some agent harnesses are documented stubs and are not written. OpenCode gated servers also receive a default-off tools gate so their tool schemas stay out of the baseline context until an agent re-enables them.

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 shell completions for dot. By default this writes the managed dot and skill-maintenance completion files for the selected shell so the next dot stow installs them. Pass –stdout to print only dot completions.

Options

Arguments

Examples

dot completions zsh
dot completions bash --stdout
dot completions fish --stdout

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-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 for cleanup work in an opted-in repository. Repository-owned Oxlint takes precedence. Pass changed paths normally, or use –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 for cleanup work and do not make these personal rules authoritative for the host repository.

Modes

<path>...  Lint explicit changed files or directories
--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 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 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. If the server is headless, open a tiled terminal and wait for a foreground client before focusing the workspace.

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 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 usage

Report local-first usage analytics from NDJSON events under $XDG_STATE_HOME/tool-usage. Live events store canonical commands and recognised flag names, never positional values. Set DOT_USAGE_DISABLE=1 to disable live recording or DOT_USAGE_DIR to relocate storage.

dot usage [flags] [<command>]

Modes

summary   Per-feature usage table (default)
stale     Features not used within the window
path      Print the event storage root
backfill  Import whitelisted shell-history invocations

Options

Arguments

Privacy

Live dot events never store positional values
Shell-history backfill is a dry run unless --apply is passed
Review history before applying when arguments may contain sensitive text

dot help

Show this help menu

dot help [flags] [<command>]

Options

Arguments