Guides

Headless and CI.

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

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:

Shell

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:

Shell

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:

Shell

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.

Shell

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.

Shell

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.

Shell

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 for the full command and flag surface.
How an agent run works for what each approval mode permits.