CLI Reference

This page lists the public ome command surface. The CLI is intentionally small: setup, recall, retrospective review, library governance, source import, diagnostics, and uninstall.

Output Contract

Default output is for humans. It should summarize what changed, what is healthy, and the next useful command without dumping internal JSON.

Use --json when a command is consumed by scripts, hooks, tests, or another agent. JSON failures still exit non-zero and print a parseable { ok: false, error: { message } } object.

ome init opens the setup flow in an interactive terminal. In CI, shell pipes, or agent runners, it skips prompts and uses flags/defaults. Use ome init --interactive when you want to force the guided setup flow.

Common Path

ome init
ome doctor
ome match "fix UI and validate in browser" --explain
ome uninstall

Setup

ome init
ome init --interactive
ome init --yes
ome init --provider claude
ome init --provider all
ome init --no-hook
ome init --reset-config

ome init is safe to run more than once. It installs the OME library, Codex skill, and selected prompt-time hooks. --reset-config restores runtime config without deleting experiences, source indexes, or retrospective runs.

Recall

ome match "<task>"
ome match "<task>" --json
ome match "<task>" --explain
ome match "<task>" --cwd /path/to/project --explain

Only active cards are recalled. Drafts created by a retrospective do not affect prompt-time recall until they are promoted.

When the current working directory is inside a project, recall reads the global dataDir and the optional project library at <project-root>/.oh-my-experience/. Use --cwd when a script needs to test a specific project context.

Sources

ome import codex --sessions <dir>
ome source status
ome source connect spool --mode ask
ome source import spool --limit 20
ome import spool --query "browser validation" --source codex

Spool is optional. If it is unavailable, Codex session import and local recall still work.

Retrospectives

ome reflect start
ome reflect start --scope project
ome reflect start --focus "browser validation and delivery gates"
ome reflect list
ome reflect show <run-id>
ome reflect add <run-id> --title "Browser validation" --summary "..." --rule "..."
ome reflect add <run-id> --title "Repo release gate" --summary "..." --rule "..." --triggers "release validation" --scope-level project --project-key github.com/example/repo
ome reflect candidates <run-id> --from-file <file>
ome reflect candidates <run-id> --scope project --from-file <file>
ome reflect candidates <run-id> --from-file <file> --audit-file <audit.json>
ome reflect decide <run-id> <candidate-id> --action approve --category "Product UI"
ome reflect apply <run-id> --dry-run
ome reflect apply <run-id>

ome reflect start --focus <text> sets the analysis lens for the run. It does not narrow source coverage, skip source audit, or lower the evidence bar unless the user explicitly constrained the source set.

ome reflect candidates requires a source audit before it writes candidates. Use --allow-incomplete-audit only for an explicit incomplete review; the generated worksheet will show the incomplete audit status.

Add --scope project when the retrospective should write candidates, drafts, and review files into the current project's .oh-my-experience/ library.

Project Libraries

ome project status
ome project init

ome project init creates <project-root>/.oh-my-experience/ with the standard experience lifecycle folders. It does not change dataDir.

ome project status --json reports the detected projectContext, project library path, whether the project library exists, whether it is readable, and any warnings.

Experience Library

ome experience list
ome experience list --scope project
ome experience list --status draft
ome experience list --compact --json
ome experience show <card-id>
ome experience show <card-id> --scope project --section rule
ome experience show <card-id> --section rule
ome experience promote <card-id>
ome experience promote <card-id> --scope project
ome experience archive <card-id> --reason "superseded"

The lifecycle stays explicit: candidate -> draft -> active -> archived. list --json returns full cards by default. Add --compact or --index when a script only needs the title index (id, title, status, category).

experience list --json is a governance command, so it reports invalid card files instead of stopping at the first parse error. The response includes invalidCards with status, path, and message. Runtime recall remains strict for active cards; invalid active cards must still be fixed before they can be recalled.

Evaluation

ome eval recall --suite <file>
ome eval recall --suite tests/fixtures/eval/core.json --limit 8
ome eval recall --suite my-suite.json --use-current-library
ome eval recall --compare before.json after.json

ome eval recall is deterministic and does not call an AI model. By default, it uses fixture cards in a temporary dataDir and never writes evaluation cards into the user's real library.

Diagnostics

ome doctor
ome doctor --repair-index
ome hook status
ome hook run
ome stats
ome version
ome -v
which -a ome

ome doctor checks dataDir writability, config schema, card lifecycle integrity, active index consistency, reflect state, hook status, event JSONL validity, package runtime requirements, and conflicting ome binaries on PATH. Invalid active or draft cards are errors. Invalid archived cards are reported as governance warnings because archived cards are history and never enter runtime recall.

ome hook run is the runtime entrypoint used by installed Codex and Claude hooks. It is kept public so installed hooks can execute it, but normal setup should happen through ome init.

Config

ome config get
ome config preview dataDir ~/Obsidian/Oh-My-Experience
ome config set dataDir ~/Obsidian/Oh-My-Experience

Uninstall

ome uninstall
ome uninstall --provider all
ome uninstall --keep-hooks
ome uninstall --keep-skill
ome uninstall --delete-library --yes

ome uninstall removes selected prompt-time hooks and the Codex OME skill, but keeps the experience library by default. Deleting the library is irreversible and requires --delete-library --yes or --delete-library --force.

Language Behavior

Human CLI output is English by default, including on non-English systems. Set OME_LANGUAGE=zh-CN only when you explicitly want Chinese CLI text.

JSON output field names stay stable English.