Command line

crucible --help prints the flags and the subcommands sandbox, config and help, under a longer introduction; crucible -h prints the same under the one-line introduction. Each subcommand has its own help, such as crucible config --help and crucible sandbox setup --help, and crucible help and crucible help <command> print the same pages. crucible --version (or -V) prints crucible and the version number on one line, and stops. All of these are answered by the parser, before a file is read or anything is started.

Run with nothing after it, crucible opens a session in the directory you are standing in, as Run it describes. The flags change what that session is. --extensions, --sandbox and the two subcommands do one thing and stop, and none of them can be combined with a session flag. crucible takes no prompt on the command line: a bare word, as in crucible "fix the bug", is refused as unrecognized subcommand 'fix the bug' and the run ends 2. The installer also links cru to the same executable, so everything here holds for cru (Install it).

Flags, session files and configuration are unstable for the whole 0.x line.

Picking up a session

Left off, crucible starts a new session. These two say which earlier one to pick up instead, and they cannot be given together.

-c, --continue

Carries on the most recent session started in this directory: the transcript is replayed to the model and new turns are appended to the same file. Continuing says what comes back with it, and Modes says why the mode does not. Where nothing was ever recorded for this directory, crucible says so and stops rather than starting a new session:

crucible: no earlier session for /home/you/api

A session another crucible still has open is refused rather than shared (One at a time).

-r, --resume <SESSION_ID>

Picks up the exact session the id names, wherever it falls in this directory's history. The id is the one a quitting session prints on its way out:

Resume this session with:
  crucible --resume 019854c2-9a1e-73f1-b0d6-2f1c4e7a58d1

and the one /resume lists inside a session (Picking one by name). An id nothing here was recorded under, or a word that is not an id at all, is refused by name rather than matched to the nearest thing:

crucible: no session 019854c2 in this workspace

Choosing the model

There is no model built in, and no provider is chosen for you. Both flags sit above your configuration: the command line is nearer than any of the three files, so what it names wins (The files).

-m, --model <MODEL>

The model to ask, as a bare name or as provider/model. Only the first slash divides the halves, so a model name with slashes of its own stays whole.

crucible --model claude-sonnet-5      # whichever provider holds a credential
crucible --model openai/gpt-5.6-terra # openai, asking for that model
crucible --model openai/              # openai, asking for its configured model

Left off, the model is providers.<name>.model for the provider being asked, and where nothing says, crucible starts and asks rather than picking one; /model writes your answer down (Which model).

A bare name goes to whichever provider holds a usable credential: a key in one of ANTHROPIC_API_KEY, DASHSCOPE_API_KEY, DEEPSEEK_API_KEY, GEMINI_API_KEY, META_API_KEY, MIMO_API_KEY, MINIMAX_API_KEY, MOONSHOT_API_KEY, OPENAI_API_KEY, XAI_API_KEY and ZAI_API_KEY (a variable exported empty holds none, so it does not compete), or one stored by /login. A key in DASHSCOPE_API_KEY, MINIMAX_API_KEY or ZAI_API_KEY is sent to the vendor's international site; a key of its mainland China site is given through /login, or reaches it with that provider's baseUrl. Where more than one is usable, qualify the name or set provider in the configuration file in your home directory, the only file provider, baseUrl and apiKeyEnv are read from; otherwise crucible starts with no provider chosen and says so (Which provider). The key is read from that provider's variable, or from whichever one its apiKeyEnv names (Keys).

A name with nothing before the slash is refused once your configuration has been read, before a session starts or anything is drawn:

crucible: --model needs a provider before the slash, as in --model openai/gpt-5.6-terra

A provider this build does not have is refused at the same point, with the ones it has:

crucible: no provider called gemini; this build has anthropic, deepseek, google, meta, mimo, minimax, moonshot, openai, qwen, xai, zai

-e, --effort <RUNG>

How hard to think on every turn of the session: low, medium, high, xhigh or max, in whatever case you type it (HIGH is high). Left off, it is providers.<name>.effort for the provider being asked, and where nothing says either, the vendor's own default for the model. Not every model takes a rung, and one named for a model that does not is refused by its vendor rather than dropped (How hard to think).

crucible --effort max

A word that is not a rung is a usage error: the parser refuses it before anything is read, carrying crucible's sentence no effort called maximum; crucible takes low, medium, high, xhigh, max, and exits 2.

Hosting an MCP server

--with-mcp <NAME>

Hosts the MCP server written down under mcp.servers as <NAME> for this run. Repeat it for each server you want; nothing is hosted unless it is named here, however many are written down. What a hosted server offers is called as mcp:<server>/<tool>, and the server runs confined the way a command does (MCP servers).

crucible --with-mcp docs --with-mcp tickets

A name nothing wrote down stops the run rather than being left out:

crucible: no mcp server called docs; this configuration has tickets

When nothing at all is written down, the line is:

crucible: no mcp server called docs; this configuration has none under mcp.servers

Asking without starting

Each of these answers and stops. No session is started, no credential is opened, and no extension, server or command is run. --extensions and --sandbox take no other flag, and neither takes the other.

--extensions

Lists what is installed in ~/.crucible/extensions (or extensions under the directory CRUCIBLE_CODE_HOME names, when it is set), with what each manifest asks to be allowed to do and the digest crucible took over its bytes, and stops. Nothing installed is run to produce the list, which is the point of being able to read it. The first line counts what was found, as no extensions in, 1 extension in or <n> extensions in followed by the directory, or says <directory> was not read when the directory holds more than 64 subdirectories, which is more than crucible reads. One description follows per extension, and when any of them is not yet allowed the listing says once, after the descriptions, what to do about it:

nothing runs until its enabled key is true and its digest key holds the digest
printed above, both in your home configuration file

Last, a directory under it that could not be used is listed under 1 directory could not be read: (or <n> directories), with the reason beside it: it or its manifest could not be opened, the manifest was not one, it declares an identifier another directory already declares, or the extensions directory itself was over the limit. An extensions directory that itself could not be opened counts as no extensions in and is listed here too. What each description holds, how to allow one, and the limit are under Extensions.

--sandbox

The same report as crucible sandbox inspect, as text, and the same exit.

sandbox inspect [--json]

Prints the confinement a command in the current directory would run under, and stops: which backend would enforce it, what that backend can and cannot hold, the reach and ceilings a command would get, and why it would be refused. Nothing is started to produce it, not the backend, not its helper, not a command, and no file is written. Every path in it but the workspace root is a digest, so it can be pasted into an issue whole.

crucible sandbox inspect
crucible sandbox inspect --json

The first line is sandbox enabled in <root> or sandbox disabled in <root>, and mode says whether project configuration requires confinement. The backend is the first one a confined command's search would reach that passes the same trust checks, without starting it; where crucible read the backend's file it prints the file's sha256 as build. A backend's version that only starting it could tell is printed unverified, with the reason, and whatever else only starting something could check is listed under not checked, since checking would start something:. The rest is explained under Reading the report.

Each feature is enforced, observed or unsupported, and each ceiling is printed beside the claim it rests on. A backend that was found but will not take this workspace's policy prints its matrix, what was asked for, and then no command could be run here with the reason under it. No backend found prints no sandbox backend was found with its reason. Both are the answer, and the run ends 0.

--json prints one JSON document on one line to standard output instead, with format_version 1, kind sandbox-inspection, status, and a truncated flag. status is ready when a backend was found and would take the policy, refused when it would not and refusal says why, unavailable when none was found, and failed when no report could be made. Beside it are enabled, mode (optional or required), the requested and effective plans, backend with its name, provenance, version (stated with a name, or unverified with why), optional build and capabilities, and unchecked, refusal and confined. confined is never true for the compatibility backend, which runs a command as an ordinary subprocess. Each plan carries its policy and commands digests, the cwd digest, its roots (with omitted for any past the list's limit), hidden, network, ceilings (each with amount, nanos, unit and claim), staged, persistent and snapshots.

When the report cannot be made, for example because there is no home directory to read configuration from, the reason is one line beginning crucible: on standard error and the run ends 1; with --json a document with status failed and the problem is written to standard output as well. The problem names the step that stopped, such as reading configuration, and no file; the line on standard error names the file, where there is one.

config check [--json]

Reads the three configuration files the way a startup would, resolves them the way it would, and stops. The report opens with configuration valid or configuration invalid, names each file as user config, project config or project-local config with absent, valid or invalid after it, lists each failure (at most four) and ends with schema: and the schema's id (Checking without starting).

crucible config check
crucible config check --json

It exits 0 when everything holds and 1 otherwise, saying the first failure again on standard error. --json prints one JSON document to standard output instead, with format_version 1, kind config-check, status, files, failures, schema and a truncated flag. config on its own, without check, is a usage error.

The check reads each value's shape and the file it may come from. It does not ask whether a provider name is one this build serves or whether a baseUrl is an address crucible will send a key to: an http address that is not loopback passes here, and the next start refuses it.

Windows sandbox maintenance

Native confinement on Windows needs a local account and firewall policy that only an administrator can create, so it is provisioned once, by hand. Both commands run from an Administrator PowerShell; they do not elevate themselves, and an ordinary crucible run stays unelevated. What they create and remove is described under Windows setup maintenance. Both run inside crucible.exe itself; the crucible-sandbox-broker.exe that a confined command later starts through is not needed for them, and where it comes from is under Install it. On Linux and macOS the broker is installed beside crucible and there is nothing to run (Turning it on).

sandbox setup [--owner <ACCOUNT>]

Provisions or repairs the native Windows sandbox. --owner names the user account to provision; left off, it is the owner of the elevated process, so name it when PowerShell was elevated as another administrator.

.\crucible.exe sandbox setup --owner 'MACHINE\person'

sandbox uninstall [--owner <ACCOUNT>]

Removes the native Windows account, network policy and setup record. --owner is the account whose setup is removed, and defaults the same way; give it the value setup was given.

.\crucible.exe sandbox uninstall

Either command prints what it did on standard output and exits 0. A failure is one line on standard error beginning crucible: Windows sandbox maintenance failed: with the reason, and exits 1. On any other operating system that is the answer too:

crucible: Windows sandbox maintenance failed: the native Windows sandbox is available only on Windows

sandbox on its own, without inspect, setup or uninstall, is a usage error.

Running without a terminal

When input or output is redirected, crucible < prompts.txt, there is no box to type in: each line of input is one prompt, taken in order, and the run ends at the end of the input. A blank line is skipped, and a line whose first word is a slash followed by letters, such as /effort high, is taken as a command, as it would be in the box, rather than sent. What the output looks like is under Run it, and a permission question with nobody to answer it is a refusal (When nobody can answer). Three things end such a run early, each with one line on standard error and exit status 1. Input that cannot be read, or a line that is not UTF-8:

crucible: could not read what you typed: <reason>

A line longer than 1 MiB:

crucible: what you typed is longer than 1 MiB; no prompt was accepted

and, when output is redirected as well, a prompt arriving where there is no model to ask, since nobody is there to type /model. Rather than reading every remaining line and answering none of them, the run says so and fails:

crucible: Warning: No models available. Use /login or set an API key environment variable. Then use /model to select a model. No turn was taken.

When a provider is chosen and only the model is missing, the sentence is Warning: No model selected. Use /model to select the model to ask. instead. When credentials are set up but no provider was chosen, it is Warning: No provider selected. Use /model to select a provider and model. Either way No turn was taken. follows it. With output still on a terminal, the warning is drawn there instead and the run goes on to the next line.

Exit status

Flags that exclude each other are refused with a line saying one cannot be used with the other: --continue with --resume, --extensions or --sandbox with any session flag or with each other, and any flag with a subcommand.