CLI reference
Apothem CLI reference — all subcommands and flags.
The apothem CLI is the primary operator interface for managing the shared
profile and harness adapters.
Global flags
| Flag | Description |
|---|---|
--version | Print the Apothem version and exit |
--help | Print help for the command |
Subcommands
apothem install
Install a harness adapter from the shared profile.
apothem install --harness <name|all> [--profile PATH] [--project PATH] [--dry-run] [--clean|--fresh] [--yes]| Option | Description |
|---|---|
--harness <name> | Harness adapter name (see canonical values below). Required. |
--profile PATH | Path to shared profile YAML. Defaults to ~/.config/apothem/profile.yaml. |
--project PATH | Project root for project-scope harnesses. |
--dry-run | Preview install without writing files. |
--clean, --fresh | Opt-in clean slate: back up and remove the prior install state (~/.claude, ~/.codex, ~/.agents, ~/.config/apothem) before installing. |
--yes | Skip per-target confirmation during a clean-slate removal (required for non-interactive --clean runs). |
Canonical --harness values:
antigravity
claude-code
codebuddy
codex
cursor
gemini-cli
github-copilot
glm
hermes
kimi-code
kiro
open-claw
opencode
qwen-code
trae
windsurf
zedUse --harness all --project <path> to select the registry-wide set. The
profile's exclude_harnesses list is honored during install/update batch
selection.
apothem update
Re-derive a harness adapter's native config from the current shared profile.
apothem update --harness <name|all> [--profile PATH] [--project PATH] [--dry-run]| Option | Description |
|---|---|
--harness <name> | Harness adapter name. Required. |
--profile PATH | Path to shared profile YAML. |
--project PATH | Project root for project-scope harnesses. |
--dry-run | Preview update without writing files. |
update re-materializes harness output. It does not upgrade the Apothem
engine itself; update the engine through the channel you installed it with
(the /plugin flow, npx, or the installer and update scripts), as described
in Updating.
apothem uninstall
Remove a harness adapter's native config.
apothem uninstall --harness <name|all> [--project PATH] [--yes]| Option | Description |
|---|---|
--harness <name> | Harness adapter name. Required. |
--project PATH | Project root for project-scope harnesses. |
--yes | Skip the confirmation prompt. |
apothem verify
Verify that a harness adapter's managed targets are present and valid.
apothem verify --harness <name|all> [--profile PATH] [--project PATH]| Option | Description |
|---|---|
--harness <name> | Harness adapter name or all. Required. |
--profile PATH | Shared profile YAML to check fidelity against. Without it, the check is purely structural. |
--project PATH | Project root for project-scope harnesses. |
Without --profile the check is structural: every managed target must be
present and valid. With --profile it also requires fidelity, so an install
that exists but has drifted from that profile fails verify — use it to confirm
a specific profile is faithfully installed.
Exit code is 0 when the harness is verified (and, with --profile, faithful
to it), 1 when a target is missing or invalid, or when --profile is given
and the install has drifted.
apothem status
Report install, verify, and drift state for every registered harness.
apothem status [--profile PATH] [--project PATH]| Option | Description |
|---|---|
--profile PATH | Shared profile to use as the drift baseline. An unreadable default profile degrades drift to unknown rather than aborting the sweep. |
--project PATH | Project root for project-scope harnesses. Without it they report needs-project. |
Each row pairs an installed flag with a verified flag, and the two combine
into the drift state:
| State | Meaning |
|---|---|
absent | Apothem has not installed into this harness. |
in-sync | Installed and matching the profile baseline. |
drift | Installed but no longer matching — remediate with apothem update. |
unknown | Installed, but the baseline profile could not be read. |
needs-project | A project-scope harness was reported without --project, so its target cannot be resolved. |
installed answers "did Apothem install here?", not "is this harness present
on the machine?". It is keyed on Apothem's own artifacts — the managed block
inside an instruction anchor, and content under the Apothem-owned .apothem/
subtree — never on a vendor-owned file the harness writes for itself. A
harness whose config directory exists but that Apothem never touched reports
absent, and one that has been uninstalled reports absent even though the
emptied directories remain.
apothem profile
Manage the shared Apothem profile.
apothem profile show [--profile PATH]
apothem profile init [--profile PATH] [--force]
apothem profile set <key> <value> [--profile PATH]
apothem profile edit [--profile PATH]| Subcommand | Description |
|---|---|
profile init | Create a schema-valid minimal profile scaffold. |
profile show | Print the resolved profile as JSON to stdout. With --json, the document is led by schema_version. |
profile set <key> <value> | Set a profile field. The value is stored as a literal string — bare words are not coerced, so no stays "no" and 1.0 stays a string — except true/false and explicit [...] / {...} list and map input. The assembled profile is schema-validated before it is written. |
profile edit | Open the profile in $EDITOR (falls back to the platform default). |
The --profile PATH option points each subcommand at an alternate profile
file. Defaults to ~/.config/apothem/profile.yaml.
apothem harnesses
List and inspect registered harness adapters.
apothem harnesses list
apothem harnesses show <name>| Subcommand | Description |
|---|---|
harnesses list | Print a table of every registered adapter with its installed-status flag and output path. |
harnesses show <name> | Print name, installed state, and output path for one adapter. |
apothem doctor
Run system diagnostics for the Apothem installation.
apothem doctorPrints the Apothem version, Python interpreter, platform, resolved profile
path, and a per-harness install-status table. Exit code is 1 when any check
fails: an invalid profile, an installed harness that does not verify, a
registered hook command that cannot start, an adapter that cannot be loaded or
probed, or an unreadable ledger. A harness that is not installed is reported
and is not a failure, and informational notes do not change the exit code.
Generated Command and Flag Reference
| Command | Flags | Description |
|---|---|---|
apothem backups prune | --dry-run, --format, --harness, --json, --keep, --no-color, --quiet, -q, --verbose, -v | Delete backup sets and install records beyond the newest N per harness. Keeps the newest N backup sets under ~/.apothem/backups/ for each selected harness, and the newest N install records per install root in its ledger under ~/.apothem/state/. A backup set that a kept record, or the latest install record of any install root, still references is never deleted, so rollback of the latest install still restores. |
apothem completion | — | Print a shell-completion script for SHELL to stdout. Supported shells: bash, zsh, fish, powershell. Every script is generated by Click's env-var completion protocol — PowerShell through the completion class registered above, since Click ships none natively. Enabling completion is opt-in: this command only prints the script — pipe or append it to the shell's completion file yourself (see --help). |
apothem diff | --format, --harness, --json, --no-color, --profile, --project, --quiet, -q, --verbose, -v | Preview the pending configuration changes for a single harness. |
apothem doctor | --format, --json, --no-color, --project, --quiet, -q, --verbose, -v | Check the installed harnesses and the shared profile; exit 1 on any failure. Reports the engine version, Python, and platform; validates a present shared profile against the packaged schema; and, for every installed harness, runs the adapter's verify and starts each hook command the install registered with a no-op payload. A harness that is not installed is reported but is not a failure, so a machine with one healthy harness passes. Project-scope harnesses are checked when --project names their root. |
apothem harnesses list | --format, --json, --no-color, --quiet, -q, --verbose, -v | List all registered harness adapters. |
apothem harnesses show | --format, --json, --no-color, --quiet, -q, --verbose, -v | Show details for a specific harness adapter. |
apothem install | --clean, --fresh, --dry-run, --format, --harness, --json, --no-color, --profile, --project, --quiet, -q, --verbose, -v, --yes | Install a harness adapter configuration. |
apothem migrate-workspace | --dry-run, --format, --json, --no-color, --project, --quiet, -q, --verbose, -v | Migrate a legacy per-harness workspace into the shared .apothem layout. The base is the resolved --project root when supplied, otherwise the current working directory (the project-local default). Per-harness memory/contexts/learning stores union-merge into the shared store; a conflicting record is skipped, never overwritten; a legacy .plans tree moves under .apothem/plans; every consumed source is backed up first. The migration is idempotent. |
apothem profile edit | --format, --json, --no-color, --profile, --quiet, -q, --verbose, -v | Open the shared profile in the system editor. |
apothem profile init | --force, --format, --json, --no-color, --profile, --quiet, -q, --verbose, -v | Create a schema-valid shared profile scaffold. |
apothem profile set | --format, --json, --no-color, --profile, --quiet, -q, --verbose, -v | Set a key in the shared profile. KEY is a dotted path that descends into the nested profile structure (identity.name, preferences.style, enforcement.sprints, harnesses.<harness>.preferences.style); a single key with no dot sets a top-level node. VALUE is stored as a literal string — bare words are not coerced (no stays "no", 2024-01-01 and 1.0 stay strings) — except true/false (the boolean enforcement flags) and explicit [...]/{...} list/map input. The fully-assembled profile is validated against the packaged schema BEFORE writing; an invalid set is refused with the standard diagnostic and the profile on disk is unchanged. |
apothem profile show | --format, --json, --no-color, --profile, --quiet, -q, --verbose, -v | Display the current shared profile. |
apothem quickstart | --format, --harness, --json, --no-color, --profile, --project, --quiet, -q, --verbose, -v, --yes | Guided first run: ensure a profile, preview the writes, then install. Walks a new operator through the canonical path in one linear flow — create a starter profile if none exists (with a personalize nudge), preview the files each harness will write (project root vs your home directory), confirm, then install with the grouped capability-note output — and ends with the recommended next commands. --yes runs the whole sequence non-interactively; --format json emits one structured summary of every step. It composes the install building blocks; it does not duplicate them. Without --harness it asks which harness to install, so the first run writes one harness's configuration rather than all of them; all is an explicit choice. A run that cannot ask fails with a usage error before anything is written. |
apothem rollback | --format, --harness, --install-id, --json, --last, --no-color, --project, --quiet, -q, --verbose, -v, --yes | Restore a harness to the state before its recorded install. |
apothem status | --format, --json, --no-color, --profile, --project, --quiet, -q, --verbose, -v | Report install, verify, and drift state for every registered harness. |
apothem uninstall | --format, --harness, --json, --no-color, --project, --quiet, -q, --verbose, -v, --yes | Remove a harness adapter configuration. |
apothem update | --dry-run, --format, --harness, --json, --no-color, --profile, --project, --quiet, -q, --verbose, -v | Re-install a harness adapter configuration from the current profile. |
apothem verify | --format, --harness, --json, --no-color, --profile, --project, --quiet, -q, --verbose, -v | Verify a harness adapter installation. Without --profile the check is structural: every managed target must be present and valid. With --profile the check additionally requires profile fidelity, so a present-but-drifted install fails verify — answering "is THIS profile faithfully installed?" rather than merely "does it exist?". |