First run

Start from the workspace the agent should edit. The current directory is the workspace unless --workspace is set.

dotnet run --project CrystalCode -- --provider deepseek --model deepseek-flash

CLI options:

Option	Meaning
-p, --provider <name>	Provider name (deepseek, openai, gemini, ollama, or a name you added to providers.json)
-m, --model <id>	Model id listed under that provider
-w, --workspace <path>	Workspace root (default: current directory)
--home <path>	Data directory (default: CRYSTAL_HOME, then ~/.crystal)
-r, --resume [id]	Choose a saved session. Omit the value to list this workspace. An id loads that file and stays here. A directory lists that workspace and enters it. all lists every workspace and enters the chosen session’s directory
--approval <mode>	default, edit, review, audit, or full for this process
--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. Does not change approvalModel.thinkingEffort on disk
--compaction-model <on|off>	Use the saved compaction model, or turn it off for this process
--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. Does not change compactionModel.thinkingEffort on disk
--plan / --work	Start in Plan or Work. Omit both to keep Work, or the mode saved on a resumed session
--thinking <effort>	Same values as /thinking
--context <budget>	Local context budget for the selected model when it declares more than one. Same text as /context (272k, 1m, or an exact token count). A model with one budget, or a budget it does not declare, is rejected. Does not write contextSelections
--tier <token>	Service-tier token the selected model lists. Does not write tierSelections
--speed <token>, --fast <token>	Speed token the selected model lists. 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. /promptset switching is refused and does not write the file. Listing and export stay available
--prompt-attachments <on|off>	on follows each attachment’s enabled flag and order. off appends nothing and refuses enable, disable, up, and down. Listing stays available
--prompt-attachment <name>	Repeatable. Appends that attachment after the enabled set for this process, even when its file says enabled false. Does not write the file. Rejected together with --prompt-attachments off
--skills, --external-tools, --plugins	on or off for this process
--rules <value>	on or off for both rule-file sides, or global=on|off and project=on|off. Does not affect instructions.md or .crystal.md
--model-calls <count>	Model rounds for each turn. unlimited removes that cap
--tool-calls <count>	Tool calls for each turn. 0 allows none. unlimited removes that cap
--duration <seconds>	Wall-clock cap for each turn. unlimited removes that cap
--bash-timeout <seconds>	Foreground per-command bash cap. 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

These flags apply to this process only. Startup does not write them to config.json or prompt.json. A later slash command that saves a preference writes that preference, and also writes --provider and --model when those were passed. It does not write the other flags. --plan and --work together are rejected. crystal space accepts the same flags except --workspace.

--help prints the same options.

The first run creates ~/.crystal (or --home / CRYSTAL_HOME) and writes a starter config.json when one is missing. Defaults: provider deepseek, model deepseek-flash, approval default, compaction at 80% of the selected model’s contextWindow.

The first interactive launch in a directory asks whether you trust it when workspaceTrust is on (the default).

Answer	Result
Yes	Writes ~/.crystal/trusted.json. Inside a git repository, the question names the repository root and later launches there are trusted. Outside a repository, only that directory is trusted.
No	Exits without writing the file. The next launch asks again.

A redirected terminal cannot ask and exits with an error. /trust off skips later prompts. /cd into an untrusted root asks again. No stays in the current workspace.

If the provider has more than one model and neither config.json nor --model picks one, the process exits and asks for --model.

Operator space

crystal space creates ~/.crystal/space when it is missing and opens the terminal there. --home selects the data directory, so the space is {home}/space. It accepts the same session flags as crystal, except --workspace.

The space is trusted without a prompt and without a trusted.json entry. /space creates it when missing and switches there. It uses the same reload path as /cd and does not ask.

Trust does not climb to a parent git repository. /trust forget does not remove it. A subdirectory follows the ordinary trust rule. If space itself is a git repository, its children share that trust root. Sessions are saved under the absolute path, like any other workspace.

crystal run --space creates the directory when it is missing and runs one task there. It does not write a trust entry. --space cannot be combined with --workspace.