# Headless and CI

> Run Matilda Code from scripts, pipelines, and other automation.

Source: https://maincode.com/docs/headless
Section: Matilda Code · Matilda documentation

---

## One-shot runs

Matilda Code has no separate `run` command. Pass a prompt and it executes once,
prints the result, and exits. Use the positional form, or `-p` / `--prompt`:

```bash
matilda "explain the changed files"
matilda -p "explain the changed files"
```

To run a prompt and then stay in the session, use `-i` / `--prompt-interactive`
instead.

## Piping

Matilda Code reads stdin, so it composes with the rest of your shell:

```bash
echo "explain this code" | matilda
git diff | matilda -p "review this diff and list risks"
```

> **Note** — When `-p` is passed explicitly, ambient piped stdin is ignored. That is
> deliberate, so a job that inherits a pipe cannot hang waiting on input.

## Authenticating a pipeline

Browser sign-in is for humans. CI, containers, and cron jobs use a Matilda API
token from the environment:

```bash
export MATILDA_API_KEY="<your token>"
matilda -p "summarise the failing tests"
```

## Structured output

`-o` / `--output-format` selects the shape of what comes back: `text` by
default, `json` for a single object, or `stream-json` for events as they
happen.

```bash
matilda -p "list every TODO in src/" -o json
```

For output your own code can rely on, pass a JSON Schema. The run registers a
`structured_output` tool and ends on the first valid call, so you get exactly
the shape you asked for or nothing.

```bash
matilda -p "extract the failing test names" --json-schema @schema.json
```

## Approvals in automation

A non-interactive run has nobody to approve anything. Choose a mode explicitly
with `--approval-mode`, or use `-b` / `--bogan` / `--yolo` to auto-approve
every tool call.

```bash
matilda -p "fix the lint errors" --approval-mode auto-edit
```

> **Caution** — `yolo` approves shell commands as well as edits. Reserve it for trusted
> automation in a controlled environment, and prefer `--sandbox` when the prompt
> is not fully under your control.

## Useful flags

| Field | Type | Description |
| - | - | - |
| `--prompt, -p` | `string` | Run one prompt non-interactively and exit. |
| `--prompt-interactive, -i` | `string` | Run a prompt, then continue in the interactive session. |
| `--output-format, -o` | `text \| json \| stream-json` | Shape of the CLI output. Defaults to text. |
| `--json-schema` | `string` | JSON Schema the final output must satisfy. Accepts a literal or @path/to/schema.json. |
| `--approval-mode` | `plan \| default \| auto-edit \| auto \| yolo` | How much the agent may do without asking. |
| `--model, -m` | `string` | Override the model for this invocation. |
| `--include-directories, --add-dir` | `array` | Extra directories to include in the workspace. |
| `--sandbox, -s` | `boolean` | Run tool calls inside the sandbox. |
| `--fresh, --no-resume` | `boolean` | Start a clean one-shot session without resuming or recording history. |

## Where to go next

- [CLI reference](https://maincode.com/docs/cli-reference) for the full command and flag surface.
- [How an agent run works](https://maincode.com/docs/agent-runs) for what each approval mode
  permits.