Command Reference

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 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, machine hooks, and then finishes by running dot update. After init completes, use dot update for ongoing maintenance.

Options

Option	Description
`--confirm`	Acknowledge non-interactive package helpers
`--noninteractive`	Skip interactive prompts for this run
`--interactive`	Allow interactive prompts for this run
`--host` `<name>`	Hypr host to link before stow (default: OMARCHY_HOST or desktop) (one of: `desktop`, `laptop`)
`--log` `<path>`	Init log path (default: /tmp/dot-init.log)
`--branch` `<name>`	Branch override for non-bootstrap Omarchy repos
`--bootstrap-branch` `<name>`	Branch override for bootstrap

Examples

dot init --noninteractive --confirm
dot init --host laptop --noninteractive --confirm
dot init --branch main --bootstrap-branch distro/omarchy

`dot install`

Ensure prerequisites, then backup/adopt dotfiles

dot install

`dot update`

Pull repos, stow dotfiles, install deps, rebuild

dot update

Options

Option	Description
`--pull`	Pull repos only
`--stow`	Stow only
`--tui`	Install deps and rebuild 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

`dot stow`

Re-stow public/private dotfiles

dot stow

Options

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

`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. Results are printed per-section with a grouped summary at the end. A log file is always written to ~/.local/state/dot/logs/.

Options

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

Checks performed

Dependencies         Required/optional CLI tools (git, stow, gh, gum, ...)
Secret Service       kwallet vs gnome-keyring provider
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
Git config           Managed include is active
Workflow runs        Repo list, status bar config, legacy watcher cleanup
Git notifications    API scope and status bar notification module wiring
Doctor startup       Startup notification timer
Daily volume reset   Laptop-only optional timer
Omarchy repos        Diff repos + worktree branch correctness
Legacy Hypr repo     Flags a retired omarchy-hypr clone at ~/.config/hypr
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 packages     Private repo + packages installed
Pacman hooks         Hook files installed and up to date

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`)
`--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-status`

Show branch status for the current repository

dot git-status [options]

Print unstaged files, staged files, and the last 10 commits — each with a compact relative timestamp, a pushed/local remote marker, and its changed files inline with (+added -deleted) line counts — for the current git repository. Designed as a single command for agents to get full working-tree and branch context.

Substitutes running these separately: git status, git diff —stat / git diff —numstat, git diff —cached —stat, git log —oneline —stat, and git log @{upstream}..HEAD (ahead/pushed check).

Add —diff to append the full unstaged and staged diffs under their sections, and —branch-diff to append the full diff of the current branch against the default branch (measured from their merge base so committed and uncommitted changes both show). —branch-diff errors on the default branch, where that range is empty. The flags combine.

Modes

(default)       Status summary: unstaged, staged, recent commits
--diff          Also print full unstaged and staged diffs
--branch-diff   Also print the full diff vs the default branch

Options

Option	Description
`--diff`	Append full unstaged and staged diffs for changed files
`--branch-diff`	Append the merge-base diff vs the default branch (errors on the default branch)

Examples

dot git-status
dot git-status --diff
dot git-status --branch-diff
dot git-status --diff --branch-diff

`dot git-log`

Open recent commits across tracked repos

dot git-log [options]

Open the recent commit history view. The left pane lists tracked repositories from dot git-diff, sorted by latest commit activity. The right pane lists recent commits for the selected repository.

Modes

(default)      Interactive git log TUI
--raw          Text summary of recent commits

Options

Option	Description
`--raw`	Text summary of recent commits

Examples

dot git-log
dot git-log --raw

`dot git-workflows`

Open watched GitHub workflow runs

dot git-workflows [options]

Open the watched GitHub workflow runs view. The left pane lists watched repositories from the private repo list. The right pane lists runs for the selected repo’s locally checked-out HEAD commit.

Modes

(default)      Interactive workflow runs TUI
--raw          Text summary of watched workflow runs
--bar-json    JSON output for status bars and shell modules
--list-repos   Watched repo summaries as rows
--list-runs    Workflow runs as rows

Options

Option	Description
`--since` `<date>`	Only include runs active at or after this date (ISO/RFC/epoch)
`--raw`	Text summary of watched workflow runs
`--bar-json`	JSON output for status bars and shell modules
`--list-repos`	Watched repo summaries as rows
`--list-runs`	Workflow runs as rows

Examples

dot git-workflows
dot git-workflows --raw
dot git-workflows --bar-json
dot git-workflows --since "$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)"
dot git-workflows --list-runs

`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 future notifications for a thread
`--unignore` `<id>`	Stop ignoring future 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 notes`

Open repository notes or run note utility commands

dot notes [--all] [command] [options]

Manage repository notes used by OpenCode note commands.

Modes

(default)                    Interactive notes TUI
--all                        Interactive notes TUI across all repos

Options

Option	Description
`--all`	Show notes from every repo-notes directory

Examples

dot notes
dot notes --all
dot notes root
dot notes context --command notes-list
dot notes list --all
dot notes list --format json

`dot notes root`

Print the notes vault root

dot notes root

Options

Option	Description
`--repo-notes`	Print repository notes directory

`dot notes context`

Print the context block for OpenCode notes

dot notes context

Options

Option	Description
`--command` `<name>`	OpenCode command name

`dot notes list`

List repository notes

dot notes list

Options

Option	Description
`--all`	Show notes from every repo-notes directory
`--format` `<labels	json>`

`dot handoffs`

Aliases: dot handoff

Open handoff notes

dot handoffs [--all] [--list]

Open the interactive notes TUI filtered to notes tagged handoff. Use —list for a plain text listing without the TUI.

Options

Option	Description
`--all`	Show handoff notes from every repo-notes directory
`--list`	List handoff notes to stdout without opening the TUI

Aliases

dot handoff
dot handoffs

`dot note`

Read, write, or delete note files

dot note <command> [options]

Read, write, and delete note files. Writes and deletes are committed to the notes vault when possible.

Examples

dot note read --path ~/Documents/notes/repo-notes/owner/repo/topic.md
dot note write --path /tmp/notes/repo-notes/owner/repo/topic.md --stdin
dot note delete --path /tmp/notes/repo-notes/owner/repo/topic.md

`dot note read`

Print a note file

dot note read

Options

Option	Description
`--path` `<path>`	Note file path

`dot note write`

Write stdin to a note file and commit it

dot note write

Options

Option	Description
`--path` `<path>`	Note file path
`--stdin`	Read note content from stdin

`dot note delete`

Delete a note file and commit it

dot note delete

Options

Option	Description
`--path` `<path>`	Note file path

`dot agents-sync`

Sync AGENTS.md to Cursor rule

dot agents-sync

`dot opencode-debug`

Debug OpenCode config and paths

dot opencode-debug

Options

Option	Description
`--agent` `<name>`	Debug a specific OpenCode agent

`dot setup-private-repo`

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
`--skip-review`	Skip local-edit review

`dot skill-check`

Validate skill references

dot skill-check

Options

Option	Description
`--open-opencode`	Run checks then open OpenCode analysis
`--diff-origin`	Diff imported skills against their upstream origins; with —open-opencode, include the diff in the prompt

`dot completions`

Generate shell completions

dot completions [zsh] [--stdout]

Generate shell completions for dot.

By default this writes the managed Zsh completion file in the public dotfiles repo so the next dot stow installs it to ~/.local/share/zsh/site-functions/_dot.

Options

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

Arguments

Argument	Description
`<shell>`	One of: `zsh`.

Examples

dot completions zsh
dot completions zsh --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 help`

Show this help menu

dot help