dotstate / docs / reference / cli

The command line,
in one place.

Everything the interactive TUI does, dotstate can do as a script. Good for CI, bootstrapping machines, or staying on the home row.

Files

Core

dotstate

Open the interactive TUI.

dotstate list

List every synced file in the active profile, grouped by source (own, inherited, common) with symlink and storage locations.-v, --verbose show detailed information

dotstate add <path>

Adopt a file. Moves it into the repo and creates a symlink in its place. Example: dotstate add ~/.zshrc.--common add as a common file shared across all profiles

dotstate remove <path>

Remove a file from sync. Restores the original and removes the symlink.--common remove from common files

dotstate activate

Re-create symlinks and restore app state. Essential after cloning your dotfiles on a new machine.

dotstate deactivate

Restore original files and remove symlinks — useful when uninstalling.

Profiles

Inspect & switch

dotstate profile

Print the active profile name.

dotstate profile list

List all profiles with the active one marked.

dotstate profile switch <name>

Switch to another profile and re-create its symlinks. If the new profile has different files, the old symlinks are removed first. Example: dotstate profile switch work.

Sync

Remote

dotstate sync

Commit local changes, pull with rebase, and push.-m, --message custom commit message

dotstate sync -m "Update zshrc"

Sync with a custom commit message.

dotstate upgrade

Check for updates and optionally upgrade dotstate itself.

Packages

Per-profile packages

dotstate packages list

List packages for a profile with installation status.-p, --profile target profile -v, --verbose detailed info

dotstate packages add

Add a package to a profile. Interactive, or via flags. Example: dotstate packages add -n ripgrep -m brew -b rg.-n, --name package name -m, --manager package manager -b, --binary binary name

dotstate packages remove

Remove a package from a profile.-p, --profile target profile -y, --yes skip confirmation

dotstate packages check

Check installation status of all tracked packages.-p, --profile target profile

dotstate packages install

Install all missing packages for a profile.-p, --profile target profile -v, --verbose show install output

Diagnostics & info

Utility

dotstate doctor

Run diagnostics to check the health of your dotstate setup.-v, --verbose detailed --fix auto-fix issues --json JSON output

dotstate config

Print the configuration file location.

dotstate repository

Print the dotfiles repository location.

dotstate logs

Print logs location and how to view them.

dotstate completions <shell>

Emit shell completions for bash, zsh, or fish.

dotstate help

Full command reference.

Exit codes

Code	Meaning
`0`	Success.
`1`	General error (invalid arguments, missing file, etc).
`2`	Configuration or repository error.
`3`	Network or git remote error.

See profiles & inheritance for how files resolve across profiles, or package management for the bigger picture on packages.

The command line, in one place.