Headless runs

crystal run runs one task and exits. It does not open the alternate screen. Quote the task, or omit it and pipe the task on stdin. A task argument wins over stdin. Slash commands are rejected.

crystal run --workspace . --approval review --duration 600 "Fix the failing test."
echo "Summarize the repository." | crystal run --model-calls 8 --tool-calls 32

--format default prints a readable trace: the assistant reply, then each tool beside its result.

Tool	What the trace keeps
read, list, glob, grep, other successes	A short head excerpt and how many lines were omitted
edit, write	The result
bash	The command, the exit status, and a short tail. The tail is longer when the command fails
Other failures	The result text

Labels use square brackets, exit status uses parentheses, and omitted-line markers use angle brackets. Host text stays distinct from tool output.

--format json prints one JSON object per line and keeps the full tool output. Thinking is omitted unless --show-thinking is set. With that flag, thinking is under [Thinking] and the reply is under [Assistant]. The saved session id is printed at the end. Resume it with crystal --resume <id>.

Flags override the saved configuration for this process only. They are not written to config.json. Do not put secrets on the command line. An omitted flag keeps the saved value, or the product default when that is also unset. --workspace-trust does not: omitting it checks the directory. unlimited removes that one cap.

Option	Meaning
-p, --provider / -m, --model	Provider and model for this process
-w, --workspace / --home	Workspace root and data directory
--space	Use the operator space {home}/space as the workspace. Creates it when missing. Cannot be combined with --workspace
--approval <mode>	default, edit, review, audit, or full
--approval-model <on|off>	Use the saved approval model, or turn it off for this process
--approval-provider <provider>	Approval-model provider for this process. Turns the switch on
--approval-model-id <model>	Approval-model id for this process. Turns the switch on
--approval-thinking <effort>	Reviewer thinking gear for this process. Same values as /approval thinking; an unsupported gear falls back to the provider default and a note is printed, and a value that is not an effort token exits 1. Does not write the file
--compaction-model <on|off>	Use the saved compaction model, or turn it off for this process. on needs a saved selection, or --compaction-provider and --compaction-model-id on the same command. Does not write the file
--compaction-provider <provider>	Compaction-model provider for this process. Turns the switch on
--compaction-model-id <model>	Compaction-model id for this process. Turns the switch on
--compaction-thinking <effort>	Summarizer thinking gear for this process. Same values as /compact thinking. An unsupported gear falls back to the provider default and a note is printed. Does not write the file
--plan / --work	Start in Plan or Work. The default is Work
--thinking <effort>	Same values as /thinking. An unsupported gear is ignored, a note is printed, and the request uses the provider default. A value that is not an effort token exits 1
--context <budget>	Local context budget for the selected model when it declares more than one. Same text as /context. A model with one budget, or a budget it does not declare, exits 1. Does not write contextSelections
--tier <token>	Service-tier token the selected model lists. A model that does not list it exits 1. Does not write tierSelections
--speed <token>, --fast <token>	Speed token the selected model lists. A model that does not list it exits 1. Does not write speedSelections
--prompt-set <name>	Force one home prompt set for this process, even when its prompt.json says enabled false. default forces the built-in text. Does not write the file
--prompt-attachments <on|off>	on follows each attachment’s enabled flag and order. off appends nothing. Omitted means on. Does not write the file
--prompt-attachment <name>	Repeatable. Appends that attachment after the enabled set, even when enabled is false. A missing name exits 1. Cannot be combined with --prompt-attachments off. Does not write the file
--skills, --external-tools, --plugins	on or off for this process
--rules <value>	on or off for both rule-file sides, or comma-separated global=on|off and project=on|off. An assignment leaves the other side as saved. Does not write the file, and does not affect instructions.md or .crystal.md
--workspace-trust <on|off>	Directory trust for this process only. Omitted and on refuse an untrusted directory. off skips the check and does not record trust. This does not follow workspaceTrust
--model-calls <count>	Model rounds for this turn. Default 1024
--tool-calls <count>	Tool calls for this turn. Default 8192. 0 allows none
--duration <seconds>	Wall-clock cap for this turn. Default 7 days. Pass a short value in CI
--bash-timeout <seconds>	Foreground per-command bash cap. Default 600. unlimited disables that timer
--disable-tool <name>	Repeatable. Omits that built-in tool for this process. An unknown name refuses to start. Does not write the file, and does not free the name
--show-thinking	Print reasoning text for this run, and label each reply [Assistant]. Independent of verboseThinking
--format	default for plain text, or json for one JSON object per line

--approval-model off cannot be combined with --approval-provider or --approval-model-id. --approval-model on needs a saved approval model or --approval-model-id. --approval-thinking sets a gear for this process only. /approval model keeps the saved gear. /approval thinking is the command that writes one. The process gear is ignored while the switch is off.

--workspace-trust does not inherit the saved setting. Leaving it out checks the directory even when workspaceTrust is false. An untrusted directory exits 4 before a session starts. Trust it from the interactive terminal, or pass --workspace-trust off. crystal run --space uses the operator space, which is already trusted.

There is no operator. In Review and Audit the reviewing model still judges calls that require review. Allow runs the tool. Deny returns the reviewer’s reason to the model. That model is the session model unless the approval-model switch is on. Anything that would ask the operator, including Default, Edit, and Full prompts, is denied. The question tool is dismissed. Plan does not offer write, edit, or bash. Credential paths stay forbidden.

A reviewer denial is a tool error. If the model then finishes, the process exits 0. A denied operator prompt or a dismissed question does not. A call to a tool Plan does not offer fails the turn.

Exit	Meaning
0	The turn completed, and no operator prompt was denied or dismissed
1	The command, configuration, credentials, workspace, or prompt set is invalid
2	The model request failed, or the model stopped because of a content filter
3	A model-call, tool-call, or duration budget was reached, the context overflowed, or the model output was truncated
4	The turn finished after an operator prompt was denied or a question was dismissed
5	The run was interrupted

A failure, a budget stop, or an interrupt is reported instead of a denial. Plain stdout then includes [Stopped] and the session id.

Each JSON line has type, a UTC timestamp, and sessionID.

type	Extra fields
tool_use	name, callId, arguments, status (success or failure), output
step_finish	reason, modelCalls, toolCalls
reasoning	Present only with --show-thinking
stopped	Present only when the process will exit non-zero
session	text is the same resume hint the plain format prints

Other types are step_start, text, error, note, and retry. Invalid commands and missing credentials are still plain text on stderr.