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

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

Options

Arguments

Examples

dot agent-oxlint src/example.ts
dot agent-oxlint src/one.ts src/two.ts
dot agent-oxlint --all

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-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 workspace-relayout

Apply or capture a Hyprland workspace layout

dot workspace-relayout [flags]

Options

dot workspace-capture

Capture Hyprland workspace and window state

dot workspace-capture [flags]

Options

dot workspace-restore

Restore a captured Hyprland workspace session

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