CLI reference

The oe binary is the primary interface to OpenExpertise. Install once:

npm install -g @openexpertise/cli

Then use:

oe <command> [options]

When developing from source (after pnpm -r build), you can also invoke via:

node packages/cli/dist/bin.js <command> [options]

All examples on this page use the short oe form.

Verbs at a glance

Command	Purpose
oe diff	List pending evolution proposals
oe evolve	Generate evolution proposals for a prior run
oe init	Scaffold a new experience directory
oe inspect	Render a run trace from the event log
oe reset-state	Delete the persistent state blackboard (destructive)
oe resume	Re-run an experience with cached results from a prior run
oe run	Execute an experience
oe state	Inspect the persistent state blackboard
oe ultra	LLM-author a new experience from a natural-language description
oe validate	Validate an experience.yaml file or directory

Global flags

These flags are accepted by every command and must be placed before the subcommand name.

Flag	Description	Default
--log-format <fmt>	Log format: json or pretty	pretty
--log-level <level>	Log verbosity: info, debug, warn, or error	info
-V, --version	Print the oe version and exit	—
-h, --help	Display help and exit	—

Example — machine-readable JSON logs:

oe --log-format json --log-level debug run examples/hello-tool

Standard exit codes

Code	Meaning
0	Success
1	Runtime failure (experience error, file not found, LLM error, etc.)
2	Invalid invocation (bad flag value, missing required argument)

Environment variables

Variable	Used by	Purpose
ANTHROPIC_API_KEY	run, resume, evolve, ultra	Authenticates against the Anthropic API; selects Anthropic as the default LLM provider
OPENAI_API_KEY	run, resume, evolve, ultra	Authenticates against the OpenAI API; selects OpenAI as the default LLM provider when ANTHROPIC_API_KEY is absent
OPENAI_BASE_URL	run, resume, evolve, ultra	Override the OpenAI-compatible endpoint (e.g. for vLLM or Ollama)

When both ANTHROPIC_API_KEY and OPENAI_API_KEY are set, Anthropic takes precedence unless --llm openai is passed.

Commands by use case

Author

Command	When to use
oe init	Bootstrap a new experience directory with a minimal scaffold
oe ultra	Describe a task in plain English; let the LLM write the YAML for you

Validate

Command	When to use
oe validate	Check YAML syntax and schema correctness before running

Run

Command	When to use
oe run	Execute an experience from scratch
oe resume	Re-run, reusing cached node results from a prior run

Inspect

Command	When to use
oe inspect	Replay the event log for a completed run
oe state	Read current values from the SQLite blackboard
oe diff	Preview pending evolution proposals

Evolve

Command	When to use
oe evolve	Ask the LLM advisor to analyse a run and propose YAML improvements
oe diff	See what proposals are waiting to be reviewed

Reset

Command	When to use
oe reset-state	Wipe the SQLite blackboard to start with a clean slate

See also

• Install & first run
• What is an experience?
• State (SQLite blackboard)
• Evolution loop