Use the reference builder
cratis build, in the Cratis CLI, is the reference builder. It holds the whole conversation with Studio: connecting, waiting for approval, asking for work, keeping the claim alive, running verification, committing, pushing and reporting the outcome. What turns a slice into code is yours to choose, in three ways: a coding agent with --agent (Build with AI), any program in any language with --exec (Build with a generator), or a generator that a coding agent runs and completes (Deterministic with AI on top). A stack author describes a stack once as a build kit.
cratis build connect --studio --organization <name>cratis build init --kit <name|git url|folder> [--agent <agent>]cratis build run --agent claude|codex|gemini|copilot|opencode|cursor|acpcratis build run --exec "<command>"cratis build run --modeling --board <board> --agent <agent> [--unattended]cratis build once --order order.json --exec "<command>" | --agent <agent>cratis build statuscratis build service install|status|uninstallThis page describes how the CLI works with Studio. The CLI’s own build reference lists every option, and Build a builder shows how to build with an agent, a generator, or both.
What Studio exposes
Section titled “What Studio exposes”Everything below is served by Studio Core. The contract documents, kits and session guidance need no sign-in; they hold no organization data. Work is only handed to a registered builder, through the builder registration and connection endpoints (see The builder protocol).
| Purpose | Address | Page |
|---|---|---|
| Build order schema | GET /api/builders/contract/{version}/build-order.schema.json |
Build orders and outcomes |
| Build outcome schema | GET /api/builders/contract/{version}/build-outcome.schema.json |
Build orders and outcomes |
| Kit manifest schema | GET /api/builders/kits/schema/{version}/build-kit.schema.json |
Build kits |
| Registered kits | GET /api/builders/kits |
Build kits |
| One kit’s manifest | GET /api/builders/kits/{name} |
Build kits |
| One kit as an archive | GET /api/builders/kits/{name}/archive |
Build kits |
| Validate a kit | POST /api/builders/kits/validate |
Build kits |
| Agent session descriptor | GET /api/builders/session |
Agent sessions |
| Screenplay guidance archive | GET /api/builders/session/screenplay-session.zip |
Agent sessions |
| Live modeling on a board | MCP tools studio_connect_local_agent, studio_poll_local_agent, studio_take_local_agent_prompt, studio_answer_local_agent_prompt, studio_disconnect_local_agent |
Live modeling with your own agent |
Studio decides what gets built and settles every slice’s status; see the build loop. A builder never sets a status itself.
The commands
Section titled “The commands”connect
Section titled “connect”cratis build connect --studio [<url>] --organization <name> [--name <name>] [--mcp-client-id <id>] [--force] [--no-wait]Registers the machine as a builder of an organization with a short code a maintainer approves in Studio, and waits until they do. --studio alone means the hosted Studio, https://app.cratis.studio. The builder’s credential is kept in the operating system’s credential store, never in the project. --mcp-client-id also stores the organization’s MCP credential, so an agent gets Studio’s tools. See Connect a builder and approve it.
Installs a kit into a project:
cratis build init --kit <name|git url> [--agent <agent>] [--kit-folder <path>]A value matching the kit name rule (lowercase words joined by hyphens) is a registered kit; an existing folder is a kit on disk; anything else is a Git URL (https://…, ssh://… or git@host:owner/repo.git), optionally followed by #<branch, tag or commit>. --kit-folder names the folder inside the repository that holds build-kit.yaml; without it the manifest is at the repository’s root.
-
A registered kit:
GET /api/builders/kits/{name}for the manifest, thenGET /api/builders/kits/{name}/archive, refused unless the SHA-256 of the body equalsX-Checksum-Sha256. A kit from Git: a shallow clone of the ref into a temporary folder outside the project, then the kit is validated; a kit with problems stopsinitwith every problem shown and nothing copied. The CLI validates with the manifest schema and the checks listed under Validating a kit, the same checks Studio runs. -
Every command in
requiresis checked for and its version compared; a missing or too old command stopsinit. -
In an empty project with
scaffold, the scaffold is copied and itscommandsrun in the project, in order; any non-zero exit stopsinit. In a project that is not empty, the scaffold is not copied: the kit needsexistingCodebase, otherwiseinitstops. WithexistingCodebase, thelearnprompt runs once (oninitor the first build) and the conventions are kept at the kit’sconventionspath. -
The
instructionsandskillsare installed where the chosen agent reads them:--agentInstructions Skills claudeCLAUDE.md.claude/skills/<skill>/geminiGEMINI.md.agents/skills/<skill>/codex,cursor,copilot,opencode(the default)AGENTS.md.agents/skills/<skill>/The kit’s instructions are written between the lines
<!-- cratis-build-kit:<name> -->and<!-- /cratis-build-kit:<name> -->, followed by one line per skill naming itsSKILL.mdand itsdescription. A file that already exists keeps everything outside that block; runninginitagain replaces only the block. This is the only guidance a kit leaves in the project, and only because the kit asks for it; the Screenplay guidance never is (see Agent sessions). -
The kit is recorded in
.cratis/build/kit.json:name,version,sha256of the archive (orsourcewith the Git URL and the resolved commit),agent, andfiles, every project pathinitwrote.run,onceandservice installread the kit and the agent from this file. A kit is optional: without one, name the agent with--agentor the generator with--exec.
cratis build run [--agent <agent> | --exec <command>] [--agent-command <command>] [--kit <path>] [--project <path>] [--verify <command>]... [--once] [--no-push] [--no-guidance]Connects, tells Studio what it can build, asks for work, and for every slice it is given:
- switches to the branch Studio names for a Studio-managed build, or to the kit’s
git.branchotherwise, and writes the order to a folder outside the project, with the order’s Screenplay documents in amodelfolder beside it; - hands the order to the agent, as described in Agent sessions, with the kit’s filled prompt, or runs the
--execcommand (see The generator contract); it renews the lease while the work goes on, and stops without reporting anything when Studio says the lease is lost; - answers the agent’s permission requests from the kit’s
permissions, refusing everything else, and never starts an agent with its permission checks switched off; - on
builtornothingToDo, runs everyverifycommand of the kit and each--verify, in order, in the project; any non-zero exit makes the outcomefailedand retryable, neverbuilt; - on
built, commits the files the outcome lists (or every changed file when it lists none) that the kit permits, with Studio’s commit message for a Studio-managed build or the kit’sgit.commitotherwise, pushes the branch with your own Git credentials unless--no-pushis given, and adds the commit and branch to the outcome; - reports the outcome, keeping only what the build contract declares for its kind;
- puts anything left uncommitted away in a Git stash named after the order, never discarding it, and switches back to the branch it started on.
The project must be a Git repository without uncommitted changes. --once stops after one slice, and Ctrl+C stops the loop.
What the builder tells Studio it can build comes from the kit: its name, its slice types (all of them without a kit), whether it builds user interfaces (ui), and the contract versions it shares with the CLI. Without a kit, the builder builds backends of every slice type. The CLI reads version 1 of build orders and outcomes, so it does not send progress reports, and Studio lists a deleted slice in the next build of its feature instead of sending it a removal order.
With --modeling, the agent models on a board instead of building slices; see Live modeling with your own agent.
An agent that stops without writing its outcome, as some do when one of their actions is refused, is asked to go on up to twice before the build fails. Local tools such as Screenplay’s are handed to an agent that only connects to MCP servers over HTTP, such as Copilot CLI, on a loopback address with a token of the session’s own.
Credentials go to the agent session and the Git process, never into a prompt, an order, an outcome or a log.
cratis build once --order <file> [--agent <agent> | --exec <command>] [--outcome <file>] [--verify <command>]... [--push]Builds one order from a file without connecting to Studio: steps 1 to 5 and 7 of run, without pushing unless --push is given. The outcome is written to the standard output, or to --outcome. It exits with 5 when the outcome is failed, so it fits in a CI job. Use it to try a generator, an agent or a kit.
status
Section titled “status”Shows the Studio and the organization the machine is registered with, whether the builder credential and Studio’s MCP credential are stored, and the kit and agent of the current folder. It changes nothing.
service
Section titled “service”Runs the build loop of a project as a user service that starts at sign-in and restarts when it stops, so a machine stays a builder without a terminal open: a launchd agent on macOS and a systemd user unit on Linux. Windows has no supported service manager; run cratis build run there.
cratis build service install --agent claudecratis build service install --exec "$HOME/slice-sheets/generate.sh"cratis build service statuscratis build service uninstallinstall takes the options of run and needs a machine registered with connect, and a kit, --agent or --exec. The service gets the PATH of the shell that installed it and no credentials; the builder token stays in the credential store. Each project gets its own service.
Build kits
Section titled “Build kits”A build kit describes a stack to a builder host such as cratis build: how a new project is created, what the coding agent is told, how one slice is built and verified, and how the work lands in Git. A kit holds no loop, connection or retry code. The host does all of that the same way for every kit, and the build loop in Studio decides what gets built.
my-kit/├── build-kit.yaml # the manifest├── AGENTS.md # stack instructions├── build-slice.md # the prompt for one build order├── learn-conventions.md # optional: learning an existing codebase├── skills/ # optional: one folder per skill, each with a SKILL.md└── scaffold/ # optional: the files of a new projectThe manifest
Section titled “The manifest”The manifest is build-kit.yaml (or the same document as build-kit.json) at the root of the kit. It is described by a JSON Schema that Studio publishes at a stable address and never changes once released:
| Document | Address |
|---|---|
| Build kit manifest, version 1 | /api/builders/kits/schema/1/build-kit.schema.json |
kitVersion: "1"name: cratis-csharpversion: 1.0.0description: Event-sourced .NET applications on Cratis Arc and Chronicle.contract: versions: ["1"]screenplay: schemaVersions: ">=38"sliceTypes: [stateChange, stateView, automation, translation]ui: truescaffold: path: ./scaffold commands: - dotnet restore CratisApp.slnxinstructions: ./AGENTS.mdskills: ./skillsprompt: ./build-slice.mdverify: - dotnet build $(ls *.slnx *.sln 2>/dev/null | head -n 1) -warnaserror - dotnet test $(ls *.slnx *.sln 2>/dev/null | head -n 1) --no-build --filter "FullyQualifiedName~{slice}" -- RunConfiguration.TreatNoTestsAsError=truegit: branch: "studio/{feature}" commit: "Build {slice}"permissions: paths: ["**"] commands: [dotnet build, dotnet test, git status]existingCodebase: learn: ./learn-conventions.md conventions: .cratis/build/conventions.mdrequires: - command: dotnet version: ">=11"| Member | Required | Meaning |
|---|---|---|
kitVersion |
yes | The manifest format version, the string "1". |
name |
yes | Lowercase words joined by hyphens, at most 64 characters. Registered kits are installed by it. |
version |
yes | The kit’s own semantic version. |
description |
yes | One sentence on the stack. |
contract.versions |
no | The build order and outcome versions the prompt is written for. Defaults to ["1"]. |
screenplay.schemaVersions |
no | The compiled Screenplay schema versions the kit understands: ">=38", "=40" or ">=38 <50". |
sliceTypes |
yes | One or more of stateChange, stateView, automation, translation. A host takes no order for another type. |
ui |
no | Whether the kit also builds the ui part of an order. Defaults to false. |
scaffold |
no | A kit folder copied into a new project, as ./scaffold or { path, commands }. commands run in the new project afterwards. |
instructions |
yes | The stack instructions, a Markdown file, installed in the form the chosen agent reads. |
skills |
no | A folder holding one folder per skill, each with a SKILL.md. |
prompt |
yes | The prompt template for one build order. |
verify |
yes | Commands the host runs, in order, after the agent is done. A slice is reported built only when every one exits with 0. |
git.branch, git.commit |
no | Templates for the branch to build on and the commit message. |
permissions.paths |
no | Globs, relative to the project, the agent may write. Defaults to everything in the project. |
permissions.commands |
no | Command prefixes the agent may run. The verify commands are always allowed. Everything else is refused. |
existingCodebase |
no | How the kit builds into a project it did not scaffold; see below. |
requires |
no | Commands the host checks for, each with an optional minimum version such as ">=10". |
Every path inside the kit starts with ./ and never leaves the kit; every path inside the project is relative and never leaves it. A manifest member the format does not declare is refused, so a manifest never carries a token or a secret.
Placeholders
Section titled “Placeholders”The prompt, the learn prompt, the verify commands and the Git templates may use these placeholders. The host fills them from the build order. In a verify command, a value with spaces or shell characters is quoted. permissions.commands are not filled: a permitted command is a prefix, so permit node tools/generate.mts and have the prompt run it with {order} after it, as Deterministic with AI on top does. Any other name in single braces refuses the kit; double braces and braces with spaces, as in JSON or code, are left alone.
| Placeholder | Filled with |
|---|---|
{order} |
The path of the build order document the host wrote for this build |
{outcome} |
The path the agent writes its outcome document to |
{slice} |
The name of the first target slice, as written in the model |
{slices} |
The names of every target slice, separated by commas |
{sliceId} |
The identifier of the first target slice |
{feature} |
The name of the feature the slices belong to |
{featurePath} |
The modules and parent features down to the feature, joined with / |
{application} |
The name of the application |
{part} |
backend or ui |
{attempt} |
The attempt number, starting at 1 |
{conventions} |
The project path of the recorded conventions, or empty when the kit records none |
What the agent does, and what the host does
Section titled “What the agent does, and what the host does”The agent only writes code and an outcome. The host does everything else, so a kit cannot get it wrong:
- The host writes the build order to
{order}and starts the agent with the instructions, the skills, the Screenplay guidance and the tools for the session (see Agent sessions), and the filled prompt. - The agent writes code and then an outcome document to
{outcome}:builtwith its files, specification results and assumptions;blockedwith a reason and questions; ornothingToDo. It leavescommit,branchandpullRequestout. - The host runs every
verifycommand. If one fails, the outcome isfailedwith the command and its exit code, whatever the agent wrote. - When verification passes and the outcome is
built, the host commits the agent’s files on thegit.branch, adds the commit to the outcome and reports it.
Permission requests from the agent are answered from permissions; the host never runs an agent with its permission checks switched off.
Existing codebases
Section titled “Existing codebases”A kit with existingCodebase can build into a project it did not scaffold. On the first build in such a project the host runs the learn prompt once: the agent reads the project and records its conventions at the conventions path, changing nothing else. Every later build passes that path as {conventions}, and the agent follows what was recorded. Delete the file to have the conventions learned again.
Registered kits
Section titled “Registered kits”Studio registers the reference kits by name. Each is one archive a host unpacks as is.
| Kit | Stack | Slice types | User interfaces |
|---|---|---|---|
cratis-csharp |
.NET on Cratis Arc and Chronicle, React on Cratis Components | all four | yes |
axon |
Java on Axon Framework, rendered by the Axon Stage renderer, JUnit | all four | no |
node |
Node.js in TypeScript on the Cratis Chronicle client, Vitest | state change, state view | no |
These addresses need no sign-in; kits hold no organization data and no credentials.
List the kits
Section titled “List the kits”GET /api/builders/kits200 OK, Cache-Control: no-store:
[ { "name": "cratis-csharp", "version": "1.0.0", "description": "Event-sourced .NET applications on Cratis Arc and Chronicle, with a React frontend on Cratis Components.", "sliceTypes": ["stateChange", "stateView", "automation", "translation"], "ui": true, "contractVersions": ["1"], "sha256": "9f2c…" }]Read a kit’s manifest
Section titled “Read a kit’s manifest”GET /api/builders/kits/{name}200 OK with the manifest as JSON, exactly as written in the kit, or 404 Not Found for a name Studio does not register.
Download a kit
Section titled “Download a kit”GET /api/builders/kits/{name}/archive200 OK with Content-Type: application/zip and the header X-Checksum-Sha256 holding the lowercase hex SHA-256 of the body, which also matches sha256 in the listing. Entries are paths relative to the kit’s root, such as build-kit.yaml and scaffold/Program.cs. The same kit always gives the same bytes. Verify the checksum before unpacking. 404 Not Found for an unknown name.
Installing from a Git URL
Section titled “Installing from a Git URL”A host installs a kit that is not registered from a Git URL: it clones the repository (or the folder the URL names), finds build-kit.yaml or build-kit.json at its root, and validates the kit before anything is copied into the project.
Validating a kit
Section titled “Validating a kit”A kit author, or a host installing a kit from Git, sends the kit as a zip:
POST /api/builders/kits/validateContent-Type: application/zipThe manifest may be at the root of the archive or inside one top folder, the way a Git host lays out an archive. The archive may be at most 5 MB, hold at most 2000 files and unpack to at most 20 MB, and no entry may leave the kit. The answer is always 200 OK, Cache-Control: no-store:
{ "valid": false, "problems": [ "/sliceTypes/1: Value should match one of the values specified by the enum", "/prompt: {apiToken} is not a placeholder a host fills; use one of {order}, {outcome}, …", "/skills: the skill other has no SKILL.md." ], "kit": null}Each problem starts with where it is: a JSON pointer into the manifest, or (document). A valid kit answers "valid": true, no problems and kit in the same shape as a listing entry. Validation checks the manifest against the schema, that every file and folder it names is in the kit and not empty, that every skill folder has a SKILL.md, and that every placeholder is one from the table above.
Related
Section titled “Related”- Connect a builder and approve it
- Build a builder: three ways to build, with a coding agent, a generator of your own, or both
- Build with AI: write a build kit of your own, line by line
- The
cratis buildreference in the CLI documentation - Talk to Studio directly, when you cannot run the CLI
- The build loop
- The builder protocol
- Live modeling with your own agent