Operating Agents

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

Run it

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

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 gate:

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 for the full flow and how to gate your own workflow.

Related

• agent, execution, approvals — full flag reference for each.
• Agent Commands via CLI — copy-paste reference and the CLI-command-vs-workflow-vs-MCP-tool distinction.