Complete mirror_neuron CLI command reference

This page documents every command available in the mirror_neuron binary. Commands are grouped by purpose. For each command you will find the exact syntax, available flags, and a practical example you can run directly.

Build the binary with mix escript.build before running any commands. See the CLI overview for setup steps.

Server

`standalone-start`

Starts an isolated, standalone runtime server instance. Use this for single-node deployments and local development where you do not need cluster membership.

./mirror_neuron standalone-start

Cluster

Use the cluster subcommands to start, discover, inspect, and manage the peer-to-peer distribution and membership lifecycle.

cluster start

Start a new cluster node. The node binds to the given address and optionally joins existing seed nodes on startup.Syntax

./mirror_neuron cluster start --node-id <id> --bind <ip:port> [--data-dir <dir>] [--join <seeds>]

Flags

Flag	Required	Description
`--node-id`	Yes	Unique identifier for this node
`--bind`	Yes	IP address and port to bind to (e.g. `127.0.0.1:4000`)
`--data-dir`	No	Directory for persistent node data
`--join`	No	Comma-separated list of seed node addresses to join on startup

Example

./mirror_neuron cluster start --node-id my-node --bind 127.0.0.1:4000

cluster join

Join an existing cluster by connecting to one or more seed nodes.Syntax

./mirror_neuron cluster join --node-id <id> --bind <ip:port> --seeds <seeds>

Flags

Flag	Required	Description
`--node-id`	Yes	Unique identifier for this node
`--bind`	Yes	IP address and port to bind to
`--seeds`	Yes	Comma-separated seed node addresses

Example

./mirror_neuron cluster join --node-id my-node-2 --bind 127.0.0.1:4001 --seeds my-node@127.0.0.1

cluster discover

Query seed nodes to discover current cluster membership without joining.Syntax

./mirror_neuron cluster discover --seeds <seeds>

Example

./mirror_neuron cluster discover --seeds my-node@127.0.0.1

cluster status

Print the current cluster status, including membership and leader information.

./mirror_neuron cluster status

cluster nodes

List all known nodes in the cluster.

./mirror_neuron cluster nodes

You can also pass --join to connect to a seed before listing:

./mirror_neuron cluster nodes --join my-node@127.0.0.1

cluster leave

Gracefully remove a node from the cluster.Syntax

./mirror_neuron cluster leave --node-id <id>

Example

./mirror_neuron cluster leave --node-id my-node-2

cluster rebalance

Trigger a job and resource rebalance across all current cluster members.

./mirror_neuron cluster rebalance

cluster elect-leader

Force a new leader election among the current cluster members.

./mirror_neuron cluster elect-leader

cluster health

Check the health of the cluster and print a status summary.

./mirror_neuron cluster health

cluster reload

Reload configuration on a specific cluster node without restarting it.Syntax

./mirror_neuron cluster reload --node-id <id>

Example

./mirror_neuron cluster reload --node-id my-node

Job lifecycle

`validate`

Check a job bundle before submitting it. Validates the bundle structure, manifest syntax, and the node and edge relationships in the workflow graph. Fix any reported errors before running.

./mirror_neuron validate <job-folder>

Example

./mirror_neuron validate examples/research_flow

`run`

Submit a job bundle for execution. In the default interactive mode the CLI displays a banner, a job submission card, a live progress panel, and a final summary. Use flags to switch to machine-readable or detached modes. Syntax

./mirror_neuron run <job-folder> [--json] [--timeout <ms>] [--no-await]

Flags

Flag	Description
`--json`	Output machine-readable JSON instead of the interactive display
`--timeout <ms>`	Abort and return an error if the job does not complete within `<ms>` milliseconds
`--no-await`	Submit the job and return immediately without waiting for completion

Interactive (default)
JSON output
Detached
With timeout

./mirror_neuron run examples/research_flow

Shows a live progress panel and final summary in your terminal.

./mirror_neuron run examples/research_flow --json

Prints structured JSON — useful for automation and scripting.

./mirror_neuron run examples/research_flow --no-await

Submits the job and exits immediately. Use job inspect to check status later.

./mirror_neuron run examples/research_flow --timeout 10000

Returns an error if the job does not complete within 10 seconds.

Inspection

Use these commands to read runtime state without modifying it.

job list

List all jobs the runtime knows about.Syntax

./mirror_neuron job list [--live]

Pass --live to continuously refresh the list.Example

./mirror_neuron job list
./mirror_neuron job list --live

job inspect

Print a detailed summary of a single job, including its status, agent graph, and runtime footprint.Syntax

./mirror_neuron job inspect <job_id>

Example

./mirror_neuron job inspect job_abc123

agent list

List all agents belonging to a specific job, including each agent’s current status.Syntax

./mirror_neuron agent list <job_id>

Example

./mirror_neuron agent list job_abc123

node list

List all runtime nodes currently visible to this instance.

./mirror_neuron node list

events

Stream the event log for a job. Useful for debugging message flow, seeing lease events, and seeing sandbox completion or failure events.Syntax

./mirror_neuron events <job_id>

Example

./mirror_neuron events job_abc123

Monitor

The monitor command opens a terminal monitor — the CLI equivalent of a lightweight operations dashboard. At the top level it shows cluster nodes, executor pool usage, visible jobs, how many boxes each job is using, sandbox count per job, and the last significant event. Selecting a job drills down to agents, sandboxes, and recent events for that job. Syntax

./mirror_neuron monitor [--json] [--running-only] [--limit <n>] [--box1-ip <ip>] [--box2-ip <ip>] [--self-ip <ip>]

Flags

Flag	Description
`--json`	Output a machine-readable JSON snapshot instead of the interactive display
`--running-only`	Show only jobs with a `running` status
`--limit <n>`	Limit the number of jobs shown in the overview
`--box1-ip <ip>`	IP address of the first cluster box to connect to
`--box2-ip <ip>`	IP address of the second cluster box to connect to
`--self-ip <ip>`	IP address of this machine, used when connecting to a remote cluster

Local
JSON output
Running jobs only
Cluster mode

./mirror_neuron monitor

Monitor controls:

Type a row number to open a job
Type a full job ID to open it directly
Press r to refresh
Press b to go back
Press q to quit

./mirror_neuron monitor --json

Returns a structured JSON snapshot of cluster and job state. Useful for automation, scripting, and building dashboards.

./mirror_neuron monitor --running-only

Filters the job list to only show jobs with a running status.

./mirror_neuron monitor \
  --box1-ip 192.168.4.29 \
  --box2-ip 192.168.4.35 \
  --self-ip 192.168.4.29

Creates a temporary control node that attaches to your runtime cluster and displays the combined view across all connected boxes.

The --box1-ip, --box2-ip, and --self-ip flags also accept supplementary options: --seed-ip, --redis-host, --redis-port, --cookie, and --cli-port for fine-grained cluster attachment.

Bundle

bundle reload

Reload a registered bundle by its ID, picking up any changes to its manifest or payloads without restarting the runtime.Syntax

./mirror_neuron bundle reload <bundle_id>

Example

./mirror_neuron bundle reload research_flow_v2

bundle check

Validate a registered bundle by its ID without reloading or running it.Syntax

./mirror_neuron bundle check <bundle_id>

Example

./mirror_neuron bundle check research_flow_v2

Node management

node add

Add a node to the runtime cluster by name.Syntax

./mirror_neuron node add <node_name>

Example

./mirror_neuron node add worker-node-3

node remove

Remove a node from the runtime cluster by name.Syntax

./mirror_neuron node remove <node_name>

Example

./mirror_neuron node remove worker-node-3

Job control

Use these commands to pause, resume, or cancel a running job. They communicate with the live runtime, so the target job must exist and be in an appropriate state.

pause

Pause a running job. All agents in the job will transition to paused status.Syntax

./mirror_neuron pause <job_id>

Example

./mirror_neuron pause job_abc123

resume

Resume a paused job.Syntax

./mirror_neuron resume <job_id>

Example

./mirror_neuron resume job_abc123

cancel

Cancel a job and stop all of its agents.Syntax

./mirror_neuron cancel <job_id>

Example

./mirror_neuron cancel job_abc123

Cancellation is irreversible. Use pause if you want to stop a job temporarily and resume it later.

Send

Inject a message envelope directly into a specific agent in a running job. The message must be valid JSON. Use this for manual testing, sensor-style workflows where external input drives agent transitions, and operator intervention. Syntax

./mirror_neuron send <job_id> <agent_id> <message.json>

Example

./mirror_neuron send job_abc123 agent_sensor_01 '{"type":"manual_result","payload":{"ok":true}}'

The message JSON is passed as a shell argument, so wrap it in single quotes to prevent shell expansion of the JSON content.

Job status values

The following status values appear in job list, job inspect, and monitor output.

Job statuses
Agent statuses

Status	Meaning
`pending`	Job is submitted but not yet started
`running`	Job is actively executing
`completed`	Job finished successfully
`failed`	Job encountered an unrecoverable error
`cancelled`	Job was cancelled by an operator

Status	Meaning
`ready`	Agent is initialized and waiting for input
`busy`	Agent is processing a message
`queued`	Agent has pending work but is waiting for a slot
`running`	Agent’s executor sandbox is actively executing
`completed`	Agent has finished its work
`error`	Agent encountered an error
`paused`	Agent has been paused by a control command

Get Started

Core Concepts

Guides

CLI Reference

Configuration

Troubleshooting

Complete mirror_neuron CLI command reference

Server

`standalone-start`

Cluster

Job lifecycle

`validate`

`run`

Inspection

Monitor

Bundle

Node management

Job control

Send

Job status values

Get Started

Core Concepts

Guides

CLI Reference

Configuration

Troubleshooting

​Server

​standalone-start

​Cluster

​Job lifecycle

​validate

​run

​Inspection

​Monitor

​Bundle

​Node management

​Job control

​Send

​Job status values

Server

`standalone-start`

Cluster

Job lifecycle

`validate`

`run`

Inspection

Monitor

Bundle

Node management

Job control

Send

Job status values