> ## 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.

# Operating Agents

> Run, watch, and inspect agents from the terminal — plus the human-approval gate.

Once an agent exists and is configured, the CLI is the fast path for triggering it, watching it, and inspecting what happened.

## Run it

```bash theme={null}
machina agent run <name>                 # interactive — prompts for inputs
machina agent run <name> key=value       # inline parameters
machina agent run <name> --sync          # wait for the result
machina agent run <name> --watch         # run async and watch progress
```

Agents run **asynchronously by default** — `agent run` schedules and immediately returns a run id. That's the opposite default from `workflow run`, which is synchronous by default. Pass `--sync` to wait, or `--watch` to poll until the run reaches a terminal state.

## Check what's been running

```bash theme={null}
machina agent executions               # list recent executions for this agent
machina execution get <execution-id>    # full detail on any run, by id
machina execution get <execution-id> --compact
machina execution get <execution-id> --json
```

`execution get` works on **any** run id — one you just started, one from a scheduled cadence, or one started from Studio. It's the single place to answer "what happened on run X," regardless of what triggered it.

## When a run needs a human

Some workflows deliberately stop and wait for a person before doing something risky or public (publishing content, a bulk data change). That's the [`approvals`](/cli/commands/approvals) gate:

```bash theme={null}
machina approvals list                    # what's waiting for a decision
machina approvals approve <request-id>    # runs the stored action in-pod
machina approvals reject <request-id>     # records the decision, no action runs
```

This isn't specific to agents — any workflow can file an approval request — but it's the mechanism you'll hit if an agent's workflow is wired to gate its output. See [`approvals`](/cli/commands/approvals) for the full flow and how to gate your own workflow.

## Related

* [`agent`](/cli/commands/agent), [`execution`](/cli/commands/execution), [`approvals`](/cli/commands/approvals) — full flag reference for each.
* [Agent Commands via CLI](/agents/cli-commands) — copy-paste reference and the CLI-command-vs-workflow-vs-MCP-tool distinction.