Agent Commands via CLI

Copy-paste reference

# Run
machina agent run <name>                     # async by default
machina agent run <name> key=value --watch
machina agent run <name> --sync

# Inspect
machina agent list
machina agent get <name>
machina agent executions
machina execution get <execution-id>

# Human gate (if the agent's workflow files an approval request)
machina approvals list
machina approvals approve <request-id>
machina approvals reject <request-id>

# Connect an external agent to this project (so it can call things over MCP)
machina connect --probe
machina mcp url

Full flag reference: agent, execution, approvals, mcp, connect.

Four different things that sound similar

It's easy to conflate these. They're distinct layers:

Layer	What it is	How you invoke it
CLI command	A machina binary command you type in your terminal.	machina agent run my-agent
Instruction sent to an Agent	The parameters/payload a run receives — key=value pairs on the command line, or fields prompted interactively.	The season_id=sr:season:123 part of machina agent run my-agent season_id=sr:season:123
Workflow	What actually executes — the DAG of connectors, prompts, and mappings that does the work. An Agent's job is to trigger one or more Workflows on a schedule.	Not invoked directly by you when it's agent-triggered; you can also run one standalone with machina workflow run <name>
MCP tool	A capability exposed over the Model Context Protocol so an external agent (not a person at a terminal) can call it — e.g. a workflow or agent published via MCP Builder.	Called by an external MCP client, not by you running machina

Concretely: when you run machina agent run my-agent season_id=sr:season:123, you're issuing a CLI command, whose payload is an instruction to the agent, which triggers a workflow. If that same agent were instead published as a tool via MCP Builder, an external agent (say, SportsClaw connected through machina connect) could trigger the same underlying workflow as an MCP tool call — without ever running machina itself.

Related

• Operating Agents — the run/watch/inspect flow in more detail.
• MCP and MCP Builder — how an agent's workflow becomes an MCP tool for external callers.