Command Reference

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

This page lists every dot command, generated from the same registry that powers dot help and shell completions. Run any command with --help to see the same details at the terminal.

`dot dashboard`

Open the dot dashboard

dot dashboard [options]

Open the full-screen dot dashboard. It combines tracked repo state, GitHub notifications, and optional bounded source commands for Twitch, environment, and calendar cards.

Modes

(default)      Interactive dashboard

Examples

dot dashboard

`dot init`

Run one-time first-use machine setup

dot init [options]

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

Option	Description
`--confirm`	Compatibility flag; accepted but does not suppress prompts
`--noninteractive`	Skip the Hypr host questionnaire for this run
`--interactive`	Enable the Hypr host questionnaire when no host is selected
`--force`	Re-run init even if the machine looks initialised
`--host` `<name>`	Hypr host to link before stow (default: OMARCHY_HOST or desktop)
`--log` `<path>`	Init log path (default: ~/.local/state/dot/init.log)

Examples

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

`dot install`

Ensure prerequisites, then backup/adopt dotfiles

dot install

`dot update`

Aliases: dot up

Self-update, pull repos, stow dotfiles, rebuild

dot update

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

Option	Description
`--pull`	Run the repository pull phase only
`--stow`	Generate completions, sync MCP configs, and stow only
`--app`	Install Bun dependencies and rebuild the dot binary only
`--check`	Report core/system repos behind upstream (no update); exit 10 if any
`--check-all`	Report all tracked repos behind upstream (no update); exit 10 if any

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 before update can continue

`dot stow`

Re-stow public/private dotfiles

dot stow

Options

Option	Description
`--public`	Stow public dotfiles only
`--private`	Stow private dotfiles only

`dot omarchy-shell-config`

Regenerate the Omarchy shell layout

dot omarchy-shell-config

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

Examples

dot omarchy-shell-config

`dot firewall`

Reconcile managed ufw firewall rules

dot firewall

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.

Examples

dot firewall

`dot doctor`

Run dotfiles system health checks

dot doctor [options]

Run health checks on the dotfiles system. Verifies dependencies, repos, stow integrity, systemd timers, packages, browser config, and more.

All checks run in parallel and each section streams to the terminal as it finishes, so sections appear in completion order. A grouped summary of any errors and warnings, ordered by section, follows at the end. A log file is always written to ~/.local/state/dot/logs/.

Options

Option	Description
`--open-opencode`	Save the report and attempt to open it in OpenCode

Checks performed

Dependencies         Required/optional CLI tools (git, stow, gh, gum, ...)
gh extensions        Configured gh CLI extensions are installed
Locale               Required locales from shell config are generated
Zsh key bindings     Delete/forward-delete bindings and other expected defaults
Repositories         Public/private dotfiles + private git repos exist and have upstreams
Origin HEAD          Local origin/HEAD tracks the remote default branch (not stale)
Stow integrity       Dry-run restow to detect drift
OpenCode location    Canonical paths, legacy remnants
OpenCode server      Shared Hypr autostart and ~/.config/opencode/.env password
Herdr integration    Herdr binary and OpenCode integration installed
GitHub MCP auth      gh token available for DOT_GH_MCP_BEARER
Git config           Managed include is active
Git notifications    API scope and notification access
Doctor startup       Startup notification timer
uwsm session PATH    ~/.local/bin on the uwsm/systemd user-environment PATH
Daily volume reset   Laptop-only optional timer
Omarchy config       Managed repos and Hypr host-link correctness
Legacy Hypr repo     Flags a retired omarchy-hypr clone at ~/.config/hypr
Neovim theme link    Repairs a mislocated omarchy-nvim theme.lua symlink
Private access       Private dotfiles overlay enabled or explains why it is disabled
Browser flags        Symlinks from private stow package
Hardware video       VAAPI render nodes, drivers, packages
Browser extensions   Private extension check list
Public packages      AUR packages installed + version check
Private package repo Private pacman repo registered
Private packages     Private repo + packages installed
Pacman hooks         Hook files installed and up to date
Firewall rules       Managed ufw rules (KDE Connect, Home Assistant, OpenCode, LocalSend, libvirt); repair with dot firewall

Exit codes

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

Examples

dot doctor
dot doctor --open-opencode

`dot clean`

Unstow managed dotfiles

dot clean

`dot git-diff`

Aliases: dot diff

Open the git diff/repo watcher view

dot git-diff [options]

Open the diff/repo watcher view. Without flags, opens the interactive TUI.

Modes

(default)        Interactive TUI diff view
--raw            Text summary of repos with changes
--bar-json      JSON output for status bars and shell modules
--list-changed   Changed repos as name|path rows
--list-all       All tracked repos as name|path rows

Options

Option	Description
`--no-fetch`	Skip fetching from remotes (use local refs only)
`--tab` `<tab>`	Initial pane to focus in TUI (default: changed) (one of: `changed`, `other`, `unchanged`)
`--repo` `<name>`	Open a changed repository directly in lazygit
`--raw`	Text summary output
`--bar-json`	JSON output for status bars and shell modules
`--list-changed`	Changed repos as rows
`--list-all`	All tracked repos as rows

Examples

dot git-diff
dot git-diff --raw
dot git-diff --bar-json
dot git-diff --tab other
dot git-diff --repo dotfiles

`dot git-commit`

Commit staged changes through the guarded gateway

dot git-commit --message <subject> [options] | --amend [options]

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, so commits stay in the maintainer’s concise one-line style.

Modes

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

Options

Option	Description
`--message` `-m` `<subject>`	Single-line commit subject (required unless –amend)
`--path` `<file>`	Commit only this file; repeatable
`--amend`	Amend the previous commit; keeps its message unless –message is given
`--push`	Push the current branch after committing (pulls –rebase first, or force-with-lease when amending, never a plain force)
`--dry-run`	Preview the commit and push plan without changing anything

Message guards

Single line     Rejects multi-line messages
No em/en-dash   Rejects '—' and '–'; use a hyphen
No full stop    Rejects a trailing '.'
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,
including a fork kept for upstream PRs. 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 GitHub notification inbox

dot git-notifications [options]

Open the authenticated user’s GitHub notification inbox. Without machine or action flags, opens the interactive TUI.

Modes

(default)       Interactive notifications TUI
--raw           Text summary of notification threads
--bar-json     JSON output for status bars and shell modules
--list-threads  Notification threads as rows
--bar-filter    Apply watched-repo filtering in raw/list output

Options

Option	Description
`--raw`	Text summary of notification threads
`--bar-json`	JSON output for status bars and shell modules
`--list-threads`	Notification threads as rows
`--bar-filter`	Apply watched-repo filtering in raw/list output
`--all`	Include read notifications
`--participating`	Only include participating or mentioned threads
`--since` `<date>`	Only include notifications updated after this date
`--mark-read` `<id>`	Mark a notification thread as read
`--mark-bot-read`	Mark unread Renovate/Dependabot/bot notifications as read
`--dry-run`	Preview –mark-bot-read without mutating GitHub state
`--mark-done` `<id>`	Mark a notification thread as done
`--ignore` `<id>`	Ignore new notifications for a thread
`--unignore` `<id>`	Stop ignoring notifications for a thread

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 agents-sync`

Mirror AGENTS.md to agent harness instruction files

dot agents-sync

`dot mcp-sync`

Regenerate MCP configs for all harnesses from the spec

dot mcp-sync

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.

Examples

dot mcp-sync

`dot notes-capture-sync`

Sync watched repositories to the notes capture picker

dot notes-capture-sync

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.

Examples

dot notes-capture-sync

`dot is-agent`

Detect whether an AI coding agent is running dot

dot is-agent [options]

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

Option	Description
`--quiet` `-q`	Print only the provider id
`--json`	Print the detection result as JSON

Examples

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

`dot setup-public-repo`

Trust and register the public timmo pacman repository

dot setup-public-repo

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.

Examples

dot setup-public-repo

`dot setup-private-repo`

Sync and register the private pacman repository

dot setup-private-repo

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.

Examples

dot setup-private-repo

`dot private-pkg-publish`

Build and publish a private package

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

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

Options

Option	Description
`--no-git`	Skip package repo commit and push
`--skip-build`	Publish an existing dist package artifact
`--install`	Install the published package after syncing the mirror

Arguments

Argument	Description
`<package-name>`

Examples

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

`dot skill-updates`

Check/apply imported skill updates

dot skill-updates

Options

Option	Description
`--check`	Check only without applying
`--update`	Auto-apply clean updates
`--json`	Report update states as JSON without applying
`--skill` `<name>`	Limit checking or updating to one imported skill
`--no-commit`	Apply updates without creating a commit
`--skip-review`	Skip local-edit review

Examples

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

`dot skill-check`

Validate skill maintenance and adapted imports

dot skill-check

Validate branch-context wiring and ensure adapted imported skills still differ from every file in their current upstream source.

When an adapted skill exactly matches its source, human sessions can reimport it through the standard Skills CLI. Agent sessions print the equivalent command instead.

Options

Option	Description
`--open-opencode`	Run checks and attempt OpenCode analysis
`--diff-origin`	Diff imported skills against their upstream origins; with –open-opencode, include the diff in the prompt
`--skill` `<name>`	Check one adapted imported skill only

Examples

dot skill-check --skill browser-control

`dot skill-updates-agent`

Run GitHub or device skill update automation

dot skill-updates-agent <github|device> [options]

Run the shared skill update workflow. GitHub mode checks imports, opens clean update pull requests, dispatches validation, and refreshes the dashboard. Device mode optionally waits for that workflow, then runs the configured local OpenCode processor with completed-run deduplication.

Options

Option	Description
`--config` `<path>`	Use a YAML config other than private dotfiles/skill-updates-agent.yml
`--run-id` `<id>`	Wait for this workflow run before device processing
`--skills-dir` `<path>`	Use this Skills checkout in GitHub mode

Arguments

Argument	Description
`<mode>`	One of: `github`, `device`.

Examples

dot skill-updates-agent github --skills-dir .
dot skill-updates-agent device --config ~/.config/dotfiles-private/skill-updates-agent.yml --run-id 123456

`dot completions`

Generate shell completions

dot completions [bash|fish|zsh] [--stdout]

Generate shell completions for dot.

By default this writes the managed completion file for the selected shell in the public dotfiles repo so the next dot stow installs it.

Options

Option	Description
`--stdout`	Print the completion script instead of writing it

Arguments

Argument	Description
`<shell>`	One of: `bash`, `fish`, `zsh`.

Examples

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

`dot omarchy`

Open an Omarchy submenu by path

dot omarchy [submenu...]

Open the Omarchy desktop controls menu. Pass a submenu path to jump straight to it:

dot omarchy theme Theme submenu dot omarchy theme set Execute theme set directly

Arguments

Argument	Description
`<submenu>`	Repeatable. One of: `theme`, `font`, `toggle`, `capture`, `system`, `launch`, `refresh`, `restart`, `install`, `remove`, `packages`, `share`, `reminder`, `setup`, `snapshot`, `brightness`, `power`.

Available submenus

theme       Theme management
font        Font management
toggle      Toggle system features
capture     Screenshots and recordings
system      Lock, logout, reboot, shutdown
launch      Launch applications
refresh     Refresh system components
restart     Restart system services
install     Install software and tools
remove      Remove software and features
packages    Package management
share       Share clipboard, files, folders
reminder    Reminders
setup       DNS, security setup
snapshot    System snapshots
brightness  Display and keyboard brightness
power       Power profiles

`dot usage`

Local-first analytics for dot usage

dot usage [summary|stale|path|backfill] [options]

Report local-first usage analytics for dot. Dispatched dot commands append NDJSON events under $XDG_STATE_HOME/tool-usage with timestamps, machine, canonical command, recognised flag names, exit status, duration, source, and invoker. Live dot events never store positional values.

Optional shell-history backfill observes selected standalone tools without requiring integration. It uses whitespace tokenisation, so review the source history before applying when arguments may contain sensitive text.

Set DOT_USAGE_DISABLE=1 to stop automatic live recording, or DOT_USAGE_DIR to relocate the event root. Explicit backfill –apply still writes events.

Modes

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

Options

Option	Description
`--days` `<n>`	Window for summary/stale (default: 90)
`--format` `<fmt>`	summary format (one of: `text`, `json`, `agent-context`)
`--root` `<path>`	Extra event root to combine (repeatable)
`--history`	Backfill from shell history (accepted for clarity)
`--apply`	Write events during backfill (default: dry run)

Examples

dot usage summary --days 30
dot usage summary --format agent-context
dot usage stale --days 90
dot usage backfill --history
dot usage backfill --history --apply

`dot help`

Show this help menu

dot help