CLI Commands Reference

This page covers the terminal commands you run from your shell.

For in-chat slash commands, see Slash Commands Reference.

Global entrypoint

minerva [global-options] <command> [subcommand/options]

Global options

Option	Description
--version, -V	Show version and exit.
--profile <name>, -p <name>	Select which Minerva profile to use for this invocation. Overrides the sticky default set by minerva profile use.
--resume <session>, -r <session>	Resume a previous session by ID or title. The keyword latest resumes the most recent session (workspace-scoped, same lookup as -c).
--continue [name], -c [name]	Resume the most recent session, or the most recent session matching a title.
--in <dir>	Change into <dir> before starting or resuming. Scopes --resume latest / -c lookups to that directory's workspace and keeps the session there (skips the recorded-cwd restore).
--worktree, -w	Start in an isolated git worktree for parallel-agent workflows.
--yolo	Bypass dangerous-command approval prompts.
--pass-session-id	Include the session ID in the agent's system prompt.
--ignore-user-config	Ignore ~/.minerva/config.yaml and fall back to built-in defaults. Credentials in .env are still loaded.
--ignore-rules	Skip auto-injection of AGENTS.md, SOUL.md, .cursorrules, memory, and preloaded skills.
--tui	Launch the TUI instead of the classic CLI. Equivalent to MINERVA_TUI=1. Always wins over display.interface.
--cli	Force the classic prompt_toolkit REPL. Use this to override display.interface: tui for a single invocation.
--dev	With --tui: run the TypeScript sources directly via tsx instead of the prebuilt bundle (for TUI contributors).

Top-level commands

Command	Purpose
minerva chat	Interactive or one-shot chat with the agent.
minerva model	Interactively choose the default provider and model.
minerva moa	Configure named Mixture of Agents presets selectable from the model picker.
minerva fallback	Manage fallback providers tried when the primary model errors.
minerva worktree	Audit and reclaim the .worktrees/ trees that minerva -w sessions accumulate, plus fully merged local branches (list, prune). See Worktree cleanup.
minerva browser	Real-profile browsing helpers. close-profile closes the browser that holds your default profile so Minerva can copy it (unsaved tabs are lost; the agent runs it only after you approve).
minerva gateway	Run or manage the messaging gateway service.
minerva proxy	Local OpenAI-compatible proxy that attaches OAuth provider credentials. See Subscription Proxy.
minerva egress	Outbound credential-injection firewall for remote terminal sandboxes (iron-proxy). Disabled by default. See Egress proxy.
minerva lsp	Manage Language Server Protocol integration (semantic diagnostics for write_file/patch).
minerva setup	Interactive setup wizard for all or part of the configuration.
minerva slack	Slack helpers (currently: generate the app manifest with every command as a native slash).
minerva auth	Manage credentials — add, list, remove, reset, status, logout. Handles OAuth flows for Codex/Anthropic.
minerva login / whoami / account	Sign in to your Minerva account on this machine, show which account it uses, or manage it (account login, account logout, account whoami). Not for model providers — use minerva auth for those.
minerva logout	Clear stored model-provider credentials (--provider openai-codex or xai-oauth) and reset provider config. Account sign-out is minerva account logout.
minerva send	Send a one-shot message to a configured messaging platform (Telegram, Discord, Slack, …). Useful from shell scripts, cron jobs, CI hooks, and monitoring daemons — no agent loop, no LLM.
minerva peer	Register peer Minerva gateways on other machines and DM their agents' canonical Bot Chats (minerva peer dm <peer>[/<agent>] "…"). The transport behind cross-machine bot-to-bot messaging.
minerva secrets	Manage external secret sources (Bitwarden Secrets Manager, 1Password) for pulling API keys at process startup instead of from ~/.minerva/.env.
minerva migrate	Diagnose and (optionally) rewrite config.yaml to replace references to retired models or deprecated settings (e.g. migrate xai).
minerva status	Show agent, auth, and platform status.
minerva pause / resume	Emergency stop: pause [--reason TEXT] halts new cron dispatch, kanban dispatch, and new gateway turns (in-flight work is not killed) until minerva resume.
minerva cron	Inspect and tick the cron scheduler.
minerva kanban	Multi-profile collaboration board (tasks, links, dispatcher).
minerva project	Manage named, multi-folder workspaces (projects). Anchors desktop session grouping and, when bound to a kanban board, gives tasks a deterministic worktree + branch convention. State is per-profile.
minerva webhook	Manage dynamic webhook subscriptions for event-driven activation.
minerva hooks	Inspect, approve, or remove shell-script hooks declared in config.yaml.
minerva doctor	Diagnose config and dependency issues.
minerva verify [path]	Detect how a project is built, tested, and started (or load its saved .minerva/environment.json), then run bootstrap → build → test → start → readiness poll → teardown. --detect-only prints the recipe, --save stores it, --phase runs selected phases, --skip-start skips the app start, --json emits a machine-readable result.
minerva security audit	On-demand supply-chain audit (OSV.dev) for the venv, plugin requirements, and pinned MCP servers.
minerva approvals	Approval-prompt tools — mine approval history into allowlist proposals (suggest) and dry-run a command's approval verdict (test).
minerva dump	Copy-pasteable setup summary for support/debugging.
minerva prompt-size	Show a byte breakdown of the system prompt + tool schemas (skills index, memory, profile). Runs offline.
minerva debug	Debug tools — upload logs and system info for support.
minerva backup	Back up Minerva home directory to a zip file.
minerva checkpoints	Inspect / prune / clear ~/.minerva/checkpoints/ (the shadow store used by /rollback). Run with no args for a status overview.
minerva import	Restore a Minerva backup from a zip file.
minerva logs	View, tail, and filter agent/gateway/error log files.
minerva config	Show, edit, migrate, and query configuration files.
minerva skin	List, switch, and tweak display skins.
minerva console	Open the safe Minerva command console.
minerva pairing	Approve or revoke messaging pairing codes.
minerva skills	Browse, install, publish, audit, and configure skills.
minerva bundles	Group several skills under a single /<name> slash command. See Skill Bundles.
minerva curator	Background skill maintenance — status, run, pause, pin. See Curator.
minerva journey (aliases learning, memory-graph)	Timeline of learned skills + memories over time.
minerva memory	Configure external memory provider. Plugin-specific subcommands (e.g. minerva honcho) register automatically when their provider is active.
minerva acp	Run Minerva as an ACP server for editor integration.
minerva mcp	Manage MCP server configurations and run Minerva as an MCP server.
minerva plugins	Manage Minerva Agent plugins (install, enable, disable, remove).
minerva tools	Configure enabled tools per platform.
minerva computer-use	Install or check the Computer Use (cua-driver) backend (macOS/Windows/Linux).
minerva pets	Browse, install, and select petdex animated pets shown across the CLI, TUI, and desktop app. Subcommands: list, install, select, show, off, scale, remove, doctor.
minerva sessions	Browse, export, prune, rename, and delete sessions.
minerva insights	Show token/cost/activity analytics.
minerva monitoring status	Show gateway monitoring settings, OTLP export state, and redaction posture. Monitoring exports service-health metrics and redacted diagnostics to an endpoint you configure under monitoring.* in config.yaml; it carries no prompts, messages, or tool arguments.
minerva import-agent	Import a Claude Code (~/.claude) or Codex CLI (~/.codex) setup.
minerva dashboard	Removed browser UI. Bare invocation prints a notice pointing to the desktop app and minerva serve; --stop / --status still manage the backend server process.
minerva serve	Start the Minerva backend server (headless; powers the desktop app and remote backends).
minerva desktop (alias gui)	Build and launch the native Electron desktop app.
minerva profile	Manage profiles — multiple isolated Minerva instances.
minerva completion	Print shell completion scripts (bash/zsh/fish).
minerva --version	Show version information.
minerva update	Pull latest code and reinstall dependencies. --check previews without installing; --backup takes a pre-pull MINERVA_HOME snapshot.
minerva uninstall	Remove Minerva from the system.

minerva chat

minerva chat [options]

Common options:

Option	Description
-q, --query "..."	Seed the session with a prompt. On a real TTY the prompt is submitted literally as the first turn of a normal interactive session (it is never parsed as a slash command or ! shell escape) and the session stays open — ideal for OS launchers and desktop integrations. With --oneshot, -Q, or non-TTY stdio it answers and exits.
--query-file PATH	Read the query from a file (- = stdin). Nothing is shell-interpreted, so quotes, $(...), and backticks arrive verbatim — use this for programmatic or untrusted message bodies (Bot Mode teammate DMs use it). Mutually exclusive with -q.
--oneshot	With -q/--query-file: answer the query and exit (the pre-0.21 single-query behavior) instead of seeding an interactive session. Implied on non-TTY stdio and by -Q.
-m, --model <model>	Override the model for this run.
-t, --toolsets <csv>	Enable a comma-separated set of toolsets.
--provider <provider>	Force a provider: auto, openrouter, openai-codex, copilot, anthropic, gemini, huggingface, chutes (aliases chutes-ai, sn64), openai-api, zai, kimi-coding, kimi-coding-cn, minimax, minimax-cn, minimax-oauth, xiaomi, alibaba, alibaba-cn, alibaba-coding-plan (alias alibaba_coding), alibaba-coding-plan-cn, alibaba-token-plan, alibaba-token-plan-cn, deepseek, nvidia, ollama-cloud, xai (alias grok), xai-oauth (alias grok-oauth), qwen-oauth, opencode-zen, opencode-go, opencode-free (aliases free, opencode_free; keyless), lmstudio, stepfun, tencent-tokenhub (alias tencent, tokenhub), tencent-tokenplan (aliases tokenplan, tencent-lkeap), fireworks, deepinfra, custom (a direct API endpoint you configure), and moa (Mixture of Agents presets). There is no argparse choices= on this flag, so an unknown value is rejected downstream, not by the parser.
-s, --skills <name>	Preload one or more skills for the session (can be repeated or comma-separated).
-v, --verbose	Verbose output.
-Q, --quiet	Programmatic mode: suppress banner/spinner/tool previews.
--image <path>	Attach a local image to a single query.
--resume <session> / --continue [name]	Resume a session directly from chat.
--worktree	Create an isolated git worktree for this run.
--checkpoints	Enable filesystem checkpoints before destructive file changes.
--yolo	Skip approval prompts.
--pass-session-id	Pass the session ID into the system prompt.
--ignore-user-config	Ignore ~/.minerva/config.yaml and use built-in defaults. Credentials in .env are still loaded. Useful for isolated CI runs, reproducible bug reports, and third-party integrations.
--ignore-rules	Skip auto-injection of AGENTS.md, SOUL.md, .cursorrules, persistent memory, and preloaded skills. Combine with --ignore-user-config for a fully isolated run.
--safe-mode	Troubleshooting mode: disable ALL customizations — user config, rules/memory injection, plugins, shell hooks, and MCP servers (implies --ignore-user-config and --ignore-rules). Use to isolate whether a problem comes from your setup or from Minerva itself.
--source <tag>	Session source tag for filtering (default: cli). Use tool for third-party integrations that should not appear in user session lists.
--max-turns <N>	Maximum tool-calling iterations per conversation turn. Overrides agent.max_turns in config, which is unlimited by default.

Examples:

minerva
minerva chat -q "Summarize the latest PRs"          # seeds an interactive session
minerva chat --oneshot -q "Summarize the latest PRs"  # answer and exit
minerva chat --provider openrouter --model anthropic/claude-sonnet-4.6
minerva chat --toolsets web,terminal,skills
minerva chat --quiet -q "Return only JSON"
minerva chat --worktree -q "Review this repo and open a PR"
minerva chat --ignore-user-config --ignore-rules -q "Repro without my personal setup"
minerva chat --safe-mode -q "Is this bug mine or Minerva's?"

minerva -z <prompt> — scripted one-shot

For programmatic callers (shell scripts, CI, cron, parent processes piping in a prompt), minerva -z is the purest one-shot entry point: single prompt in, final response text out, nothing else on stdout or stderr. No banner, no spinner, no tool previews, no Session: line — just the agent's final reply as plain text.

minerva -z "What's the capital of France?"
# → Paris.

# Parent scripts can cleanly capture the response:
answer=$(minerva -z "summarize this" < /path/to/file.txt)

Per-run overrides (no mutation to ~/.minerva/config.yaml):

Flag	Equivalent env var	Purpose
-m / --model <model>	MINERVA_INFERENCE_MODEL	Override the model for this run
--provider <provider>	(none)	Override the provider for this run
--usage-file <path>	(none)	Write a JSON usage report after the run (see below)

minerva -z "…" --provider openrouter --model openai/gpt-5.5
# or:
MINERVA_INFERENCE_MODEL=anthropic/claude-sonnet-4.6 minerva -z "…"

Same agent, same tools, same skills — just strips every interactive / cosmetic layer. If you need tool output in the transcript too, use minerva chat --oneshot -q instead; -z is explicitly for "I only want the final answer".

--usage-file — JSON usage report for pipelines

minerva -z "…" --usage-file /path/report.json writes a machine-readable usage report after the run: estimated_cost_usd, input_tokens / output_tokens / cache_read_tokens / cache_write_tokens / reasoning_tokens / total_tokens, api_calls, model, provider, session_id, service_tier, and completed / failed flags. The report is written even when the run fails, so batch pipelines can always account for spend. It has no effect outside -z/--oneshot, and a broken usage write never masks the run's own outcome.

minerva -z "summarize this repo" --usage-file /tmp/usage.json
jq .estimated_cost_usd /tmp/usage.json

minerva model

Interactive provider + model selector. This is the command for adding new providers, setting up API keys, and running OAuth flows. Run it from your terminal — not from inside an active Minerva chat session.

minerva model

Use this when you want to:

• add a new provider (OpenRouter, Anthropic, Copilot, DeepSeek, custom, etc.)
• log into OAuth-backed providers (Anthropic, Copilot, Codex)
• enter or update API keys
• pick from provider-specific model lists
• configure a custom/self-hosted endpoint
• save the new default into config

minerva model vs /model — know the difference

minerva model (run from your terminal, outside any Minerva session) is the full provider setup wizard. It can add new providers, run OAuth flows, prompt for API keys, and configure endpoints.

/model (typed inside an active Minerva chat session) can only switch between providers and models you've already set up. It cannot add new providers, run OAuth, or prompt for API keys.

If you need to add a new provider: Exit your Minerva session first (Ctrl+C or /quit), then run minerva model from your terminal prompt.

/model slash command (mid-session)

Switch between already-configured models without leaving a session:

/model                              # Show current model and available options
/model claude-sonnet-4              # Switch model (auto-detects provider)
/model zai:glm-5                    # Switch provider and model
/model custom:qwen-2.5              # Use model on your custom endpoint
/model custom                       # Auto-detect model from custom endpoint
/model custom:local:qwen-2.5        # Use a named custom provider
/model openrouter:anthropic/claude-sonnet-4  # Switch back to cloud

By default, /model changes apply to the current session only. Add --global to persist the change to config.yaml (or set model.persist_switch_by_default: true to make every switch persist):

/model claude-sonnet-4 --global     # Switch and save as new default

What if I only see OpenRouter models?

If you've only configured OpenRouter, /model will only show OpenRouter models. To add another provider (Anthropic, DeepSeek, Copilot, etc.), exit your session and run minerva model from the terminal.

On a --global switch, provider and base URL changes are persisted to config.yaml alongside the model. When switching away from a custom endpoint, the stale base URL is cleared to prevent it leaking into other providers.

minerva gateway

minerva gateway <subcommand>

Subcommands:

Subcommand	Description
run	Run the gateway in the foreground. Recommended for WSL, Docker, and Termux.
start	Start the installed systemd/launchd background service.
stop	Stop the service (or foreground process).
restart	Restart the service.
status	Show service status.
list	List all profiles and whether each profile's gateway is currently running (with PID where available). Handy when you run multiple profiles side-by-side and want a single overview.
install	Install as a systemd (Linux) or launchd (macOS) background service.
uninstall	Remove the installed service.
setup	Interactive messaging-platform setup.
migrate-legacy	Remove legacy minerva.service units left over from pre-rename installs. Profile units (minerva-gateway-<profile>.service) and unrelated services are never touched. Flags: --dry-run, -y/--yes.

Options:

Option	Description
--all	On start / restart / stop: act on every profile's gateway, not just the active MINERVA_HOME. Useful if you run multiple profiles side-by-side and want to restart them all after minerva update.
--no-supervise	On run: inside the s6-overlay Docker image, opt out of auto-supervision and use pre-s6 foreground semantics — gateway runs as the container's main process with no auto-restart. No-op outside the s6 image. Equivalent to setting MINERVA_GATEWAY_NO_SUPERVISE=1.
--external-supervisor	On run: declare that a wrapper-provided process manager owns the foreground gateway. Use this when sudo, env -i, or another wrapper strips launchd/systemd's native environment marker. In-chat restarts and updates exit back to that manager instead of spawning a detached replacement.

--external-supervisor is a restart-policy contract: an in-chat restart or service-restart update exits with status 75, so the wrapper's supervisor must relaunch the gateway after that nonzero exit. For systemd, use Restart=on-failure or Restart=always and do not include 75 in RestartPreventExitStatus; for launchd, configure KeepAlive to relaunch after unsuccessful exits. Without that policy, a requested restart leaves the gateway stopped.

WSL users

Use minerva gateway run instead of minerva gateway start — WSL's systemd support is unreliable. Wrap it in tmux for persistence: tmux new -s minerva 'minerva gateway run'. See WSL FAQ for details.

minerva lsp

minerva lsp <subcommand>

Manage the Language Server Protocol integration. LSP runs real language servers (pyright, gopls, rust-analyzer, …) in the background and feeds their diagnostics into the post-write check used by write_file and patch. Gated on git workspace detection — LSP only runs when the cwd or edited file is inside a git worktree.

Subcommands:

Subcommand	Description
status	Show service state, configured servers, install status.
list	Print the registry of supported servers. Pass --installed-only to skip missing ones.
install <id>	Eagerly install one server's binary.
install-all	Install every server with a known auto-install recipe.
restart	Tear down running clients so the next edit re-spawns.
which <id>	Print the resolved binary path for one server.

See LSP — Semantic Diagnostics for the full guide, supported languages, and configuration knobs.

minerva setup

minerva setup [model|tts|terminal|gateway|tools|telemetry|agent] [--non-interactive] [--reset] [--quick] [--reconfigure]

First run: launches the first-time wizard.

Returning user (already configured): drops straight into the full reconfigure wizard — every prompt shows your current value as its default, press Enter to keep or type a new value. No menu.

Jump into one section instead of the full wizard:

Section	Description
model	Provider and model setup.
tts	Text-to-speech provider and voice setup.
terminal	Terminal backend and sandbox setup.
gateway	Messaging platform setup.
tools	Enable/disable tools per platform.
telemetry	Monitoring / diagnostics export settings.
agent	Agent behavior settings.

Options:

Option	Description
--quick	On returning-user runs: only prompt for items that are missing or unset. Skip items you already have configured.
--non-interactive	Use defaults / environment values without prompts.
--reset	Reset configuration to defaults before setup.
--reconfigure	Backwards-compat alias — bare minerva setup on an existing install now does this by default.

minerva slack

minerva slack manifest              # print manifest to stdout
minerva slack manifest --write      # write to ~/.minerva/slack-manifest.json
minerva slack manifest --long-description-file AGENTS.md --write
minerva slack manifest --slashes-only  # just the features.slash_commands array

Generates a Slack app manifest that registers every gateway command in COMMAND_REGISTRY (/btw, /stop, /model, …) as a first-class Slack slash command — matching Discord and Telegram parity. Paste the output into your Slack app config at https://api.slack.com/apps → your app → Features → App Manifest → Edit, then Save. Slack prompts for reinstall if scopes or slash commands changed.

Flag	Default	Purpose
--write [PATH]	stdout	Write to a file instead of stdout. Bare --write writes $MINERVA_HOME/slack-manifest.json.
--name NAME	Minerva	Bot display name in Slack.
--description DESC	default blurb	Bot description shown in the Slack app directory.
--long-description TEXT	unset	Set display_information.long_description inline (175–4,000 characters). Incompatible with --slashes-only.
--long-description-file PATH	unset	Read the long description from a UTF-8 text file, preserving its contents exactly. Mutually exclusive with --long-description and incompatible with --slashes-only.
--slashes-only	off	Emit only features.slash_commands for merging into a manually-maintained manifest.
--agent-view	off	Emit Slack's Agent messaging experience (agent_view, app_home_opened + message.im) instead of the legacy assistant_view one. Slack cannot reverse this once the manifest is applied. Mutually exclusive with --no-assistant.
--no-assistant	off	Omit Slack AI Assistant mode entirely (assistant_view, the assistant:write scope, assistant_thread_* events). DMs then render as a flat chat where bare slash commands work inline instead of in Slack's Assistant thread pane. Mutually exclusive with --agent-view.

Run minerva slack manifest --write again after minerva update to pick up any new commands.

minerva send

minerva send --to <target> "message text"
minerva send --to <target> --file <path>
echo "message" | minerva send --to <target>
minerva send --list [platform]

Send a one-shot message to a configured messaging platform without spinning up an agent or gateway loop. Reuses the gateway's already-configured credentials (~/.minerva/.env + ~/.minerva/config.yaml) so ops scripts, cron jobs, CI hooks, and monitoring daemons can post status updates without reimplementing each platform's REST client.

For bot-token platforms (Telegram, Discord, Slack) no running gateway is required — minerva send talks directly to the platform's REST endpoint. Plugin platforms that need a persistent adapter still require a live gateway.

Option	Description
-t, --to <TARGET>	Delivery target. Formats: platform (uses home channel), platform:chat_id, platform:chat_id:thread_id, or platform:#channel-name. Examples: telegram, telegram:-1001234567890, discord:#ops, slack:C0123ABCD.
-f, --file <PATH>	Read the message body from PATH (text files only — logs, reports, markdown). Pass - to force reading from stdin. To send an image or other binary file, use MEDIA:<path> (see below).
-s, --subject <LINE>	Prepend a subject/header line before the message body.
-l, --list [platform]	List configured targets across all platforms (or only the given platform).
-q, --quiet	Suppress stdout on success — useful in scripts (rely on exit code only).
--json	Emit raw JSON result instead of human-readable output.

If neither a positional message argument nor --file is provided, minerva send reads from stdin when it is not a TTY. Exit codes: 0 on success, 1 on delivery/backend failure, 2 on usage errors.

Sending images and other media

--file is for text bodies only. To deliver an image, document, video, or audio file as a native platform attachment, reference it inside the message text with the MEDIA:<local_path> directive:

minerva send --to telegram "MEDIA:/tmp/screenshot.png"
minerva send --to telegram "Build chart for today MEDIA:/tmp/chart.png"   # with caption
minerva send --to discord:#ops "MEDIA:/tmp/report.pdf"

By default, image files are sent as photos (platforms like Telegram recompress these). Add [[as_document]] to the message to deliver them as uncompressed file attachments instead:

minerva send --to telegram "[[as_document]] MEDIA:/tmp/screenshot.png"

Examples:

minerva send --to telegram "deploy finished"
echo "RAM 92%" | minerva send --to telegram:-1001234567890
minerva send --to discord:#ops --file /tmp/report.md
minerva send --to slack:#eng --subject "[CI]" --file build.log
minerva send --list                  # all platforms
minerva send --list telegram         # filter by platform

minerva peer

minerva peer add <name> --url http://host:port --key <API_SERVER_KEY>
minerva peer list
minerva peer dm <peer>[/<agent>] "message"
minerva peer run <peer>[/<agent>] --idempotency-key <key> "message"
minerva peer status <peer>[/<agent>] <run_id>
minerva peer stop <peer>[/<agent>] <run_id>
minerva peer remove <name>

Bot-to-bot DMs across machines. Register another Minerva gateway (any machine running the api_server platform) as a peer, then message its agents: minerva peer dm resolves the remote agent's canonical Bot Chat session over the peer's API server, runs one agent turn there, and prints the reply on stdout — the cross-machine twin of the local minerva -p <bot> chat --in ~ -c "Bot Chat" … bot-messaging command.

<peer> alone targets the peer gateway's main agent; <peer>/<agent> targets a named profile on a multiplexed peer (routed via its /p/<profile>/ mirror).

Subcommand	Description
add <name> --url <URL> [--key <KEY>] [--note TEXT]	Register or update a peer. The URL goes to config.yaml (bot_peers); the key is stored as MINERVA_PEER_<NAME>_KEY in ~/.minerva/.env.
list	List peers and whether each has a key configured.
dm <peer>[/<agent>] [message]	Message the peer agent's canonical Bot Chat and print the reply (--json for machine-readable output; message falls back to stdin).
run <peer>[/<agent>] [message]	Start a long canonical Bot Chat turn asynchronously and return its run_id, session ID, and idempotency key (--json supported). Reuse --idempotency-key when retrying the same request.
status <peer>[/<agent>] <run_id>	Poll an asynchronous peer run and print its final output when complete (--json supported).
stop <peer>[/<agent>] <run_id>	Stop the exact asynchronous peer run without targeting another turn (--json supported).
remove <name>	Remove a peer from the registry (the .env key entry is left in place).

When at least one peer is registered, the Bot Mode messaging protocol (agent.bot_mode_protocol) taught to every canonical Bot Chat automatically includes the peer roster and the minerva peer dm pattern, so agents discover cross-machine teammates without SOUL edits. See Bot Mode.

Exit codes: 0 on success, 1 on delivery/peer failure, 2 on usage errors.

minerva secrets

minerva secrets bitwarden <subcommand>
minerva secrets bw <subcommand>          # short alias
minerva secrets onepassword <subcommand>
minerva secrets op <subcommand>          # short alias (also: 1password)

Pull API keys from an external secret manager at process startup instead of storing them in ~/.minerva/.env. Supports Bitwarden Secrets Manager and 1Password. See the full guides: Bitwarden integration and 1Password integration. A third source, a helper command of your own, is configured in config.yaml only — see Command helper.

bitwarden (alias bw) subcommands:

Subcommand	Description
setup	Interactive wizard: install the pinned bws binary, store an access token, and pick a project. Accepts --project-id, --access-token, and --server-url for non-interactive use.
status	Show current config, binary path/version, and token validation status.
token	Rotate the access token: validates the new token against Bitwarden before storing it in .env (a rejected token changes nothing). Accepts --access-token for non-interactive use and --no-verify to skip the probe.
sync	Fetch secrets now and report what changed. Add --apply to actually export the secrets into the current shell's environment (default is dry-run).
install	Download and verify the pinned bws binary. --force re-downloads even if a managed copy already exists.
disable	Turn off the Bitwarden integration.

onepassword (aliases op, 1password) subcommands:

Subcommand	Description
setup	Verify the op CLI, set the account or service-account token env var, and enable the integration. Accepts --account, --token-env (default OP_SERVICE_ACCOUNT_TOKEN), --token (stored in .env), and --binary-path for non-interactive use.
status	Show current config, the op binary, and the mapped references.
token	Rotate the service-account token: validates it against 1Password before storing it in .env. Accepts --token for non-interactive use and --no-verify to skip the probe.
set <ENV_VAR> <op://reference>	Map an environment variable to an op://vault/item/field reference.
remove <ENV_VAR>	Remove an env-var → reference mapping.
sync	Resolve the references now and report what changed. Add --apply to export the values into the current shell's environment (default is dry-run).
disable	Turn off the 1Password integration.

minerva migrate

minerva migrate <type>

Diagnose and (optionally) rewrite the active config.yaml to replace references to retired models or deprecated settings. A timestamped backup of the original config.yaml is taken before any rewrite (skip with --no-backup).

Subcommand	Description
xai	Scan config.yaml for references to xAI models scheduled for retirement on May 15, 2026 and (with --apply) rewrite them in-place to the official replacements per the xAI migration guide. Defaults to dry-run.

Common flags for migration subcommands:

Flag	Description
--apply	Rewrite config.yaml in-place (default: dry-run, no writes).
--no-backup	Skip the timestamped backup of config.yaml when applying.

minerva proxy

minerva proxy <subcommand>

Run a local OpenAI-compatible HTTP server that forwards requests to an OAuth-authenticated upstream provider (currently xAI Grok OAuth). External apps can point at the proxy with any bearer token; the proxy attaches your real OAuth credentials on the way out. See Subscription Proxy for the full guide.

Subcommand	Description
start	Run the proxy in the foreground. Flags: --provider <xai> (default xai), --host <addr> (default 127.0.0.1; use 0.0.0.0 to expose on LAN), --port <int> (default 8645).
status	Show which proxy upstreams are ready (credentials present, OAuth valid).
providers	List available proxy upstream providers.

minerva security

minerva security <subcommand>

On-demand vulnerability scan against OSV.dev. Covers the Minerva venv (installed PyPI distributions), Python dependencies declared by plugins under ~/.minerva/plugins/, and pinned npx/uvx MCP servers in config.yaml. Does NOT scan globally-installed packages or editor/browser extensions.

Subcommand	Description
audit	Run a one-shot supply-chain audit.

audit flags:

Flag	Default	Description
--json	off	Emit machine-readable JSON instead of human-readable text.
--fail-on <level>	critical	Exit non-zero when any finding meets this severity (low, moderate, high, critical).
--skip-venv	off	Skip scanning the Minerva Python venv.
--skip-plugins	off	Skip scanning plugin requirements files.
--skip-mcp	off	Skip scanning pinned MCP servers in config.yaml.

minerva approvals

minerva approvals suggest [--apply N[,M...]] [--days N] [--min-count N] [--limit N] [--json] [--db PATH]
minerva approvals test [--env-type TYPE] [--json] -- <command>

Subcommand	Description
suggest	Scan the session database for dangerous-classified commands you approved, rank the recurring patterns, and print a numbered command_allowlist proposal. Nothing is written unless --apply names proposals to merge into config.yaml. Destructive classes (recursive delete, sudo, disk writes, credential edits, …) are never proposed. Defaults: last 90 days (--days 0 = all), patterns approved at least twice, 20 proposals. See Mining approval history.
test	Dry-run the real approval guards (hardline blocklist, approvals.deny rules, dangerous-pattern detection, allowlist, yolo/off bypass) against a command and print the verdict, the matching rule, and the normalized-command trace. Never runs the command. Exit codes: 0 allow, 2 would ask for approval, 3 deny. Put -- before the command so its own flags aren't parsed.

minerva login / minerva whoami / minerva account

minerva login [--url URL] [--no-browser] [--force]
minerva whoami
minerva account {login,logout,whoami}

Sign this machine in to your Minerva account (default service: https://tryimagent.com). login shows a one-time code and opens the approval page in your browser; the resulting token is stored in auth.json. whoami prints the signed-in account, and minerva account logout forgets this machine's sign-in.

Option	Description
--url <url>	Account service base URL.
--no-browser	Print the approval URL instead of opening a browser (headless / SSH).
--force	Sign in again even if this machine already has a session.

These commands are about the Minerva account only. To connect a model provider, use minerva auth or minerva model.

minerva logout

minerva logout [--provider openai-codex|xai-oauth]

Remove stored model-provider credentials and reset provider config (defaults to the active provider). This does not sign you out of your Minerva account — that is minerva account logout.

minerva auth

Manage credential pools for same-provider key rotation. See Credential Pools for full documentation.

minerva auth                                              # Interactive wizard
minerva auth list                                         # Show all pools
minerva auth list openrouter                              # Show specific provider
minerva auth add openrouter --api-key sk-or-v1-xxx        # Add API key
minerva auth add anthropic --type oauth                   # Add OAuth credential
minerva auth add openai-codex --type oauth --priority 0   # Add an account and try it first
minerva auth remove openrouter 2                          # Remove by index
minerva auth priority openrouter backup-key 0             # Move a credential to the front of fill_first order
minerva auth reset openrouter                             # Clear cooldowns
minerva auth reset openrouter 2                           # Clear the cooldown on one credential
minerva auth refresh openai-codex work                    # Refresh one OAuth credential and clear its cooldown
minerva auth status anthropic                             # Show auth status for a provider
minerva auth logout anthropic                             # Log out and clear stored auth state

Subcommands: add, list, remove, reset, priority, refresh, status, logout. When called with no subcommand, launches the interactive management wizard.

minerva status

minerva status [--all] [--deep]

Option	Description
--all	Show all details in a shareable redacted format.
--deep	Run deeper checks that may take longer.

minerva cron

minerva cron <list|create|edit|pause|resume|run|remove|status|runs|incidents|notepad|doctor|tick>

Subcommand	Description
list	Show scheduled jobs.
create / add	Create a scheduled job from a prompt, optionally attaching one or more skills via repeated --skill. Supports a per-job reasoning pin via --reasoning-effort <none|minimal|low|medium|high|xhigh|max|ultra>.
edit	Update a job's schedule, prompt, name, delivery, repeat count, or attached skills. Supports --clear-skills, --add-skill, and --remove-skill, plus --reasoning-effort (empty string clears the pin).
pause	Pause a job without deleting it.
resume	Resume a paused job and compute its next future run.
run	Trigger a job on the next scheduler tick.
remove	Delete a scheduled job.
status	Check whether the cron scheduler is running.
runs [job_id] (alias history)	Show durable execution attempts, optionally for one job. --limit sets the row count (1-500).
incidents [list|ack] [incident_id]	List durable cron failure incidents (filter with --state detected|alerted|closed) or acknowledge one.
notepad <job_id> [list|get|set|delete] [key] [value]	Read or write a job's durable notepad — key/value state that persists across its runs.
doctor	Read-only fleet health check: failed runs, failed deliveries, overdue/missing next_run_at, missing scripts or workdirs. Exits non-zero when issues are found.
tick	Run due jobs once and exit.

The cron trigger is pluggable via the cron.provider config key. Empty (the default) uses the built-in in-process ticker. Name a custom provider under plugins/cron_providers/<name>/ or $MINERVA_HOME/plugins/<name>/ to replace it. An unknown or unavailable provider falls back to the built-in, so cron is never left without a trigger. See the cron internals doc.

minerva kanban

minerva kanban [--board <slug>] <action> [options]

Multi-profile, multi-project collaboration board. Each install can host many boards (one per project, repo, or domain); each board is a standalone queue with its own SQLite DB and dispatcher scope. New installs start with one board called default, whose DB is ~/.minerva/kanban.db for back-compat; additional boards live at ~/.minerva/kanban/boards/<slug>/kanban.db. The gateway-embedded dispatcher sweeps every board per tick.

Global flags (apply to every action below):

Flag	Purpose
--board <slug>	Operate on a specific board. Defaults to the current board (set via minerva kanban boards switch, the MINERVA_KANBAN_BOARD env var, or default).

This is the human / scripting surface. Agent workers spawned by the dispatcher drive the board through a dedicated kanban_* toolset (kanban_show, kanban_complete, kanban_request_review, kanban_request_changes, kanban_block, kanban_create, kanban_link, kanban_comment, kanban_heartbeat, kanban_attach, kanban_attach_url, kanban_attachments; orchestrator profiles also get kanban_list and kanban_unblock) instead of shelling to minerva kanban. Workers have MINERVA_KANBAN_BOARD pinned in their env so they physically cannot see other boards.

Action	Purpose
init	Create kanban.db if missing. Idempotent.
boards list / boards ls	List all boards with task counts. --json, --all (include archived).
boards create <slug>	Create a new board. Flags: --name, --description, --icon, --color, --switch (make active). Slug is kebab-case, auto-downcased.
boards switch <slug> / boards use	Persist <slug> as the active board (writes ~/.minerva/kanban/current).
boards show / boards current	Print the currently-active board's name, DB path, and task counts.
boards rename <slug> "<name>"	Change a board's display name. Slug is immutable.
boards rm <slug>	Archive (default) or hard-delete a board. --delete skips the archive step. Archived boards move to boards/_archived/<slug>-<ts>/. Refused for default.
boards set-default-workdir <slug> [path]	Set the default workspace path (absolute) for tasks on a board; omit path to clear it.
boards export / boards import	Export a board to a portable .tar.gz archive, or import such an archive as a new board.
create "<title>"	Create a new task on the active board. Flags: --body, --assignee, --parent (repeatable), --workspace scratch|worktree|dir:<path>, --tenant, --priority, --triage, --idempotency-key, --max-runtime, --max-retries, --skill (repeatable).
swarm "<goal>"	Create a swarm graph: parallel worker cards (--worker PROFILE:TITLE[:SKILL,SKILL], repeatable) feeding a --verifier profile and then a --synthesizer profile. Also --tenant, --priority, --created-by, --idempotency-key, --json.
list / ls	List tasks on the active board. Filter with --mine, --assignee, --status, --tenant, --archived, --json.
show <id>	Show a task with comments and events. --json for machine output.
assign <id> <profile>	Assign or reassign. Use none to unassign. Refused while task is running.
reassign <id> <profile>	Reassign a task (none unassigns). --reclaim releases an active claim first, which a running task requires; --reason is recorded.
reclaim <id>	Release an active worker claim on a running task. --reason is recorded on the event.
set-model <id> [model]	Pin the task's worker to a model (and --provider) from the next dispatch; none clears the override.
link <parent> <child>	Add a dependency. Cycle-detected. Both tasks must be on the same board.
unlink <parent> <child>	Remove a dependency.
claim <id>	Atomically claim a ready task. Prints resolved workspace path.
comment <id> "<text>"	Append a comment. The next worker that claims the task reads it as part of its kanban_show() response.
attach <id> <path>	Attach a local file to a task (--name, --content-type, --author).
attachments <id> / attach-rm <attachment_id>	List a task's attachments (--json), or delete one by id.
complete <id>...	Mark one or more tasks done. Flags: --result, --summary, --metadata.
edit <id> --result "<text>"	Backfill the result of an already-completed task. Also --summary and --metadata (JSON stored on the latest completed run).
block <id> "<reason>"	Mark task blocked for human input. Also appends the reason as a comment.
request-review <id>	Move a task to review with a reviewer handoff — NOT a block. Flags: --summary, --metadata, --reviewer (reassigns before review dispatch).
request-changes <id> <reason>	Reviewer verdict for an active review run: close the review attempt and route the task back to its original implementer.
reopen-review <id>...	Send review task(s) back for changes (review → ready/todo). Flag: --reason (appended as a comment).
schedule <id> "<reason>"	Park time-delay/follow-up work in scheduled so it is not shown as a human blocker.
unblock <id>	Restore a blocked task to its source phase (review or ready), or todo while dependencies remain open.
promote <id> [reason]	Recovery path: move todo/blocked tasks to ready by hand. --ids adds more tasks, --force ignores open parents, --dry-run validates only, --json.
archive <id>	Hide from default list. gc will remove scratch workspaces.
tail <id>	Follow a task's event stream.
watch	Live-stream task events for the board (--assignee, --tenant, --kinds completed,blocked,…, --interval). Ctrl+C exits.
runs <id>	Attempt history for a task, one row per run (profile, outcome, elapsed, summary). --json; filter with --state-type status|outcome --state-name <value>.
log <id>	Print the worker log for a task (--tail N bytes).
heartbeat <id>	Emit a worker liveness heartbeat, with an optional --note.
stats	Per-status and per-assignee counts plus the oldest ready task's age (--json).
assignees	Known profiles with per-profile task counts (--json).
diagnostics / diag	List active diagnostics on the board (--severity warning|error|critical, --task, --json).
notify-subscribe <id> / notify-list [id] / notify-unsubscribe <id>	Manage gateway chat subscriptions to a task's terminal events (--platform, --chat-id, --thread-id; subscribe also takes --delivery-mode notify|notify+wake|wake). The gateway's /kanban subscribe uses these.
dispatch	One dispatcher pass on the active board. Flags: --dry-run, --max N, --failure-limit N, --json.
daemon	Deprecated — the dispatcher runs inside the gateway (minerva gateway start).
context <id>	Print the full context a worker would see (title + body + parent results + comments).
specify <id> / specify --all	Flesh out a triage-column task into a concrete spec (title + body with goal, approach, acceptance criteria) via the auxiliary LLM, then promote it to todo. Flags: --tenant (scope --all to one tenant), --author, --json. Configure the model under auxiliary.triage_specifier in config.yaml.
decompose <id> / decompose --all	Fan a triage-column task out into a graph of child tasks routed to specialist profiles by description. Falls back to specify-style single-task promotion when the LLM decides the task doesn't benefit from fan-out. Same flags as specify. Configure the decomposer model under auxiliary.kanban_decomposer in config.yaml; kanban.orchestrator_profile only controls who owns the root/orchestration task after fan-out. Also runs automatically every dispatcher tick when kanban.auto_decompose: true (the default). See Auto vs Manual orchestration.
gc	Remove scratch workspaces for archived tasks, plus task events and worker logs older than --event-retention-days / --log-retention-days (30 each by default).
repair	Run an integrity check on the board's DB and auto-repair index-only corruption (the damaged file is quarantined first). Any other corruption is reported and left alone; exits non-zero while the DB is still corrupt.

Examples:

# Create a second board and put a task on it without switching away.
minerva kanban boards create atm10-server --name "ATM10 Server" --icon 🎮
minerva kanban --board atm10-server create "Restart server" --assignee ops

# Switch the active board for subsequent calls.
minerva kanban boards switch atm10-server
minerva kanban list                  # shows atm10-server tasks

# Archive a board (recoverable) or hard-delete it.
minerva kanban boards rm atm10-server
minerva kanban boards rm atm10-server --delete

Board resolution order (highest precedence first): --board <slug> flag → MINERVA_KANBAN_BOARD env var → ~/.minerva/kanban/current file → default.

All actions are also available as a slash command in the gateway (/kanban …), with the same argument surface — including boards subcommands and the --board flag.

For the full design — comparison with Cline Kanban / Paperclip / NanoClaw / Gemini Enterprise, eight collaboration patterns, four user stories, concurrency correctness proof — see docs/minerva-kanban-v1-spec.pdf in the repository or the Kanban user guide.

minerva egress

Outbound credential-injection firewall for remote terminal sandboxes. Wraps the iron-proxy daemon — a TLS-intercepting proxy that swaps opaque proxy tokens for real upstream API credentials at the network boundary, so sandboxes never hold real keys. Disabled by default; see the full Egress proxy page for setup + architecture.

minerva egress install                  # download the pinned iron-proxy binary
minerva egress install --force          # re-download even if already installed

minerva egress setup                    # interactive wizard: CA, mappings, config
minerva egress setup --tunnel-port N    # override the tunnel listener port (default 9090)
minerva egress setup --from-bitwarden   # use Bitwarden Secrets Manager as credential source
minerva egress setup --no-bitwarden     # explicitly switch back to env-based credentials
minerva egress setup --rotate-tokens    # mint fresh proxy tokens (default preserves existing)

minerva egress start                    # spawn the managed proxy daemon
minerva egress stop                     # SIGTERM (then SIGKILL after 5s grace)
minerva egress restart                  # stop (if running) then start — needed for secret changes
minerva egress reload                   # hot-reload the ruleset in-place (no restart, no dropped
                                       #   connections) via the loopback management API

minerva egress status                   # binary + config + pid + listening + mappings
minerva egress status --show-tokens     # print proxy tokens in full (default: redacted)

minerva egress disable                  # flip proxy.enabled = false (does not stop a running proxy)
minerva egress config                   # print the path to proxy.yaml for inspection

Common flows

# First-time setup
export OPENROUTER_API_KEY=…
minerva egress setup && minerva egress start
minerva config set terminal.backend docker   # if not already

# Switching credential source after the fact
minerva egress setup --from-bitwarden       # env → bitwarden
minerva egress setup --no-bitwarden         # bitwarden → env
# (just `setup` without either flag preserves the existing mode)

# Rotating all tokens (e.g. after a suspected token leak)
minerva egress setup --rotate-tokens    # setup offers to restart the running daemon for you
# (running sandboxes still hold old tokens; restart them too)

# Adding a new upstream
# Edit ~/.minerva/config.yaml proxy.extra_allowed_hosts: [api.example.com]
minerva egress setup
minerva egress restart                  # one-command apply (stop + start)

Diagnostic shortcuts

minerva egress status                     # current state in one view
cat ~/.minerva/proxy/proxy.yaml           # the rendered iron-proxy config
tail -20 ~/.minerva/proxy/iron-proxy.log  # daemon-level diagnostics
tail -f ~/.minerva/proxy/iron-proxy.log | jq  # daemon + per-request log (line-delimited JSON; v0.39 combines both streams)

Common failure modes + recovery are covered in Egress proxy → Troubleshooting.

minerva project

minerva project <create|list|show|add-folder|remove-folder|rename|set-primary|use|archive|restore|bind-board>

Projects are human-named workspaces that can span multiple folders / repos. They anchor desktop session grouping and, when bound to a kanban board, give tasks a deterministic worktree + branch convention. State is per-profile.

Subcommand	Description
create	Create a new project.
list (alias ls)	List projects.
show	Show a project's details.
add-folder	Add a folder / repo to a project.
remove-folder	Remove a folder from a project.
rename	Rename a project.
set-primary	Set the primary folder.
use	Set the active project.
archive	Archive a project (recoverable).
restore	Restore an archived project.
bind-board	Bind a kanban board to this project.

minerva webhook

minerva webhook <subscribe|list|remove|test>

Manage dynamic webhook subscriptions for event-driven agent activation. Requires the webhook platform to be enabled in config — if not configured, prints setup instructions.

Subcommand	Description
subscribe / add	Create a webhook route. Returns the URL and HMAC secret to configure on your service.
list / ls	Show all agent-created subscriptions.
remove / rm	Delete a dynamic subscription. Static routes from config.yaml are not affected.
test	Send a test POST to verify a subscription is working.

Every subcommand exits non-zero when it refuses or fails (unknown skill name, invalid route name, no such subscription, webhook platform not enabled, unreachable gateway), so scripts and CI can detect it. An empty list is a successful answer, not a failure.

minerva webhook subscribe

minerva webhook subscribe <name> [options]

Option	Description
--prompt	Prompt template with {dot.notation} payload references.
--events	Comma-separated event types to accept (e.g. issues,pull_request). Empty = all.
--description	Human-readable description.
--skills	Comma-separated skill names to load for the agent run.
--deliver	Delivery target: log (default), telegram, discord, slack, github_comment.
--deliver-chat-id	Target chat/channel ID for cross-platform delivery.
--secret	Custom HMAC secret. Auto-generated if omitted.
--deliver-only	Skip the agent — deliver the rendered --prompt as the literal message. Zero LLM cost, sub-second delivery. Requires --deliver to be a real target (not log).
--script	Filter/transform script under ~/.minerva/scripts/. The webhook payload is passed as JSON on stdin; JSON stdout replaces the payload, and empty stdout, [SILENT], or a nonzero exit code ignores the webhook. See Script Filters and Transforms.

Subscriptions persist to ~/.minerva/webhook_subscriptions.json and are hot-reloaded by the webhook adapter without a gateway restart.

minerva doctor

minerva doctor [--fix] [--live] [--ack ADVISORY_ID]

Option	Description
--fix	Attempt automatic repairs where possible.
--live	Opt-in: after the static checks, run one bounded, read-only health probe per configured tool backend (Firecrawl / FAL / browser / MCP / TTS / STT). Makes real network calls.
--ack ADVISORY_ID	Acknowledge a security advisory by ID and exit, so it stops raising a startup banner. Run minerva doctor first to see active advisories and their IDs — this is the only way to clear one.

minerva dump

minerva dump [--show-keys]

Outputs a compact, plain-text summary of your entire Minerva setup. Designed to be copy-pasted into Discord, GitHub issues, or Telegram when asking for support — no ANSI colors, no special formatting, just data.

Option	Description
--show-keys	Show redacted API key prefixes (first and last 4 characters) instead of just set/not set.

What it includes

Section	Details
Header	Minerva version, release date, git commit hash
Environment	OS, Python version, OpenAI SDK version
Identity	Active profile name, MINERVA_HOME path
Model	Configured default model and provider
Terminal	Backend type (local, docker, ssh, etc.)
API keys	Presence check for 25 common provider/tool API keys (OpenRouter, OpenAI, Anthropic, Gemini, Chutes, the web-search backends, FAL, ElevenLabs, GitHub, …)
Features	Enabled toolsets, MCP server count, memory provider
Services	Gateway status, configured messaging platforms
Workload	Cron job counts, installed skill count
Config overrides	Any config values that differ from defaults

Example output

--- minerva dump ---
version:          0.8.0 (2026.4.8) [af4abd2f]
os:               Linux 6.14.0-37-generic x86_64
python:           3.11.14
openai_sdk:       2.24.0
profile:          default
minerva_home:      ~/.minerva
model:            anthropic/claude-opus-4.6
provider:         openrouter
terminal:         local

api_keys:
  openrouter           set
  openai               not set
  anthropic            set
  firecrawl            set
  ...

features:
  toolsets:           all
  mcp_servers:        0
  memory_provider:    built-in
  gateway:            running (systemd)
  platforms:          telegram, discord
  cron_jobs:          3 active / 5 total
  skills:             42

config_overrides:
  agent.max_turns: 250
  compression.threshold: 0.85
  display.streaming: False
--- end dump ---

When to use

• Reporting a bug on GitHub — paste the dump into your issue
• Asking for help in Discord — share it in a code block
• Comparing your setup to someone else's
• Quick sanity check when something isn't working

tip

minerva dump is specifically designed for sharing. For interactive diagnostics, use minerva doctor. For a visual overview, use minerva status.

minerva debug

minerva debug share [options]
minerva debug delete <url>...

Upload a debug report (system info + recent logs) to a paste service and get a shareable URL. Useful for quick support requests — includes everything a helper needs to diagnose your issue.

Option	Description
--lines <N>	Number of log lines to include per log file (default: 200).
--expire <days>	Paste expiry in days (default: 7).
--local	Print the report locally instead of uploading.
--no-redact	Disable upload-time secret redaction. By default, uploads are redacted.

The report includes system info (OS, Python version, Minerva version), recent agent, gateway, GUI/backend, and desktop logs (512 KB limit per file), and redacted API key status. By default, uploads are redacted so secrets are not included.

Uploads use public paste services tried in order: paste.rs, dpaste.com. minerva debug delete <url>... deletes pastes that debug share uploaded.

Examples

minerva debug share              # Upload debug report, print URL
minerva debug share --lines 500  # Include more log lines
minerva debug share --expire 30  # Keep paste for 30 days
minerva debug share --local      # Print report to terminal (no upload)
minerva debug delete https://paste.rs/abc123   # Remove an uploaded report

minerva backup

minerva backup [options]

Create a zip archive of your Minerva configuration, skills, sessions, and data. The backup excludes the minerva-agent codebase itself, and it does not nest earlier backup artifacts (backups/, state-snapshots/) — each of those already contains its own copy of state.db.

Option	Description
-o, --output <path>	Output path for the zip file (default: ~/minerva-backup-<timestamp>.zip).
-q, --quick	Quick snapshot: only critical state files (config.yaml, state.db, .env, auth, cron jobs). Much faster than a full backup.
-l, --label <name>	Label for the snapshot (only used with --quick).

The backup uses SQLite's backup() API for safe copying, so it works correctly even when Minerva is running (WAL-mode safe).

What's excluded from the zip:

• *.db-wal, *.db-shm, *.db-journal — SQLite's WAL / shared-memory / journal sidecars. The *.db file already got a consistent snapshot via sqlite3.backup(); shipping the live sidecars alongside it would let a restore see a half-committed state.
• checkpoints/ — per-session trajectory caches. Hash-keyed and regenerated per session; wouldn't port cleanly to another install anyway.
• The minerva-agent code itself (this is a user-data backup, not a repo snapshot).

Examples

minerva backup                           # Full backup to ~/minerva-backup-*.zip
minerva backup -o /tmp/minerva.zip        # Full backup to specific path
minerva backup --quick                   # Quick state-only snapshot
minerva backup --quick --label "pre-upgrade"  # Quick snapshot with label

minerva checkpoints

minerva checkpoints [COMMAND]

Inspect and manage the shadow git store at ~/.minerva/checkpoints/ — the storage layer behind the in-session /rollback command. Safe to run any time; does not require the agent to be running.

Subcommand	Description
status (default)	Show total size, project count, and per-project breakdown. Bare minerva checkpoints is equivalent.
list	Alias for status.
prune	Force a cleanup sweep — delete orphan and stale projects, GC the store, enforce the size cap. Ignores the 24h idempotency marker.
clear	Delete the entire checkpoint base. Irreversible; asks for confirmation unless -f.
clear-legacy	Delete only the legacy-<timestamp>/ archives produced by the v1→v2 migration.

Options

Option	Subcommand	Description
--limit N	status, list	Max projects to list (default 20).
--retention-days N	prune	Drop projects whose last_touch is older than N days (default 7).
--max-size-mb N	prune	After the orphan/stale pass, drop the oldest commit per project until total store size ≤ N MB (default 500).
--keep-orphans	prune	Skip deleting projects whose working directory no longer exists.
-f, --force	clear, clear-legacy	Skip the confirmation prompt.

Examples

minerva checkpoints                                  # status overview
minerva checkpoints prune --retention-days 3         # aggressive cleanup
minerva checkpoints prune --max-size-mb 200          # tighten size cap once
minerva checkpoints clear-legacy -f                  # drop v1 archive dirs
minerva checkpoints clear -f                         # wipe everything

See Checkpoints and /rollback for the full architecture and the in-session commands.

minerva import

minerva import <zipfile> [options]

Restore a previously created Minerva backup into your Minerva home directory. All files in the archive overwrite existing files in your Minerva home; --force only skips the confirmation prompt that fires when the target already has a Minerva installation.

Option	Description
-f, --force	Skip the existing-installation confirmation prompt.

warning

Stop the gateway before importing to avoid conflicts with running processes.

SQLite databases

.db members (state.db, kanban.db, response_store.db, …) are not published with a rename like ordinary files. Renaming would replace the file's inode while a gateway or backend (minerva serve) process still holds the old one open: that process would keep reading pre-import pages and keep writing sessions nobody else can see, and those sessions would simply be absent from the database everyone opens next — with nothing logged. Instead the imported pages are written into the existing database file, the same way /snapshot restore does it, so every open connection converges on the imported data.

If the live database cannot be replaced safely — the page copy failed and another process still holds the file open — the import leaves that database untouched and lists it under Warnings (N files skipped). Stop the holding processes and re-run.

Importing an older backup over newer work is still allowed, but it is no longer silent. When the imported state.db holds fewer messages than the one it replaced, the summary reports it:

  ⚠ Session data replaced by older backup contents:
    state.db: 12 session(s) / 8912 message(s) -> 3 / 24
    Anything recorded after the backup was taken is not in it.
    Recover from a newer backup or snapshot: /snapshot list inside `minerva`

Examples

minerva import ~/minerva-backup-20260423.zip           # Prompts before overwriting existing config
minerva import ~/minerva-backup-20260423.zip --force   # Overwrite without prompting

minerva logs

minerva logs [log_name] [options]

View, tail, and filter Minerva log files. All logs are stored in ~/.minerva/logs/ (or <profile>/logs/ for non-default profiles).

Log files

Name	File	What it captures
agent (default)	agent.log	All agent activity — API calls, tool dispatch, session lifecycle (INFO and above)
errors	errors.log	Warnings and errors only — a filtered subset of agent.log
gateway	gateway.log	Messaging gateway activity — platform connections, message dispatch, webhook events
gui	gui.log	Backend server (minerva serve) / TUI-gateway / PTY-bridge / websocket events
desktop	desktop.log	Electron desktop app — boot, backend spawn output, and recent Python tracebacks
mcp	mcp-stderr.log	Every stdio MCP subprocess's stderr, redirected here by tools/mcp_tool.py

Options

Option	Description
log_name	Which log to view: agent (default), errors, gateway, gui, desktop, mcp, or list to show available files with sizes.
-n, --lines <N>	Number of lines to show (default: 50).
-f, --follow	Follow the log in real time, like tail -f. Press Ctrl+C to stop.
--level <LEVEL>	Minimum log level to show: DEBUG, INFO, WARNING, ERROR, CRITICAL.
--session <ID>	Filter lines containing a session ID substring.
--since <TIME>	Show lines from a relative time ago: 30m, 1h, 2d, etc. Supports s (seconds), m (minutes), h (hours), d (days).
--component <NAME>	Filter by component: gateway, agent, tools, cli, cron, gui.

Examples

# View the last 50 lines of agent.log (default)
minerva logs

# Follow agent.log in real time
minerva logs -f

# View the last 100 lines of gateway.log
minerva logs gateway -n 100

# Show only warnings and errors from the last hour
minerva logs --level WARNING --since 1h

# Filter by a specific session
minerva logs --session abc123

# Follow errors.log, starting from 30 minutes ago
minerva logs errors --since 30m -f

# List all log files with their sizes
minerva logs list

Filtering

Filters can be combined. When multiple filters are active, a log line must pass all of them to be shown:

# WARNING+ lines from the last 2 hours containing session "tg-12345"
minerva logs --level WARNING --since 2h --session tg-12345

Lines without a parseable timestamp are included when --since is active (they may be continuation lines from a multi-line log entry). Lines without a detectable level are included when --level is active.

Log rotation

Minerva uses Python's RotatingFileHandler. Old logs are rotated automatically — look for agent.log.1, agent.log.2, etc. The minerva logs list subcommand shows all log files including rotated ones.

minerva prompt-size

minerva prompt-size [--platform <name>] [--json]

Reports the fixed prompt budget for a fresh session — what gets sent on every API call before any conversation content. Useful when a downstream adapter or proxy has a tighter prompt budget than the model's context window, or when you want to see which block (skills index, memory, profile) dominates.

It builds the same system prompt the agent would, then breaks it down:

• System prompt total — full assembled prompt (identity, guidance, skills index, context files, memory, profile, timestamp).
• Skills index — the <available_skills> block. This is often the largest single block when many skills are installed.
• Memory and user profile — your MEMORY.md / USER.md snapshots.
• Prompt tiers — stable / context / volatile, matching how Minerva layers the prompt for cache-friendliness.
• Tool schemas — the JSON for all enabled tools (the other half of the fixed per-call payload).

Runs entirely offline — no API call, works with no credentials configured.

# Human-readable breakdown for the CLI platform (default)
minerva prompt-size

# Simulate a messaging platform's prompt (different platform hint)
minerva prompt-size --platform telegram

# Machine-readable output for scripts
minerva prompt-size --json

tip

The skills index and tool schemas scale with how many skills and tools you have enabled. To shrink the prompt, disable unused toolsets (minerva tools) or uninstall skills you don't need (minerva skills). Context files (AGENTS.md, .cursorrules) in your current directory also count toward the total.

minerva config

minerva config <subcommand>

Subcommands:

Subcommand	Description
show	Show current config values.
edit	Open config.yaml in your editor.
get <key> [--json]	Print a single config value by dotted key (e.g. minerva config get model.default). --json emits machine-readable output.
set <key> <value> [--force]	Set a config value. --force suppresses the unknown-key notice printed after writing a key this version doesn't recognise — the value is saved either way.
unset <key>	Remove a config key, reverting it to the built-in default.
path	Print the config file path.
env-path	Print the .env file path.
check	Check for missing or stale config.
migrate	Add newly introduced options interactively.

Dots inside key names

minerva config set/get/unset use . as the nesting separator, but many real key names contain literal dots — model IDs (grok-4.6, glm-5.3-flash), hostnames (api.example.com), versioned provider names. Two rules make these addressable:

• Existing keys just work. When navigating an existing mapping, an existing literal key that matches the dotted remainder is preferred over splitting. minerva config set providers.p.models.grok-4.6.supports_vision true updates the real grok-4.6 entry (and get/unset resolve the same way).
• Creating a new dotted key requires escaping. Escape literal dots with a backslash: minerva config set 'providers.p.models.grok-4\.7.context_length' 128000 creates the literal grok-4.7 key. (Quote the key so your shell keeps the backslash.)

If an unescaped write would create a nested mapping that shadows an existing dotted sibling (e.g. creating grok-4 next to an existing grok-4.6), the command fails with an error instead of silently writing a phantom entry the runtime would never read.

minerva pairing

minerva pairing <list|approve|revoke|clear-pending>

Subcommand	Description
list	Show pending and approved users.
approve <platform> <code>	Approve a pairing code.
revoke <platform> <user-id>	Revoke a user's access.
clear-pending	Clear pending pairing codes.

minerva skills

minerva skills <subcommand>

Subcommands:

Subcommand	Description
trust [path] / untrust [path]	Trust a project so its repo-local skills (./.minerva/skills, ./.agents/skills) load, or revoke that trust. Defaults to the git checkout that contains the current directory.
browse	Paginated browser for skill registries.
search	Search skill registries.
install	Install a skill.
inspect	Preview a skill without installing it.
list	List installed skills.
check	Check installed hub skills for upstream updates.
update	Reinstall hub skills with upstream changes when available.
audit	Re-scan installed hub skills.
uninstall	Remove a hub-installed skill.
reset	Un-stick a bundled skill flagged as user_modified by clearing its manifest entry. With --restore, also replaces the user copy with the bundled version.
list-modified [--json]	List the bundled skills you have edited — the ones minerva update reports as user-modified and skips.
diff <name>	Show a unified diff between your copy of a bundled skill and the stock version, before you decide on reset.
opt-out	Stop bundled skills from being seeded into the active profile. Writes a .no-bundled-skills marker so the installer, minerva update, and any sync skip bundled-skill seeding. Safe by default — nothing on disk is touched. With --remove, also deletes already-present bundled skills that are unmodified (user-edited, hub-installed, and hand-written skills are never removed; previews and confirms first, --yes to skip).
opt-in	Undo opt-out by removing the .no-bundled-skills marker so bundled skills are seeded again on the next minerva update. With --sync, re-seed immediately.
publish	Publish a skill to a registry.
snapshot export <file> / snapshot import <file> [--force]	Export installed skills to a JSON file (- for stdout), or install from one. --force installs despite a caution verdict.
tap list / tap add <owner/repo> / tap remove <name>	Manage custom GitHub skill sources.
config	Interactive enable/disable configuration for skills by platform.

Common examples:

minerva skills browse
minerva skills search react --source skills-sh
minerva skills search https://mintlify.com/docs --source well-known
minerva skills inspect skills-sh/vercel-labs/json-render/json-render-react
minerva skills install skills-sh/anthropics/skills/pdf --force
minerva skills install https://sharethis.chat/SKILL.md                     # Direct URL (+ referenced support files)
minerva skills install https://example.com/SKILL.md --name my-skill        # Override name when frontmatter has none
minerva skills check
minerva skills update
minerva skills config
minerva skills reset google-workspace
minerva skills reset google-workspace --restore --yes
minerva skills opt-out                  # stop future bundled-skill seeding (nothing deleted)
minerva skills opt-out --remove --yes   # also delete UNMODIFIED bundled skills
minerva skills opt-in --sync            # undo: remove marker and re-seed now

Notes:

• --force can override non-dangerous policy blocks for third-party/community skills.
• --force does not override a dangerous scan verdict.
• --source skills-sh searches the public skills.sh directory.
• --source well-known lets you point Minerva at a site exposing /.well-known/skills/index.json.
• --source browse-sh searches browse.sh's catalog of 200+ site-specific browser-automation skills. Identifiers look like browse-sh/airbnb.com/search-listings-ddgioa.
• Passing an http(s)://…/*.md URL installs SKILL.md plus explicitly referenced files under references/, templates/, scripts/, assets/, and examples/. When frontmatter has no name: and the URL slug isn't a valid identifier, an interactive terminal prompts for a name; non-interactive surfaces (/skills install inside the TUI, gateway platforms) require --name <x> instead.

minerva bundles

minerva bundles <subcommand>

Skill bundles group several skills under one /<bundle-name> slash command. Invoking the bundle loads every referenced skill into a single combined user message. Storage: ~/.minerva/skill-bundles/<slug>.yaml. See Skill Bundles for the YAML schema and behavior.

Subcommands:

Subcommand	Description
list	List installed bundles (default when no subcommand given)
show <name>	Show one bundle's name, description, skills, and file path
create <name>	Create a new bundle. Pass --skill <id> (repeat) or omit for interactive entry. --description, --instruction, --force available.
delete <name>	Remove a bundle file
reload	Re-scan ~/.minerva/skill-bundles/ and report added/removed bundles

Examples:

minerva bundles create backend-dev \
  --skill github \
  --skill test-driven-development \
  --skill requesting-code-review \
  -d "Backend feature work"

minerva bundles list
minerva bundles show backend-dev
minerva bundles delete backend-dev

In a chat session, /bundles lists installed bundles and /<bundle-name> loads one.

minerva curator

minerva curator <subcommand>

The curator is an auxiliary-model background task that periodically reviews agent-created skills, prunes stale ones, consolidates overlaps, and archives obsolete skills. Bundled and hub-installed skills are never touched. Archives are recoverable; auto-deletion never happens.

Subcommand	Description
status	Show curator status and skill stats
usage	Show usage telemetry for all skills (bundled, hub, agent-created) with provenance. --sort activity|recent|name, --provenance agent|bundled|hub, --json
run	Trigger a curator review now (blocks until the LLM pass finishes)
run --background	Start the LLM pass in a background thread and return immediately
run --dry-run	Preview only — produce the review report with no mutations
backup	Take a manual tar.gz snapshot of ~/.minerva/skills/ (curator also snapshots automatically before every real run)
rollback	Restore ~/.minerva/skills/ from a snapshot (defaults to newest)
rollback --list	List available snapshots
rollback --id <ts>	Restore a specific snapshot by id
rollback -y	Skip the confirmation prompt
rollback <entry_id>	Undo a single skill mutation by its ledger entry id instead of restoring a whole snapshot
ledger	List the per-mutation skill audit ledger (curator, agent, and user changes). --skill <name> filters, --limit sets the count (default 20)
pause	Pause the curator until resumed
resume	Resume a paused curator
pin <skill>	Pin a skill so the curator never auto-transitions it
unpin <skill>	Unpin a skill
list-unmanaged	List curation-eligible skills that have no provenance marker
adopt <skill>...	Hand unmanaged skills to the curator. --all-unmanaged adopts every one (--dry-run previews, --yes skips the prompt)
restore <skill>	Restore an archived skill
archive <skill>	Archive a skill manually
prune	Bulk-archive curator-managed skills idle for at least --days days (default 90). --dry-run previews
list-archived	List archived skills (recoverable via restore)
purge	Permanently delete archived skills older than curator.archive_ttl_days (--days overrides). Only ever runs when you call it, and is recorded in the ledger

On a fresh install the first scheduled pass is deferred by one full interval_hours (7 days by default) — the gateway will not curate immediately on the first tick after minerva update. Use minerva curator run --dry-run to preview before that happens.

See Curator for behavior and config.

minerva moa

Configure named Mixture of Agents presets. Presets appear as selectable models under a Mixture of Agents provider in every model picker; /moa <prompt> runs one prompt through the default preset.

minerva moa list
minerva moa configure [name]
minerva moa delete <name>

minerva moa configure reuses Minerva's provider → model picker for each reference model and the aggregator. A preset is an execution-mode configuration, not a primary model or provider.

minerva fallback

minerva fallback <subcommand>

Manage the fallback provider chain. Fallback providers are tried in order when the primary model fails with rate-limit, overload, or connection errors.

Subcommand	Description
list (alias: ls)	Show the current fallback chain (default when no subcommand)
add	Pick a provider + model (same picker as minerva model) and append to the chain
remove (alias: rm)	Pick an entry to delete from the chain
clear	Remove all fallback entries

See Fallback Providers.

minerva hooks

minerva hooks <subcommand>

Inspect shell-script hooks declared in ~/.minerva/config.yaml, test them against synthetic payloads, and manage the first-use consent allowlist at ~/.minerva/shell-hooks-allowlist.json.

Subcommand	Description
list (alias: ls)	List configured hooks with matcher, timeout, and consent status
test <event>	Fire every hook matching <event> against a synthetic payload
revoke (aliases: remove, rm)	Remove a command's allowlist entries (takes effect on next restart)
doctor	Check each configured hook: exec bit, allowlist, mtime drift, JSON validity, and synthetic run timing

See Hooks for event signatures and payload shapes.

minerva memory

minerva memory <subcommand>

Set up and manage external memory provider plugins. Available providers: honcho, openviking, mem0, hindsight, holographic, retaindb, byterover, supermemory. Only one external provider can be active at a time. Built-in memory (MEMORY.md/USER.md) is always active.

Subcommands:

Subcommand	Description
setup	Interactive provider selection and configuration.
status	Show current memory provider config.
off	Disable external provider (built-in only).
reset [--target all|memory|user] [--yes]	Erase built-in memory. --target picks the store: all (default), memory (MEMORY.md), or user (USER.md). --yes skips the confirmation.

Provider-specific subcommands

When an external memory provider is active, it may register its own top-level minerva <provider> command for provider-specific management (e.g. minerva honcho when Honcho is active). Inactive providers do not expose their subcommands. Run minerva --help to see what's currently wired in.

minerva acp

minerva acp

Starts Minerva as an ACP (Agent Client Protocol) stdio server for editor integration.

Related entrypoints:

minerva-acp
python -m acp_adapter

Install support first:

cd ~/.minerva/minerva-agent && uv pip install -e '.[acp]'

See ACP Editor Integration and ACP Internals.

minerva mcp

minerva mcp <subcommand>

Manage MCP (Model Context Protocol) server configurations and run Minerva as an MCP server.

Subcommand	Description
(none) or picker	Interactive catalog picker — browse Minerva-approved MCPs and install/enable/disable.
catalog	List Minerva-approved MCPs (plain text, scriptable).
install <name>	Install a catalog entry (e.g. minerva mcp install globalping).
serve [-v|--verbose]	Run Minerva as an MCP server — expose conversations to other agents.
add <name> [--url URL] [--command CMD] [--auth oauth|header] [--env KEY=VALUE ...] [--connect-timeout SECONDS] [--args ...]	Add a custom MCP server with automatic tool discovery. --env sets environment variables for stdio servers; --connect-timeout bounds the initial connection and tool discovery. --args passes the remaining argv to the stdio command, so put it last.
remove <name> (alias: rm)	Remove an MCP server from config.
list (alias: ls)	List configured MCP servers.
test <name>	Test connection to an MCP server.
configure <name> (alias: config)	Toggle tool selection for a server.
login <name> [--flow browser|device]	Force re-authentication for an OAuth-based MCP server. --flow overrides oauth.flow: browser PKCE or device (RFC 8628 device code, for headless hosts).
reauth <name> / reauth --all	Re-authenticate one OAuth MCP server, or every OAuth server in config one at a time.

See MCP Config Reference, Use MCP with Minerva, and MCP Server Mode.

minerva plugins

minerva plugins [subcommand]

Unified plugin management — general plugins, memory providers, and context engines in one place. Running minerva plugins with no subcommand opens a composite interactive screen with two sections:

• General Plugins — multi-select checkboxes to enable/disable installed plugins
• Provider Plugins — single-select configuration for Memory Provider and Context Engine. Press ENTER on a category to open a radio picker.

Subcommand	Description
(none)	Composite interactive UI — general plugin toggles + provider plugin configuration.
install <identifier> [--force] [--ref COMMIT_SHA]	Install a plugin from a Git URL (https://, git@, or file:// for a local Git repository) or owner/repo[/subdir] shorthand. Plugins are not looked up by name: a bare name exits with an error. --ref accepts only a full 40-character commit SHA and installs that exact immutable revision.
update <name>	Pull latest changes for an unpinned installed plugin. Pinned plugins must be reinstalled with --force --ref <new-commit> to move.
remove <name> (aliases: rm, uninstall)	Remove an installed plugin.
enable <name>	Enable a disabled plugin.
disable <name>	Disable a plugin without removing it.
list (alias: ls)	List installed plugins with enabled/disabled status.
show <name> (alias: info)	Show details for one plugin, including the events it emits and listens to.
capabilities [name]	Show each plugin's declared capabilities (from plugin.yaml) against what you have granted. Capabilities are a consent and audit layer, not a sandbox.
doctor [path-or-id] [--ci]	Validate a native plugin through the real manifest parser, loader, and registration path. --ci exits 1 on errors.
pack install <path-or-url> [--force]	Install a plugin pack (minerva-pack.yaml) — a declarative set of plugins, each a repo pinned to an exact 40-character commit SHA. Shows a mandatory review screen (every plugin, its source and pinned ref), asks one confirmation for the pack contents, then runs ordinary pinned installs. Each plugin's declared capabilities still go through the standard per-plugin consent — a pack never bulk-grants. Partial failures are reported per plugin; exits non-zero when any plugin failed. Interactive only (no --yes).
pack export [--enabled-only] [--name NAME]	Emit a pack YAML on stdout from the current install: repo + exact SHA of each git-installed plugin plus sanitized non-secret plugins.entries config. Local-only plugins (no git provenance) are listed as warning comments, never as installable entries. Secrets, capability grants, and allow_* gates are always stripped.
pack show <path-or-url>	Dry-run: parse, validate, and display a pack without installing anything.

Provider plugin selections are saved to config.yaml:

• memory.provider — active memory provider (empty = built-in only)
• context.engine — active context engine ("compressor" = built-in default)

General plugin disabled list is stored in config.yaml under plugins.disabled. Git installs also record only their canonical source, exact installed revision, and pin status in the profile-local plugins/.install-metadata.json sidecar. It does not contain plugin config, environment values, secrets, or capability grants.

See Plugins and Build a Minerva Plugin.

minerva tools

minerva tools [--summary]
minerva tools <list|enable|disable|post-setup> [...]

Option / subcommand	Description
--summary	Print the current enabled-tools summary and exit.
list [--platform P]	Show every tool and whether it is enabled on a platform (default cli).
enable <name>... [--platform P] / disable <name>... [--platform P]	Enable or disable toolsets (plain names such as web) or single MCP tools (server:tool) on a platform (default cli).
post-setup <key>	Run the install hook a tool backend declares — the same step the interactive UI runs after you pick a backend that needs extra dependencies. Keys: agent_browser, browser_use_cli, browserbase, camofox, cua_driver, ddgs, faster_whisper, kittentts, langfuse, lightpanda, piper, xai_grok. A key is only accepted when a currently visible provider declares it (valid_post_setup_keys()), so the set offered on your install may be narrower.

With no subcommand and no --summary, this launches the interactive per-platform tool configuration UI.

minerva computer-use

minerva computer-use <subcommand>

Subcommands:

Subcommand	Description
install	Run the upstream cua-driver installer (macOS, Windows, and Linux).
install --upgrade	Re-run the installer even if cua-driver is already on PATH. The upstream script always pulls the latest release, so this performs an in-place upgrade.
status	Print whether cua-driver is on $PATH and which version is installed.
doctor [--include CHECK] [--skip CHECK] [--json]	Run cua-driver's health report and show its platform checks.
permissions status [--json]	Report macOS Accessibility and Screen Recording grants.
permissions grant	Ask macOS to grant Accessibility and Screen Recording to Cua Driver.

minerva computer-use install is the stable entry point for installing the cua-driver binary used by the computer_use toolset. It runs the same upstream installer that minerva tools invokes when you first enable Computer Use, so it's safe to use for re-running the install if the toolset toggle didn't trigger it (for example, on returning-user setups).

If cua-driver is already present, Minerva checks its version and runtime manifest. A compatible 0.20.0 or newer installation is left in place. An old or incomplete standard installation is repaired with the current upstream installer. Minerva never replaces a custom binary selected through MINERVA_CUA_DRIVER_CMD; update that binary directly or remove the override. minerva computer-use status reports when repair is required.

The built-in computer_use toolset is the recommended Minerva integration. Registering raw Cua MCP tools is an alternative when you need Cua's low-level tool vocabulary. cua-driver skills install detects Minerva and links Cua's skill pack into the Minerva skills directory automatically.

Permission mode and capability-manifest approval belong to runtime launch. In bounded mode Minerva passes Cua's canonical --capability-manifest and --approve-capability-manifest flags. Every MCP transport owns a private lifecycle session inside its runtime. Public session names label cursor and session state; they do not own or share the runtime.

minerva update automatically re-runs the upstream installer at the end of the update if cua-driver is on PATH, so most users will not need to call --upgrade manually. Use it when upstream ships a fix you want right now without waiting for the next Minerva update.

minerva pets

minerva pets <list|install|select|show|off|scale|remove|doctor>

Petdex is a public gallery of animated sprite pets for coding agents. Install one and Minerva shows it reacting to agent activity across the CLI, TUI, and desktop app.

Subcommand	Description
list	Browse the petdex gallery.
install	Install a pet from the gallery.
select	Set the active pet (writes display.pet.*).
show	Animate the active pet in the terminal.
off	Disable the pet display.
scale	Resize the pet everywhere (display.pet.scale).
remove	Delete an installed pet.
doctor	Check pet setup + terminal graphics support.

You can also generate a brand-new pet from a text description with the /hatch slash command. See Pets.

minerva sessions

minerva sessions <subcommand>

Subcommands:

Subcommand	Description
list	List recent sessions.
browse	Interactive session picker with search and resume. Each row shows a lifecycle status tag (done / intr / err / empty, derived from the session's final message) and its message count. Press d on a highlighted row (while the search filter is empty) to delete that session after a y/N confirmation; while a filter is active, d types into the search instead.
export <output> [--session-id ID]	Export sessions to JSONL (default), or with --format md|qmd|html|trace. Accepts the same filters as prune.
delete <session-id>	Delete one session.
prune	Delete sessions matching filters: time bounds --older-than/--newer-than/--before/--after (durations like 5h/2d, bare days, or ISO timestamps); attributes --source, --title, --model, --provider, --branch, --end-reason, --user, --chat-id, --chat-type, --cwd; numeric bounds --min/--max-messages, --min/--max-tokens, --min/--max-cost, --min/--max-tool-calls; plus --include-archived, --dry-run, --yes. Default: older than 90 days.
archive	Bulk-archive (soft-hide, no deletion) sessions matching the same filters as prune. Requires at least one filter.
stats	Show session-store statistics.
rename <session-id> <title>	Set or change a session title.
pin <session-id>... / unpin <session-id>...	Set or clear the durable keep flag. Pinned sessions are exempt from the sessions.auto_archive sweep, always appear in listings, and show in the desktop sidebar's Pinned section.
pinned [--json]	List pinned sessions.
import [path] [--from claude|codex]	Import a Claude Code or Codex CLI conversation so it can be resumed with minerva --resume <id>. The source files are only read.
clean-markers [--dry-run]	Optional one-time rewrite of stale bracketed tool-call markers (e.g. [memory]) that older local tool-call templates stored as assistant text. Sessions are already repaired in memory on load; this just stops re-repairing on every resume. Backs up state.db first unless --no-backup.
optimize	Reclaim disk space: merge FTS5 index segments + VACUUM. Non-destructive — no session data changes.
optimize-storage	Migrate the full-text search index to the compact v23 external-content layout; on large databases this reclaims a large fraction of state.db.
repair	Repair a malformed state.db schema (e.g. table messages_fts already exists) so hidden sessions reappear; a backup is made first.
repair-routing	Re-attach gateway conversations stranded in session rows that lost their routing identity (a chat "jumping back in time" after a restart). Dry-run by default; --apply performs the adoptions (stop the gateway first); --max-gap-seconds N tunes the contiguity window. Only unambiguous cases are repaired. See Sessions → Repair Stranded Gateway Sessions.
recover	Offline, non-destructive recovery of a damaged state.db into a separate clean database.
retitle-skills	Regenerate titles for sessions opened with a /skill, using what the user actually typed; lists changes unless --apply is passed.

minerva insights

minerva insights [--days N] [--source platform]

Option	Description
--days <n>	Analyze the last n days (default: 30).
--source <platform>	Filter by source such as cli, telegram, or discord.

minerva import-agent

minerva import-agent [claude-code|codex] [options]

Import a Claude Code (~/.claude) or OpenAI Codex CLI (~/.codex) setup into Minerva. Maps CLAUDE.md/AGENTS.md instructions to memory entries, Bash(...) permission allow/deny rules to command_allowlist/approvals.deny, MCP servers to mcp_servers in config.yaml, and skill directories into ~/.minerva/skills/. Always previews before applying; API keys and credentials are never imported.

Option	Description
agent	claude-code or codex (default: auto-detect).
--source <path>	Custom source directory (default: ~/.claude or ~/.codex).
--dry-run	Preview only — write nothing.
--overwrite	Replace conflicting MCP servers / skills (default: skip).
--yes, -y	Skip confirmation prompts.

See the import guide for the full mapping tables.

minerva serve

minerva serve [options]

Start the Minerva backend server — the HTTP API and JSON-RPC/WebSocket gateway the desktop app connects to. It is headless: it has no browser UI. The desktop app launches its own minerva serve backend; use this command directly when you want a backend on a remote host for Minerva Desktop to connect to. A non-loopback bind engages the auth gate, which requires an auth provider. Requires the [web] extra (FastAPI + Uvicorn).

Option	Default	Description
--port	9119	Port to run the server on (0 lets the OS assign a free port)
--host	127.0.0.1	Bind address. Any non-loopback address engages the auth gate.
--isolated	off	When launched from a named profile (worker serve), run a dedicated server scoped to that profile instead of routing to the machine-level server.
--stop	—	Stop running Minerva backend server processes and exit.
--status	—	List running Minerva backend server processes and exit.
--insecure	off	Deprecated no-op. It formerly bypassed auth on a non-loopback bind; since the June 2026 hardening a public bind always requires an auth provider. Accepted so old launch scripts don't die on an unknown flag.
--no-open	off	Legacy no-op — serve never opens a browser. Accepted for old callers.
--skip-build	off	Legacy no-op — the browser UI build it used to skip is gone. Accepted so old launch scripts (Windows Scheduled Tasks, CI) keep working.
--open-profile NAME	—	Internal: set by the unified-launch re-exec to preselect the launching profile.

Port conflicts: if the requested port (default 9119) is already held by another process (e.g. a second minerva serve or the gateway), the command prints a machine-readable sentinel line BACKEND_PORT_IN_USE port=<port> to stdout, a human hint naming the likely holder, and exits with code 75 (EX_TEMPFAIL) instead of a generic error — so scripts and the desktop app can tell "port occupied" apart from "backend broken". Pass --port 0 to bind a free ephemeral port (the successful boot announces the chosen port via MINERVA_BACKEND_READY port=<port>).

minerva dashboard

The browser dashboard has been removed — Minerva Desktop is the graphical interface, and minerva serve runs the backend it connects to. A bare minerva dashboard prints a notice pointing to both and exits 1.

Two flags are not stubs and still manage the backend server process, for the benefit of older shells and scripts:

Flag	Behaviour
--stop	Stop a running backend server (same handler as minerva serve --stop).
--status	Report whether a backend server is running.

minerva profile

minerva profile <subcommand>

Manage profiles — multiple isolated Minerva instances, each with its own config, sessions, skills, and home directory.

Subcommand	Description
list	List all profiles.
use <name>	Set a sticky default profile.
create <name> [--clone] [--clone-all] [--clone-from <source>] [--no-alias]	Create a new profile. --clone copies config, .env, SOUL.md, and skills from the active profile. --clone-all copies all state. --clone-from specifies a source profile and implies config clone unless paired with --clone-all.
delete <name> [-y]	Delete a profile.
describe [name] [--text TEXT | --auto] [--overwrite] [--all]	Read or set a profile's description, which the kanban orchestrator uses to route tasks. --auto writes one with the auxiliary LLM (auxiliary.profile_describer); --all --auto fills in every profile that has none.
show <name>	Show profile details (home directory, config, etc.).
alias <name> [--remove] [--name NAME]	Manage wrapper scripts for quick profile access.
rename <old> <new>	Rename a profile.
export <name> [-o FILE]	Export a profile to a .tar.gz archive (local backup).
import <archive> [--name NAME]	Import a profile from a .tar.gz archive (local restore).
install <source> [--name N] [--alias] [--force] [-y]	Install a profile distribution from a git URL or local directory.
update <name> [--force-config] [-y]	Re-pull a distribution; preserves user data (memories, sessions, auth).
info <name>	Show a profile's distribution manifest (version, requirements, source).

Examples:

minerva profile list
minerva profile create work --clone
minerva profile use work
minerva profile alias work --name h-work
minerva profile export work -o work-backup.tar.gz
minerva profile import work-backup.tar.gz --name restored
minerva profile install github.com/user/my-distro --alias
minerva profile update work
minerva -p work chat -q "Hello from work profile"

minerva completion

minerva completion [bash|zsh|fish]

Print a shell completion script to stdout. Source the output in your shell profile for tab-completion of Minerva commands, subcommands, and profile names.

Examples:

# Bash
minerva completion bash >> ~/.bashrc

# Zsh
minerva completion zsh >> ~/.zshrc

# Fish
minerva completion fish > ~/.config/fish/completions/minerva.fish

minerva update

minerva update [--gateway] [--check] [--plan] [--no-backup] [--backup] [--yes]
               [--branch NAME] [--switch-branch] [--keep-stash] [--force] [--force-venv]

Pulls the latest minerva-agent code and reinstalls dependencies in the managed venv, then re-runs the post-install hooks (MCP servers, skills sync, completion install). Safe to run on a live install. Use --check to see whether your checkout is behind origin/main without installing.

minerva update pulls the configured update branch (default: main). If your checkout is on another branch, Minerva may check out the update branch before pulling. Commit branch work before updating when you want to keep it outside the update autostash flow.

Option	Description
--gateway	Internal mode used by the messaging /update command. Uses file-based IPC for prompts and progress streaming instead of reading from terminal stdin. Not a gateway restart flag.
--check	Check whether an update is available without pulling, installing dependencies, or restarting anything.
--plan	Print the update plan and exit without changing anything: install kind (release/git/Docker/Nix), every running Minerva service across all profiles with its supervisor and running code version, and how each will be restarted. On image- or package-managed installs, reports the correct external update command instead. Read-only.
--no-backup	Skip all pre-update backups for this run (both the quick state snapshot and the full zip), regardless of updates.pre_update_backup.
--backup	Force a full pre-update backup for this run: the quick state snapshot plus a complete zip of MINERVA_HOME (config, auth, sessions, skills, pairing data). The default mode is quick — a lightweight state snapshot only. Set the permanent mode via `updates.pre_update_backup: quick
--yes, -y	Assume yes for interactive prompts such as config migration and stash restore, and skip the fork-upstream prompt without adding a remote. API-key entry is skipped; run minerva config migrate separately for those.
--branch NAME	Update against this branch instead of the default (main). If the checkout is on another branch, Minerva switches to it first, auto-stashing uncommitted changes.
--switch-branch	Only meaningful with updates.parked_branch_strategy: update_in_place. Overrides it for this run: switch to the update target and update there, leaving the checked-out branch untouched (no merge commit written into its history). No effect under the default switch strategy. Still refuses a dirty tree.
--keep-stash	Do not re-apply local changes after the update. They are still stashed so the update can proceed, but stay parked in git stash instead of being restored onto the new code. The desktop updater uses this so local source edits never silently ride along.
--force	Windows only: proceed even when another minerva.exe is detected (expect WinError 32 warnings). Does not bypass the venv-process guard — that is --force-venv.
--force-venv	Windows only: mutate the venv while other processes are running from its interpreter (desktop backend, gateway, terminals). Those hold native .pyd files locked, so the dependency sync will likely fail partway and strand the install half-updated. Use only when the detected holders are provably false positives.

Additional behavior:

• Gateway restart. After a successful update, Minerva attempts to restart all running gateway profiles automatically so they pick up the new code. Use minerva gateway restart when you want to restart a gateway without applying an update.
• Restart-phase recovery. If the in-process restart phase aborts while importing the freshly pulled tree, supervised gateway profiles are retried through a clean Python process. Only restarts independently confirmed by systemd (systemctl --user is-active) are reported as verified; a relaunch that merely exited 0 is recorded as relaunch_attempted and still fails the update conservatively. Manual gateways and serve/dashboard runtimes are never killed without a relaunch authority; they are recorded as skipped with a reason and remain in the incomplete-update report with the exact restart command.
• Update receipts + fleet version check. Every run writes a machine-readable receipt to ~/.minerva/logs/update_receipts/ (pre-update fleet plan, steps, skips with reasons, restart outcome; latest.json points at the newest). After the restart phase the updater verifies each live gateway's running code against the updated checkout and prints a per-profile version matrix; a gateway still on pre-update code fails the update (exit 1) with the exact restart command.
• Local source changes. For git installs, dirty tracked files and untracked files are auto-stashed before branch checkout or pull (git stash push --include-untracked). Interactive terminal updates ask before restoring the stash. Non-interactive updates restore it by default; set updates.non_interactive_local_changes: discard only on managed installs where local source edits should be thrown away after a successful pull. If stash restore conflicts or the pull fails, the stash is left in place for manual recovery.
• npm lockfile churn. Before stashing or switching branches, Minerva makes a best-effort cleanup of tracked package-lock.json diffs produced by npm install/build steps. Commit or manually stash intentional lockfile edits before running minerva update.
• Pairing data snapshot. Without --backup, minerva update still takes the default quick pre-update state snapshot, which includes your pairing stores (pairing/, platforms/pairing/) alongside state.db, config.yaml, .env and auth.json. Only --no-backup or updates.pre_update_backup: off skips it. Roll back with /snapshot list and /snapshot restore <id> inside minerva.
• Legacy minerva.service warning. If Minerva detects a pre-rename minerva.service systemd unit (instead of the current minerva-gateway.service), it prints a one-time migration hint so you can avoid flap-loop issues.
• Exit codes. 0 on success, 1 on pull/install/post-install errors, 2 on unexpected working-tree changes that block git pull.

Maintenance commands

Command	Description
minerva --version	Print version information.
minerva update	Pull latest changes and reinstall dependencies.

| minerva uninstall [--full] [--gui] [--dry-run] [--yes] | Remove Minerva, optionally deleting all config/data. --gui removes only the desktop Chat GUI, leaving the agent intact; --full also deletes config/data; --dry-run prints what would be removed without changing anything; --yes skips prompts. |

See also

• Slash Commands Reference
• CLI Interface
• Sessions
• Skills System
• Skins & Themes