> ## Documentation Index
> Fetch the complete documentation index at: https://docs.machina.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Commands via CLI

> Copy-paste command reference, and the difference between a CLI command, a workflow, and an MCP tool.

## Copy-paste reference

```bash theme={null}
# 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`](/cli/commands/agent), [`execution`](/cli/commands/execution), [`approvals`](/cli/commands/approvals), [`mcp`](/cli/commands/mcp), [`connect`](/cli/commands/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](/mcp/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`](/cli/commands/connect)) could trigger the same underlying workflow as an **MCP tool call** — without ever running `machina` itself.

## Related

* [Operating Agents](/agents/operating-agents) — the run/watch/inspect flow in more detail.
* [MCP](/mcp/overview) and [MCP Builder](/mcp/mcp-builder) — how an agent's workflow becomes an MCP tool for external callers.