Running Agents

Starting a run

Queue gives you two ways to kick off an agent: pass the goal inline as an argument, or let the CLI prompt you interactively.

queue run <agent-name> "<goal>"

Output streams to your terminal in real time. Each step prints a short reasoning summary alongside any tool calls the agent made. Hit Ctrl+C at any point to cancel — Queue stops cleanly and preserves the partial trace so you can inspect what happened.

Flags

All flags below can be combined in a single run.

--model

Override the model for this run. Changes take effect immediately without touching your agent config.

queue run my-agent "..." --model o3

--max-steps

Set an upper bound on how many reasoning steps the agent can take. Useful when you need tighter control over cost or want to cap exploration on an open-ended task.

--timeout

Hard wall-clock limit in seconds. If the agent hasn’t finished by then, Queue cancels it gracefully and saves the trace up to that point.

--context

Feed the agent additional context — a file path, a URL, or a glob. You can pass the flag multiple times. The content is prepended to the agent’s system context before the run starts.

queue run my-agent "..." --context src/schema.ts --context https://example.com/api-spec

--dry-run

Trace the agent’s reasoning without executing any tools or writing anything to disk. Queue prints what each step would have done — handy for auditing a new agent before letting it run for real.

--env

Target a specific environment. Agents can carry distinct credentials, tool configs, and integrations per environment, so you can test in staging before promoting to production.

queue run my-agent "..." --env staging

Interactive mode

queue run my-agent "..." --interactive

The agent pauses at any step marked as a checkpoint in your config and waits for you to confirm before continuing. Use this when you want human sign-off on irreversible actions — file writes, API calls, deployments — without giving up the speed benefits of automation everywhere else.

Quiet mode

queue run my-agent "..." --quiet

Suppress per-step output and only print the final result. Ideal for scripting or piping Queue into other tools where intermediate noise would break downstream parsing.

Reading the output

A completed run prints the final answer, total step count, token usage, and a link to the full trace in the Queue dashboard. Add --json to receive everything as a structured object instead.

queue run my-agent "..." --json | jq .result