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

# Agent

> Submit, watch and manage an agent run from the terminal.

export const OutcrawlStyles = () => {
  if (typeof document !== 'undefined' && !document.getElementById('outcrawl-overrides')) {
    const s = document.createElement('style');
    s.id = 'outcrawl-overrides';
    s.textContent = `
      /* Match the product's radius grid (4 / 6 / 8 / 9999), not Mintlify's default. */
      .rounded-sm { border-radius: 0.375rem !important; } /* 6px, --r-ctl */
      .rounded-md { border-radius: 0.375rem !important; } /* 6px, --r-ctl */
      .rounded-lg { border-radius: 0.5rem !important; }   /* 8px, --r-panel */
      .rounded-l-sm { border-top-left-radius: 0.375rem !important; border-bottom-left-radius: 0.375rem !important; }
      .rounded-r-sm { border-top-right-radius: 0.375rem !important; border-bottom-right-radius: 0.375rem !important; }
      .rounded-l-md { border-top-left-radius: 0.375rem !important; border-bottom-left-radius: 0.375rem !important; }
      .rounded-r-md { border-top-right-radius: 0.375rem !important; border-bottom-right-radius: 0.375rem !important; }
      .rounded-l-lg { border-top-left-radius: 0.5rem !important; border-bottom-left-radius: 0.5rem !important; }
      .rounded-r-lg { border-top-right-radius: 0.5rem !important; border-bottom-right-radius: 0.5rem !important; }

      /* Cards: never pure white in light mode, matching the one-big-card surface tone. */
      .card { background-color: #fcfcfc !important; border-radius: 0.5rem !important; }
      html.dark .card { background-color: #141311 !important; }

      /* Docs hero box */
      .oc-hero { background-color: #fcfcfc; border: 1px solid #e5e2dc; }
      html.dark .oc-hero { background-color: #141311; border-color: #26241f; }
      html.dark .oc-hero h1 { color: #edeae4; }

      /* Thin, transparent-track, hide-until-hover scrollbar. */
      ::-webkit-scrollbar { width: 6px; height: 6px; background-color: transparent; }
      ::-webkit-scrollbar-track { background-color: transparent; }
      ::-webkit-scrollbar-thumb { background-color: rgba(155, 155, 155, 0.5); border-radius: 10px; transition: opacity 0.3s ease; opacity: 0; }
      ::-webkit-scrollbar-thumb:hover { background-color: rgba(155, 155, 155, 0.7); }
      *:hover::-webkit-scrollbar-thumb,
      *:focus::-webkit-scrollbar-thumb,
      *:active::-webkit-scrollbar-thumb { opacity: 1; }
      * { scrollbar-width: thin; scrollbar-color: rgba(155, 155, 155, 0.5) transparent; }
    `;
    document.head.appendChild(s);
  }
  return null;
};

<OutcrawlStyles />

Agents are the richest command family in the CLI, matching the richest family in the registry: eight routes behind one task.

## Submit a run

```bash theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
outcrawl agent "find the cheapest flight to Lisbon"
outcrawl agent "find the cheapest flight from New York to Lisbon" --budget 20.00 --max-steps 40
```

`--budget` is a hard ceiling on what the run is billed. Without it, the CLI applies a sane default rather than refusing outright; name your own once a task is worth more than that. The second search cost 7.4–9.2 credits on 2026-10-03 (n=3), so 20.00 is more than twice that. Every run starts fresh: there is no command that continues a previous run, so write each task to stand on its own. Submitting returns an id in milliseconds, the run itself can take hours, so the next commands are how you follow it.

## Watch it

```bash theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
outcrawl agent status <id>     # where it has got to, and what it has spent
outcrawl agent events <id>     # the full step-by-step log, streamed as it happens
outcrawl agent results <id>    # what it has produced so far, paginated
```

`status` is safe to poll as often as you like, it is a row read, not a browser. `events` streams, so it is the command for watching a run live rather than sampling it.

## Manage it

```bash theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
outcrawl agent cancel <id>              # stop it; work already done stays billed
outcrawl agent control <id>                    # take the wheel, the browser stays open
outcrawl agent control <id> --release          # hand it back, it resumes where you left it
outcrawl agent answer <id> --answer "<answer>"  # answer the question a paused run asked
```

`control` is the way to step in for something you would rather do yourself, a login you will not automate, a form only you should fill: the browser stays open and `control --release` hands it back on whatever page you left it on. No command sends a running agent new instructions; cancel and resubmit for that.

`answer` is for a run that stopped to ask: when it needs something only you know, its status is `paused` and `pause.question` in `agent status --json` holds what it asked. Answer it and the run carries on from where it stopped; left unanswered, the question expires and the run carries on without it. A card, a billing profile or a security code is never an answer: send it with `agent secrets add`.

## Attach a file

```bash theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
outcrawl agent files add <id> <path>
```

Hands a file to the run so it can attach it to a page. The file is destroyed when the run ends, on every ending, and there is no matching download command, `results` is how a run's own output comes back.

## Scripting: the contract every command keeps

Every command in this CLI, not only `agent`, keeps the same contract whether a person runs it or a script does, unchanged by the colour, charts and prompts a terminal now gets ([Reference](/docs/cli/reference)):

* **`--json` on any command** puts exactly the API's response body on stdout, one line, nothing else mixed in: no banner, no colour, no "next step" hint.
* **Four exit codes**: `0` worked, `1` the call was made and did not work, `2` the invocation was wrong and nothing was sent, `3` the API refused (auth, plan or tenant scope).
* **Nothing ever prompts without a real terminal.** A missing id, a `secrets create` value with nothing to read it from: each is a usage error on stderr with the exit code above, never a hang waiting on input that cannot arrive.
* **`NO_COLOR`**, set to anything, turns off every colour code even when stdout is a real terminal.
* **A secret is piped, not typed, in a script:**

```bash theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
echo "4111111111111111" | outcrawl secrets create card_amex_personal --kind card --json
```

`outcrawl agent` is no exception: run from CI with `--json`, it behaves exactly as it always has.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.