CLI reference
The ethos binary dispatches a single top-level subcommand. Running it with no arguments is equivalent to ethos chat.
Source
Top-level dispatch lives in apps/ethos/src/index.ts. Each case in the switch is a subcommand; per-command flag parsing lives in apps/ethos/src/commands/.
Synopsis
ethos [subcommand] [args...] [--version | --help]
If [subcommand] is omitted, ethos runs chat. If ~/.ethos/config.yaml is missing, the run is preceded by ethos setup.
The -q / --query / --query=<text> flag is recognised as a top-level alias for ethos chat -q <text>.
Top-level flags
| Flag | Aliases | Description |
|---|---|---|
--version | -v | Print the installed CLI version and exit. Combine with --json for structured metadata (name, version, node, platform, arch, supported providers and channels, managed mode status). |
--help | -h | Print the top-level usage line and exit. |
--query <text> | -q, --query=<text> | One-shot mode. Routes to chat with singleQuery; process exits after the response. |
ethos setup
Interactive first-run wizard. Writes ~/.ethos/config.yaml. Re-running is safe — answers default to the current config.
Synopsis: ethos setup [auth | model | personality | messaging | memory | providers | keys]
| Arg | Description |
|---|---|
| (none) | Start the wizard at the first step. |
auth | Jump to the auth step. |
model | Jump to the model-selection step. |
personality | Jump to the personality step. |
messaging | Jump to the channel-credentials step. |
memory | Jump to the memory-backend step. |
providers | Jump to the provider-chain step. |
keys | Jump to the key-rotation step. |
If the wizard completes with "launch chat", the process continues into ethos chat against the freshly written config.
ethos setup messaging
ethos chat
Interactive REPL with streaming output, persisted sessions, and slash commands. Sessions are keyed by cli:<basename of cwd>. See session.
Synopsis: ethos chat [--verbose] [--skin <name>] [-q <prompt>] [--continue] [--resume <id>] [--team <name>] [--dry-run]
| Flag | Default | Description |
|---|---|---|
--verbose | off | Print a per-turn timing summary (LLM time, TTFT, tool wall-clock, total, tokens, cost) after every response. Persistent equivalent: verbose: true in config. |
--skin <name> | from config | Override the resolved skin for this process only. Does not write to disk. |
-q <prompt>, --query <prompt> | off | Single-query mode. Stream one answer and exit. --query=<prompt> is also accepted. |
--continue, -c | off | Resume the most recent CLI session. Scoped to cli:* sessions only — never crosses into gateway sessions. |
--resume <id>, -r <id> | off | Resume a specific session by ID or title. Tries exact ID match first, then case-insensitive title match. When multiple sessions match, lists candidates instead of picking one. |
--no-resume-hint | off | Suppress the session-resume hint printed on exit. |
--team <name> | off | Override activeContext for this process, routing through a team coordinator. Does not write to disk. |
--dry-run | off | Dry-run mode — tools are planned but not executed. Toggle within a session with /dry-run on|off. |
ethos chat --verbose
ethos chat --continue
ethos chat --resume "research session"
ethos chat --team eng --dry-run
ethos -q "summarize the changes since yesterday"
ethos personality
Manage personalities. With no subcommand, lists every personality (built-in plus user) and marks the default.
Synopsis: ethos personality [list | show <id> | set <id> | duplicate <src> <dst> | mcp <id> [--attach <name> | --detach <name>] | plugins <id> [--attach <plugin-id> | --detach <plugin-id>]]
| Subcommand | Description |
|---|---|
list (default) | List built-ins and user personalities, marking the default. |
show <id> | Print the generated character sheet — identity, routing, memory scope, toolset, MCP servers, plugins, fs_reach. |
set <id> | Persist <id> as the default personality in ~/.ethos/config.yaml. |
duplicate <src> <dst> | Copy <src> into ~/.ethos/personalities/<dst>/ so it becomes user-editable. |
mcp <id> [--attach|--detach <name>] | Show, attach, or detach MCP servers from ~/.ethos/mcp.json. |
plugins <id> [--attach|--detach <id>] | Show, attach, or detach installed plugins. |
ethos personality show engineer
ethos personality duplicate engineer engineer-paired
ethos personality mcp engineer --attach github
ethos plugins
Print a plugin-by-personality attachment matrix. To install or remove plugins, use ethos plugin.
Synopsis: ethos plugins
ethos memory
View and edit the memory files. Behaviour depends on memory: in config — markdown (default) or vector.
Synopsis: ethos memory [show | add "<text>" | clear | export [path]]
| Subcommand | Args | Description |
|---|---|---|
show (default) | — | Markdown mode: print MEMORY.md + USER.md. Vector mode: print the 20 most recent chunks. |
add | "<text>" | Append to memory. In vector mode, embed and chunk. |
clear | — | Wipe memory. In vector mode, prompts for confirmation. |
export | [path] | Vector mode only. Export all chunks to a markdown file. Default: ~/.ethos/memory-export-<ts>.md. |
ethos memory add "Mitesh prefers terse explanations."
ethos gateway
Configure and run the multi-platform message gateway — the surface that brings Telegram, Slack, Discord, WhatsApp, and Email senders into the same agent.
Synopsis: ethos gateway [setup | start]
setup opens the setup wizard at the messaging step (alias for ethos setup messaging). start spins up every platform whose credentials are present in config.yaml and is long-running; exits non-zero if ~/.ethos/config.yaml is absent.
ethos cron
Schedule prompts to fire on cron expressions. list (default) shows every job with schedule, last run, next run. create schedules a new job (flags below). pause <id> / resume <id> / delete <id> manage existing jobs. run <id> fires immediately.
Synopsis: ethos cron [list | create | pause <id> | resume <id> | delete <id> | run <id>]
Flags for create:
| Flag | Required | Description |
|---|---|---|
--name, -n <name> | yes | Human-readable job name. |
--schedule, -s <expr> | yes | 5-field cron expression (e.g. 0 8 * * *). |
--prompt, -p <text> | yes | Prompt the agent runs on each fire. |
--personality <id> | no | Override the default personality for this job. |
--deliver <target> | no | Delivery target (Telegram chat id, Slack channel, etc.). |
ethos cron create -n "Daily standup" -s "0 8 * * 1-5" -p "What's on my calendar today?"
ethos acp
Run the Agent Control Protocol server. JSON-RPC over stdin/stdout. Long-running; typically spawned by an orchestrator.
Synopsis: ethos acp
ethos serve
Start the Ethos web UI and HTTP API on a local port. Long-running.
Synopsis: ethos serve [--port <n>] [--bind <addr>] [--team <name>] [--mesh <name>]
| Flag | Default | Description |
|---|---|---|
--port <n> | 3000 | HTTP port. |
--bind <addr> | 127.0.0.1 | Bind address. Use 0.0.0.0 to expose to LAN; still token-protected. |
--team <name> | off | Resolve the agent against a team coordinator and mesh. |
--mesh <name> | default | Explicit mesh name when --team is not set. |
On first run, prints http://localhost:3000?t=<token>; the token rotates into an httpOnly cookie on first browser visit.
ethos status
Single-pane health summary — config, adapters, personalities, error log. Exits non-zero if critical issues are found.
Synopsis: ethos status [--json]
| Flag | Default | Description |
|---|---|---|
--json | off | Machine-readable JSON output with version, config, adapter status, personality count, and error log summary. |
ethos status
ethos status --json
ethos batch
Run a JSONL of prompts in parallel against the configured agent. Outputs JSONL. Required positional: <tasks.jsonl> — one task per line as {"id": "...", "prompt": "..."}. Optional: --concurrency (default 3), --output (default <input>.output.jsonl), --checkpoint (default <input>.checkpoint.json) — re-running with the same checkpoint skips already-completed tasks.
Synopsis: ethos batch <tasks.jsonl> [--concurrency <n>] [--output <out>] [--checkpoint <cp>]
ethos eval
Score the agent's output against expected answers. Required: --expected <file> (JSONL keyed by id). Optional: --scorer (exact / contains / regex / llm, default contains), --concurrency (default 3), --output (default <input>.eval.jsonl), --evolve to chain skill evolution after scoring, --auto-approve (with --evolve) to promote evolved skills directly without queuing for review.
Synopsis: ethos eval run <tasks.jsonl> --expected <expected.jsonl> [--scorer <name>] [--concurrency <n>] [--output <out>] [--evolve [--auto-approve]]
ethos evolve
Generate candidate skill files from session history or a prior eval run and queue them for review. Supports both a newer subcommand style and the original flag-based style.
Synopsis (subcommand style):
ethos evolve status
ethos evolve run [--quiet]
ethos evolve apply <filename> | --all [-y]
Synopsis (legacy flag style — backwards-compatible):
ethos evolve --eval-output <file> [--auto-approve]
ethos evolve --list-pending
ethos evolve --approve <name> | --approve-all
ethos evolve --reject <name>
Subcommands
| Subcommand | Description |
|---|---|
status | Show evolver run history and the pending queue. |
run [--quiet] | Export recent sessions (last 7 days from sessions.db), run the evolver against them, and queue candidates for review. --quiet suppresses progress output — the cron-safe equivalent of the legacy --eval-output path. |
apply <filename> | --all [-y] | Promote pending skills into ~/.ethos/skills/. --all promotes every pending file. -y skips the confirmation prompt. |
Legacy flags
| Flag | Description |
|---|---|
--eval-output <file> | Run evolution against a specific eval output file and write candidates to ~/.ethos/skills/pending/. |
--auto-approve | With --eval-output, skip the pending queue and promote directly. |
--list-pending | Show the pending queue. |
--approve <name> | Promote one pending candidate into ~/.ethos/skills/. --accept is an alias. |
--approve-all | Promote all pending candidates. --accept-all is an alias. |
--reject <name> | Delete a pending candidate. |
ethos plugin
Install, list, and remove individual plugins (npm packages or local paths). For a personality-attachment overview, use ethos plugins.
Synopsis: ethos plugin [list | install <path-or-pkg> | remove <id>]
ethos skills
Install ClawHub-compatible skills (markdown files with frontmatter). list (default) shows installed skills. install <slug> installs from ClawHub — slug formats: owner/repo, github:owner/repo, github:owner/repo/path. update [<slug>] updates one or all. remove <slug> uninstalls.
Synopsis: ethos skills [list | install <slug> | update [<slug>] | remove <slug>]
ethos keys
Manage the API-key rotation pool at ~/.ethos/keys.json (chmod 600). list (default) prints masked keys with labels and priorities. add <key> [--label <name>] [--priority <n>] appends; priority defaults to 50 and higher values are chosen first. remove <index> deletes the 1-based entry.
Synopsis: ethos keys [list | add <api-key> [--label <name>] [--priority <n>] | remove <index>]
ethos set
Set or inspect the active context that chat and serve route through. ethos set with no args prints the current context. ethos set personality <id> routes to a single personality; ethos set team <name> routes to a team coordinator (start it separately with ethos team start <name>).
Synopsis: ethos set [personality <id> | team <name>]
ethos team
Manage team manifests and the supervisor lifecycle.
Synopsis: ethos team [list | create <name> | <name> add <personality> | <name> remove <personality> | start <name> | stop <name> | status <name> | logs <name> [--member <id>]]
ethos mesh
Inspect mesh-level runtime state (live member counts, per-mesh registries).
Synopsis: ethos mesh [list | status <name> | create <name> | destroy <name>]
ethos process
Inspect and stop background processes started by the process_* tool family inside ethos chat. The subcommands drive the same registry helpers the tools use, so list / logs / stop produce the same output and lifecycle behaviour the agent sees — letting you watch or kill a process from a separate shell.
Synopsis: ethos process [list [--json] | logs <id> [--lines N] [--stream stdout|stderr|both] | stop <id> [--signal SIGTERM|SIGKILL]]
| Subcommand | Args / flags | Description |
|---|---|---|
list (default) | --json | List every tracked process with PID, status, and duration. Runs a liveness check (marks dead running entries as orphan) and reaps stale terminal entries. --json emits the raw array instead of a table. |
logs <id> | --lines N, --stream stdout|stderr|both | Print the last N lines (default 200) of a process's logs. --stream selects which log; default both interleaves stdout then stderr. |
stop <id> | --signal SIGTERM|SIGKILL | Signal a running process. Default SIGTERM waits up to 5 s for a graceful exit, then escalates to SIGKILL. |
ethos process list
ethos process logs 6f6c1e2a-... --lines 50 --stream stderr
ethos process stop 6f6c1e2a-...
logs and stop exit 1 for an unknown id (PROCESS_NOT_FOUND). The process_* tool family it mirrors — process_start, process_list, process_logs, process_stop, process_wait — is documented in extensions/tools-process/README.md; it is gated by a personality's toolset.yaml like every other tool.
ethos logs
Inspect and bundle local diagnostics from ~/.ethos/logs/.
Synopsis: ethos logs [list | summary | note | bundle [--out <path>] [--lines <n>] | tail [--lines <n>] [--interval-ms <n>]]
ethos mcp
Expose Ethos to MCP-compatible clients (Claude Desktop, Cursor, OpenCode, Continue, Zed) over stdio.
Synopsis: ethos mcp [serve | install --client <name> | init | doctor | inspect]
Supported --client values: claude-desktop, cursor, opencode, continue, zed.
ethos backup
Snapshot ~/.ethos/ to a tarball. With no argument, writes ./ethos-backup-<timestamp>.tar.gz. A directory argument writes a timestamped file inside it; a filename argument writes there directly.
Synopsis: ethos backup [<path>]
ethos import
Restore a backup tarball into ~/.ethos/. Without flags, refuses when ~/.ethos/ already has content. --merge unions by personality id (newer mtime wins) and appends to MEMORY.md / USER.md. --force removes existing ~/.ethos/ first.
Synopsis: ethos import <path> [--merge | --force]
ethos trace
Inspect persisted traces from the observability store.
Synopsis: ethos trace [list | show <id> | export <id> [--out <path>]]
ethos audit
Inspect the audit-event log (channel approvals, key rotations, personality writes).
Synopsis: ethos audit [list | show <id>]
ethos security audit
Run the local security audit — permission diffs, exposed secrets, untrusted skill warnings. --fix auto-remediates the safe subset; --json emits machine-readable findings; --deep runs the slower, network-touching checks. Exits 2 on usage error (e.g. ethos security with no audit arg).
Synopsis: ethos security audit [--fix] [--json] [--deep]
ethos errors
Inspect ~/.ethos/logs/errors.jsonl.
Synopsis: ethos errors [list | show <id> | clear]
ethos perf
Per-turn performance summaries from the local trace store.
Synopsis: ethos perf [summary | turn <id>]
ethos tail
Live-tail every known Ethos log file in one stream.
Synopsis: ethos tail [--lines <n>] [--interval-ms <n>]
ethos retention
Inspect and run retention sweeps for observability data.
Synopsis: ethos retention [show | run [--dry-run]]
ethos data
Inspect local data stores (sessions, traces, blobs).
Synopsis: ethos data [stats | sessions | traces]
ethos support
Generate a support bundle for issue triage.
Synopsis: ethos support [bundle [--out <path>]]
ethos archive
Manage long-term archive of sessions and memory.
Synopsis: ethos archive [list | create | restore <id>]
ethos systemd-unit
Generate a systemd service unit file for a given Ethos command. Writes to stdout — pipe to a file or inspect before installing.
Synopsis: ethos systemd-unit <name>
| Name | Description |
|---|---|
ethos-gateway | Unit for ethos gateway start. |
ethos-serve | Unit for ethos serve. |
ethos-runall | Unit for ethos run-all. |
Placeholder values are substituted from environment variables at generation time:
| Placeholder | Env var | Default |
|---|---|---|
{{ETHOS_BINARY}} | ETHOS_BINARY | ethos |
{{ETHOS_USER}} | ETHOS_USER | $USER (current user) |
{{ETHOS_HOME}} | ETHOS_HOME | $HOME |
Generated units set ETHOS_MANAGED=1 and load ~/.ethos/.env via EnvironmentFile. Values containing newlines are rejected.
ethos systemd-unit ethos-gateway > ~/.config/systemd/user/ethos-gateway.service
systemctl --user daemon-reload
systemctl --user enable --now ethos-gateway
ethos usage
Aggregate token usage and estimated cost over a time window. Reads from ~/.ethos/sessions.db.
Synopsis: ethos usage --since <duration> [--json]
| Flag | Required | Description |
|---|---|---|
--since <duration> | yes | Time window. Format: Nh (hours), Nd (days), Nm (minutes). Example: 24h, 7d, 30m. |
--json | no | Emit machine-readable JSON instead of a human-readable summary. |
The JSON output includes totals, byProvider, byPersonality, and a truncated flag (true when results exceed the 10,000-session cap — narrow the --since window for complete data).
ethos usage --since 7d
ethos usage --since 24h --json
ethos claw
Migrate an OpenClaw install (~/.claw/) into Ethos (~/.ethos/). Idempotent.
Synopsis: ethos claw migrate [--dry-run] [--preset all|user-data] [--overwrite] [--yes]
--dry-run prints the plan without writing. --preset all (default) migrates everything; user-data skips personalities. --overwrite replaces existing Ethos files on conflict. --yes / -y skips the confirmation prompt.
ethos doctor
Diagnostic — checks config, provider auth, session-store integrity, key permissions.
Synopsis: ethos doctor [--json]
ethos upgrade
Check npm for a newer @ethosagent/cli and install it. Detects npm-global vs source clone and prints the right instructions.
Synopsis: ethos upgrade
Exit codes
| Code | Meaning |
|---|---|
0 | Success. |
1 | Generic error (missing config, command parse error, network failure, unknown subcommand). |
2 | Managed-mode error: ETHOS_MANAGED=1 is set but config is missing, or a usage error (e.g. ethos security with no audit arg). |
130 | Interrupted (Ctrl+C / SIGINT). |
Errors land on stderr formatted by formatError(toEthosError(err)) and are appended to ~/.ethos/logs/errors.jsonl. Set ETHOS_DEBUG=1 for verbose tracing.
Environment variables
| Variable | Description |
|---|---|
ANTHROPIC_API_KEY | Anthropic provider key (overrides apiKey for Anthropic). |
OPENAI_API_KEY | OpenAI / OpenAI-compat provider key. |
OPENROUTER_API_KEY | OpenRouter key. |
ETHOS_DEBUG | 1 prints hook events, token counts, and prompt diagnostics. |
ETHOS_DIR | Override the ~/.ethos/ location entirely. |
ETHOS_VERSION | Override the reported version string (dev runs). |
ETHOS_DEDUP_LEGACY | 1 disables the outbound dedup cache (rollback hatch). |
ETHOS_MANAGED | 1 runs in managed mode — skip interactive setup, exit 2 if config is missing. Used by systemd units and orchestration playbooks. |
ETHOS_BINARY | Override the ethos binary path in ethos systemd-unit output. |
ETHOS_USER | Override the service user in ethos systemd-unit output. |
ETHOS_HOME | Override the home directory in ethos systemd-unit output and EnvironmentFile path. |
ETHOS_ENV_FILE | Override the .env file path for secrets loading (default: ~/.ethos/.env). |
See also
config.yamlreference — every field these subcommands read and write.- Personality config reference — the per-personality
config.yaml+toolset.yamlthatethos personalityscaffolds. - Slash commands reference — every
/commandavailable insideethos chat. - Glossary — every Ethos term in one definition list, anchored for cross-page links.