CLI Reference

The root command:

mushroom-agent <command> [options]

Available commands:

Command	Description
init	Initialize local config, secrets, prompts, and node settings
accesskey	Manage agent server accesskeys
start	Start the local agent server, attach the current local device runtime, and open the browser UI
serve	Start the agent service and API transports
node	Attach device runtime and run hardware diagnostics
tools	Inspect registered tools
skills	List, discover, and install instruction skills
memory	Add local files to agent memory
eval-live	Run live evaluation cases against the configured local agent
eval-benchmark	Run and compare benchmark suites
tui	Open the terminal UI

mushroom-agent init

Initialize the local environment under ~/.mushroom_agent/. The command starts an interactive wizard that writes text-mode or voice-mode model configuration into config.yaml.

mushroom-agent init
mushroom-agent init --root /custom/path
mushroom-agent init --force
mushroom-agent init --mode agent
mushroom-agent init --mode agent --run-mode voice
mushroom-agent init --mode node --server-url ws://host:7860 --access-key <accesskey>

This creates the default generated files:

config.yaml
node.yaml
<local secrets sidecar>
logs/
skills/
prompts/
  SOUL.md
  AGENTS.md
  IDENTITY.md
  APPROACH_GREETING.md

The generated config.yaml starter keeps local paths implicit. Logs, the default skills/ directory, memory storage, prompt files, and tool working directories are derived from the local root at runtime. Secrets entered in the wizard are written to a local secrets sidecar and referenced from config.yaml. node.yaml contains the node identity, remote attachment settings, and builtin device capability settings for start and node attach.

prompts/SOUL.md, prompts/AGENTS.md, and prompts/IDENTITY.md provide starter files for persona, rules, and identity. prompts/APPROACH_GREETING.md tunes camera-approach greeting style and is read only for that event.

Options:

Option	Description
--root	Custom root directory (default: ~/.mushroom_agent)
--force	Overwrite existing generated config files
--mode agent|node	agent writes the agent host config; node writes only remote attach config
--run-mode text|voice	agent mode profile; skips the Pure text / Voice prompt
--server-url	node mode remote server URL, for example ws://host:7860
--access-key	node mode accesskey issued by the agent host
--node-name	Human-readable node name for node mode
--proxy	Optional outbound proxy for node WebSocket attachment

mushroom-agent accesskey

Manage agent server accesskeys. Accesskey plaintext is printed only when an accesskey is created; config.yaml stores server.accesskeys with accesskey hashes and previews. Accesskeys do not expire automatically; use disable or delete to revoke one.

mushroom-agent accesskey create --name "Kitchen Pi" --node-id pi-kitchen
mushroom-agent accesskey list
mushroom-agent accesskey disable akid_xxx
mushroom-agent accesskey enable akid_xxx
mushroom-agent accesskey delete akid_xxx

accesskey list also reads accesskey_usage.yaml next to config.yaml and shows the most recent node that used each accesskey.

mushroom-agent start

Start the configured local agent server and attach the configured local node runtime from node.yaml. The browser UI is always enabled, the URL is printed, and the browser opens when the server is ready.

export MUSHROOM_SKIP_LANGFUSE_AUTH=1
mushroom-agent start
mushroom-agent start --host 127.0.0.1 --port 7860

Options:

Option	Description
--config	Path to config file
--host	UI server host (default: read from server.host)
--port	UI server port (default: read from server.port)

The local UI includes the Local I/O view for configured audio, text, video, User/Agent voice text, latest video preview frame, command summaries, and hardware output events.

mushroom-agent serve

Start the agent service from config.yaml. This is the service/API entrypoint for HTTP chat, WebSocket chat, realtime voice, and function communication.

export MUSHROOM_SKIP_LANGFUSE_AUTH=1
mushroom-agent serve

Options:

Option	Description
--config	Path to config file
--communications	Comma-separated transports: http, websocket, func
--port	HTTP port (default: 7860)

Browser UI

Use --ui for local browser testing. It mounts /web, prints the URL, and opens the browser by default.

mushroom-agent serve --ui

Option	Description
--ui	Mount the local browser test page at /web

mushroom-agent node

Attach the configured device runtime to a remote service or run local hardware diagnostics. Single-machine startup is handled by mushroom-agent start.

node attach

Attach this device runtime to a remote agent service configured in node.yaml.

# 1. On the agent host
mushroom-agent serve

# 2. On each device
mushroom-agent node attach

Options:

Option	Description
--config	Path to the local config file whose sibling node.yaml should be used
--mode remote|standalone	Runtime mode for node attach; default is remote
--standalone-entry	Python entry file for a standalone node app when --mode standalone
--standalone-config	Optional YAML config for the standalone node app

node record-audio

Capture local audio for noise suppression A/B diagnostics.

mushroom-agent node record-audio --seconds 10

Options:

Option	Description
--seconds	Recording duration in seconds
--config	Path to config file

mushroom-agent skills

Manage installed skills.

mushroom-agent skills list
mushroom-agent skills available
mushroom-agent skills available --source local --from ./skills
mushroom-agent skills available --source git --from https://github.com/org/skills.git
mushroom-agent skills install <name>
mushroom-agent skills install <name> --force
mushroom-agent skills install --source <repo-or-dir> --all --target ~/.mushroom_agent/skills

mushroom-agent tools

Inspect tools registered from builtin configuration and MCP discovery.

mushroom-agent tools list

mushroom-agent memory

Add a local text or Markdown file to agent memory.

mushroom-agent memory add-file ./notes.md
mushroom-agent memory add-file ./notes.md --session sess-123 --modality document

Options:

Option	Description
--config	Path to config file
--session	Optional session id; omit for agent-wide public memory
--modality text|document	Memory resource modality

mushroom-agent eval-live

Run live eval cases against the configured local agent. This uses the real configured LLM unless --dry-run is set.

mushroom-agent eval-live --suite smoke --dry-run
mushroom-agent eval-live --suite all --samples 2 --no-enable-judge
mushroom-agent eval-live --case-id <case-id> --enable-judge

Key options:

Option	Description
--config	Path to config file
--suite smoke|all	Eval suite
--capability	Filter by capability tag
--case-id	Run a single case by id
--samples	Independent samples per case
--enable-judge / --no-enable-judge	Enable or disable LLM-as-judge metrics
--judge-metrics	Comma-separated judge metric ids
--dry-run	Load config and cases without LLM or judge calls
--case-timeout	Per-sample timeout in seconds
--write-baseline	Write a candidate baseline file
--silence	Suppress logs

mushroom-agent eval-benchmark

Run benchmark cases or compare benchmark summaries.

mushroom-agent eval-benchmark run --suite smoke --dry-run
mushroom-agent eval-benchmark run --suite all --samples 3 --label candidate
mushroom-agent eval-benchmark compare --against baseline.json --candidate candidate.json

eval-benchmark run accepts most live-eval filters plus benchmark output controls such as --output-dir and --label. eval-benchmark compare compares two summary JSON files with latency and pass-rate thresholds.

mushroom-agent tui

Open the terminal UI. It can use a local config or attach to an existing server.

mushroom-agent tui
mushroom-agent tui --host 127.0.0.1 --port 7860
mushroom-agent tui --attach-url ws://127.0.0.1:7860/ws/v1/chat --accesskey <accesskey>

Local vs Remote

serve --ui

Starts the service/API path and mounts /web.

start

Agent and configured device runtime together in one process with the local UI.

serve + node attach

Start the agent on a host, then attach one or more configured devices to it.