Build slices from Cratis Studio with any coding agent
cratis build turns a machine into a builder for Cratis Studio. Studio offers the slices of an event model that are ready to build; the builder takes one, hands it to a coding agent or a generator, verifies the result with the kit’s commands, commits it and reports the outcome. Studio decides what is offered, retries and each slice’s status; the builder only builds.
This page is the command reference. The Builders guide explains how a builder works, how to connect and run one, how to write a generator and how to use agents and kits.
cratis build connect --studio --organization acmecratis build init --kit cratis-csharp --agent claudecratis build run| Command | What it does |
|---|---|
cratis build connect |
Registers this machine as a builder and waits for a maintainer to approve it. |
cratis build init |
Installs a build kit into a project. |
cratis build run |
Runs the build loop, or with --modeling connects an agent to a board. |
cratis build once |
Builds an exported order offline. |
cratis build status |
Shows the connection and the project’s kit and agent. |
cratis build kit validate |
Validates a kit, for kit authors. |
cratis studio fetch |
Fetches the context of a slice, feature, event model or domain for an agent. |
Agents and generators
Section titled “Agents and generators”--agent |
Agent | How it runs |
|---|---|---|
claude |
Claude Code | Natively, through its own command line. Nothing else to install. |
codex |
Codex | Over the Agent Client Protocol, through npx -y @zed-industries/codex-acp. |
gemini |
Gemini CLI | Over the Agent Client Protocol, through gemini --experimental-acp. |
copilot |
GitHub Copilot CLI | Over the Agent Client Protocol, through copilot --acp. |
opencode |
OpenCode | Over the Agent Client Protocol, through opencode acp. |
cursor, acp |
Any ACP agent | Over the Agent Client Protocol, through the command given with --agent-command. |
--agent-command overrides the command for any agent. The agent runs with its own sign-in.
A deterministic generator needs no agent: --exec <command> runs the command in the project with the order in the file named by STUDIO_BUILD_ORDER. The command writes its outcome to the file named by STUDIO_BUILD_OUTCOME; the filled prompt is in the file named by STUDIO_BUILD_PROMPT for a generator that wants it. Write a generator describes the contract in full.
What an agent gets
Section titled “What an agent gets”Every session gets, without anything installed in the project:
- The order, written to a folder outside the project, with the prompt filled from it.
- The Screenplay session guidance, the version Studio pins, verified against its checksum and cached under
~/.cratis/cache/screenplay-session. Claude Code loads it as a plugin and a system-prompt addition; agents over ACP read itsAGENTS.md.--no-guidanceleaves it out. - The kit’s instructions and skills.
- Tools: Screenplay’s tools on the order’s model, served by this CLI, and Studio’s board tools when the organization’s MCP credential is configured.
An agent is never run with its permission checks switched off. It may read the project and the folders handed to it, write only the paths the kit permits, and run only the commands the kit permits and its verification commands. Claude Code is started so that it refuses everything else; an agent over ACP asks, and the builder answers from the same rules. Web fetches are refused.
No credential is written into a prompt, a file the agent reads, an outcome or the log. Studio’s MCP token reaches Claude Code through an environment variable its MCP configuration reads, and an ACP agent through the session setup. What the builder logs and reports is scrubbed of every credential it holds and of anything that looks like one.
Verification, commits and outcomes
Section titled “Verification, commits and outcomes”The agent writes an outcome (built, blocked, nothingToDo or failed); the builder keeps only what Studio’s build contract declares for that kind. Then:
- Every verification command of the kit, and each
--verify, runs in order in the project. If any exits with anything but 0, the outcome isfailedand retryable, whatever the agent wrote. - The builder commits the files the agent reported that the kit permits, on the branch Studio names for a Studio-managed build, or on the kit’s
git.branchotherwise, with Studio’s or the kit’s message. Files outside the permitted paths are never committed. - It pushes with your own Git credentials (not with
--no-push) and reports the commit and branch with the outcome.
Anything left uncommitted after a build is put away in a Git stash named after the order, never discarded, and the repository goes back to the branch it was on.
Exit codes
Section titled “Exit codes”| Code | Meaning |
|---|---|
0 |
Done. For once, the outcome is not failed. |
2 |
Studio could not be reached. |
3 |
Studio refused the registration. |
4 |
Studio no longer accepts the builder’s credential; register again with connect --force. |
5 |
The options, the kit or the order cannot be used, or the outcome of once is failed. |
connect
Section titled “connect”cratis build connect --studio [<URL>] --organization <NAME> [--name <NAME>] [--mcp-client-id <ID>] [--mcp-url <URL>] [--force] [--no-wait] [--insecure-file-store]--studio alone means the hosted Studio, https://app.cratis.studio; give an address only for another Studio. An address copied from Studio’s builder address, https://<studio host>/builders/connect/<organization>, is accepted too and names the organization as well.
Creates a token on this machine, registers with the organization and prints a short code. A maintainer types the code in Studio under Organization settings › Builders to approve the builder; connect waits until they do. The token is kept in the operating system’s credential store (--insecure-file-store keeps it in a 0600 file instead) and never leaves this machine except to Studio.
--mcp-client-id configures the organization’s MCP credential from Organization settings › MCP, so agents get Studio’s tools and cratis studio fetch works. The secret is read from CRATIS_STUDIO_MCP_SECRET, or asked for in a terminal; it is never taken on the command line.
cratis build init --kit <KIT> [--kit-folder <PATH>] [--agent <AGENT>] [--project <PATH>] [--existing] [--studio <URL>]--kit is a kit Studio registers by name (cratis-csharp, node), a Git URL, or a folder. A Git URL may end in #<branch, tag or commit> to pin the kit; --kit-folder names the folder inside the repository that holds build-kit.yaml. The kit is validated before anything is copied; a registered kit’s archive is verified against its checksum. Then init:
- checks the commands the kit requires,
- scaffolds an empty project from the kit and runs its scaffold commands; a project that is not empty (or
--existing) is left as it is, which needs a kit that learns existing codebases: the first build learns the project’s conventions into the kit’s conventions file and later builds reuse them, - copies the kit to
.cratis/build/kit, and - installs the kit’s instructions and skills where the agent reads them:
CLAUDE.mdand.claude/skillsfor Claude Code,GEMINI.mdand.agents/skillsfor Gemini CLI,AGENTS.mdand.agents/skillsfor the others. The instructions go between<!-- cratis-build-kit:<name> -->and<!-- /cratis-build-kit:<name> -->, followed by a line per skill; the rest of an existing instruction file is kept, and runninginitagain replaces only that block.
The installation is recorded in .cratis/build/kit.json: the kit’s name and version, the archive’s checksum (or the Git URL and the commit it resolved to), the agent, and every path init wrote. run and once read the kit and agent from it.
cratis build run [--agent <AGENT> | --exec <COMMAND> | --level <LEVEL> [--target <TARGET>]] [--agent-command <COMMAND>] [--ai <ROUTE>] [--docker [--image <IMAGE>]] [--kit <PATH>] [--project <PATH>] [--verify <COMMAND>]... [--once] [--no-push] [--no-guidance]Connects, asks Studio for work and builds each slice it is given, renewing the slice’s lease while it builds. When Studio says the lease is lost, the build stops and nothing is reported. The project must be a Git repository without uncommitted changes. --once stops after one slice; Ctrl+C stops the loop, and the builder shows as offline.
The packaged builder, Docker and Studio’s AI
Section titled “The packaged builder, Docker and Studio’s AI”| Option | Meaning |
|---|---|
--level <LEVEL> |
Build with the packaged Cratis builder instead of a program of your own, at one of the levels below. Cannot be combined with --exec. |
--target <TARGET> |
With --level, what the application is built as: cratis (default; .NET on Arc and Chronicle) or axon (Java on Axon Framework). The renderer’s target at code and code-ai, and what the agent writes at ai. |
--ai <ROUTE> |
local (default): the agent uses its own sign-in and provider. studio: the agent’s model calls run through Studio’s AI gateway on the organization’s providers. Needs builder protocol version 2. |
--docker |
Run the builder in the packaged builder image, with the project mounted at /workspace. Needs Docker. |
--image <IMAGE> |
With --docker, the image to run. Defaults to the builder for --target: cratis/builder, or cratis/studio-axon-builder for axon. Without a tag, the newest version on this machine runs, or else the newest on Docker Hub is pulled; with a tag, the image runs as given. See which version runs. |
--level |
Studio mode | What happens | Needs --agent |
|---|---|---|---|
screenplay |
Screenplay only | Commits the model to the screenplay folder; no code. |
No |
code |
Static code | Commits and renders the model; no model calls. | No |
code-ai |
Static code refined by AI | Renders, then the agent implements the behavior the model describes on top of the render, without editing managed files except the places the renderer leaves open. | Yes |
ai |
AI only | Commits the model without rendering; the agent implements the slices from it with the kit’s conventions, permissions and verification commands. | Yes |
At code-ai and ai the prompt ends with Instructions from the model: the slice descriptions from the order’s context.hints, the specifications as acceptance criteria and the feedback from context.feedback. The agent also reads the command handler and query descriptions in the Screenplay documents. It records what the model leaves open as assumptions in the outcome instead of inventing behavior.
cratis build run --level code-ai --agent claudecratis build run --level ai --target axon --agent copilotcratis build once --order order.json --level code-ai --target axon --agent copilotA builder in a container, or on a build server without CLI configuration, takes its connection from CRATIS_STUDIO_URL, CRATIS_STUDIO_ORGANIZATION, CRATIS_BUILDER_ID and CRATIS_BUILDER_TOKEN. See Run the Cratis builder locally.
Modeling on a board
Section titled “Modeling on a board”cratis build run --modeling --agent <AGENT> --board <BOARD> [--name <NAME>] [--unattended]Connects the agent to an event model board instead of building. --board is the board’s identifier or its address in Studio. It shows on the board as connected, under --name or the agent’s product name (Claude Code, Codex, Gemini CLI, Cursor, Copilot CLI, OpenCode), and people hand it work by mentioning it in the board chat; its replies appear in the chat. By default the agent proposes and a person confirms: it may only read the board until a person confirms its proposal, and a declined proposal changes nothing. --unattended lets it change the board at once. Everything the agent changes on the board is attributed to it. The command ends when Studio ends the session; a refused connection ends it with the reason and a non-zero exit code. It needs the organization’s MCP credential (connect --mcp-client-id).
cratis build once --order <FILE> [--agent <AGENT> | --exec <COMMAND> | --level <LEVEL> [--target <TARGET>]] [--outcome <FILE>] [--push] [...]Builds an order exported from Studio without a connection, and writes the outcome to the standard output or --outcome. Useful for trying a kit or an agent, and in CI.
status
Section titled “status”cratis build statusShows the Studio and organization, whether the builder token and Studio’s MCP credential are stored, and the kit and agent of the current folder. Changes nothing.
service
Section titled “service”Keeps a builder running without a terminal: the build loop of one project runs as a user service that starts when you sign in and restarts 30 seconds after it stops.
cratis build service install --agent claudecratis build service statuscratis build service uninstallinstall takes the options of run (--agent, --agent-command, --exec, --kit, --project, --verify, --no-guidance, --no-push) and needs a machine registered with connect, and a project with a kit or --kit or --exec. Installing again replaces the service. Each project gets its own service, named cratis-build-<folder>-<hash>.
| Operating system | Service manager | Service file | Output |
|---|---|---|---|
| macOS | launchd agent in your sign-in session | ~/Library/LaunchAgents/io.cratis.<name>.plist |
~/Library/Logs/Cratis/<name>.log |
| Linux | systemd user unit | ~/.config/systemd/user/<name>.service (or under $XDG_CONFIG_HOME) |
journalctl --user -u <name>.service |
The service gets the PATH of the shell you installed it from, so it finds the agent, Git and the kit’s tools, and nothing else from your environment. The builder token stays in the credential store; on Linux the service reads it from the Secret Service of your session. A systemd user service stops when you sign out unless lingering is on for your user (loginctl enable-linger). Windows has no service manager the builder supports; run cratis build run there.
status reports whether the service is installed and running and where its output goes, and changes nothing. uninstall stops the service and removes its file.
kit validate
Section titled “kit validate”cratis build kit validate [PATH]Validates a kit the way Studio and the builder do: the manifest (build-kit.yaml or build-kit.json) against the format, that every file and folder it names is in the kit and not empty, that every skill has a SKILL.md, and that every placeholder is one a builder fills. Each problem is reported with a JSON pointer into the manifest. Studio’s builder documentation describes the format.
studio fetch
Section titled “studio fetch”cratis studio fetch --context <slice|feature|eventModel|domain> --id <ID> [--format markdown|text|json|yaml|toon] [--out <PATH>] [--no-guidance]Fetches the context of a slice, a feature, an event model or a domain through Studio’s export: its commands, events, read models, specifications and Screenplay, with the Screenplay guidance unless --no-guidance. text is Markdown; TOON fits a large context into a token budget. Writes to the standard output, or to --out. Uses the organization’s MCP credential configured with cratis build connect --mcp-client-id.