CLI reference

The apothem command-line interface manages harness adapter configurations from the shared profile. Each page below documents one subcommand: its synopsis, options, behavior, and exit codes.

Each of install, update, and uninstall also accepts a continuous-form alias (installing, updating, uninstalling) that is identical in flags and behavior to the base command. Updating and uninstalling through the install channels — the Claude Code plugin, npx, and the one-shot installer scripts — are documented in the Updating and Uninstalling install guides, not by the aliases themselves.

CommandsCopy Anchor Link

JSON output contractCopy Anchor Link

Every command except completion (which emits a shell script) accepts --json (shorthand for --format json) and then writes exactly one JSON document to stdout. Each document starts with a top-level schema_version key, an integer that is 1 today:

{"schema_version": 1, "status": "success", "command": "verify", "...": "..."}

• Stability. Within one schema_version, changes are additive: a new key can appear, but no key is renamed or removed and no value changes type. Anything else increases schema_version.
• Versioned artifacts. profile show --json emits the profile itself, so its schema_version is the profile schema version (also 1 today).
• One exception. harnesses list --json emits a JSON array (one object per harness), as it always has, so it has no top-level key to carry the version. Wrapping it in an object would break existing parsers; until a version bump does that, treat its shape as schema_version 1.
• Errors. Expected failures use the same document shape with "status": "error" and an error object carrying code, field, reason, and fix.

Exit codesCopy Anchor Link

Every command uses the same small set of exit codes; each page lists the ones it can return.

A usage error never touches the filesystem. Under --json (or --format json) it prints one error document with "code": "cli.usage" instead of the plain usage text, so automation can tell a mistyped flag from a partial write.

For slash commands and the higher-level CLI overview, see the CLI overview and Slash commands reference pages.