Build slices for Cratis Studio with the Cratis CLI
A builder turns the slices of a Cratis Studio event model into code. Studio decides which slices are ready, who builds them, how often a failed slice is retried and what each slice’s status is. A builder only builds: it takes a slice, writes the code and says how it went.
You do not have to write a builder from scratch. A builder is cratis build plus a program of your own. The CLI does everything that involves Studio and Git; your program only turns a build order into code.
Run the builder Studio runs
Section titled “Run the builder Studio runs”You do not have to bring a program. The packaged Cratis builder is what Studio runs in the cloud, on your machine or in Docker: cratis build run --level screenplay, code, code-ai or ai, the same four modes Studio offers, for the Cratis or the Axon target. It can send its model calls through Studio, so usage is counted and pooled there.
Three ways to build
Section titled “Three ways to build”| Way | Your program | Choose it when |
|---|---|---|
| Build with AI | A coding agent, kept to a build kit’s files, commands and checks | You want the most code for the least effort, on any stack. Not sure? Start here |
| Write a generator | A deterministic program in any language | The code follows rules you can write down, and must come out the same every time |
| Deterministic with AI on top | A generator writes the structure, an agent fills in the marked places | You want your structure on every slice and the agent’s effort only where judgment is needed |
In all three, the CLI verifies, commits and reports, and the same build kit can describe the stack.
What the CLI does for you
Section titled “What the CLI does for you”cratis build run is one loop. For every slice Studio hands it, the CLI:
- Connects to Studio with the machine’s builder token and tells Studio what it can build.
- Asks for work and receives a build order: the slices to build, their Screenplay model and their specifications.
- Holds the lease. It renews the lease on the slice every third of the lease time while the build runs. If Studio says the lease is lost, the build stops and nothing is reported.
- Hands the order to your program, in a folder outside the project.
- Verifies the result with the kit’s verification commands and every
--verifycommand, such asdotnet testornpm test. - Commits the files your program reported, on the branch Studio names.
- Pushes with your own Git credentials.
- Reports the outcome to Studio, with the commit and the branch.
- Cleans up. Anything left uncommitted goes into a Git stash named after the order, and the repository goes back to the branch it was on.
Your program does not talk to Studio, run Git or hold a credential.
Generators and agents
Section titled “Generators and agents”Your program is one of two kinds:
| A generator | A coding agent | |
|---|---|---|
| Option | --exec "<command>" |
--agent <name> |
| What it is | Any command the shell can start: a Bash script, a Node.js, Python or Go program, a .NET app, a code generator you already have | Claude Code, Codex, Gemini CLI, GitHub Copilot CLI, OpenCode, or any agent that speaks the Agent Client Protocol |
| What it gets | The build order as a JSON file | A prompt filled from the order, the Screenplay guidance, the kit’s instructions and skills, and tools |
| What it gives back | An outcome as a JSON file | An outcome as a JSON file |
A generator is deterministic and needs no SDK, no Cratis package and no network access. It reads one JSON file and writes another, so it can be written in any language. See Write a generator.
A coding agent runs with its own sign-in and its permission checks on. See Build with AI and Agents and build kits. To combine the two, see Deterministic with AI on top.
Try it
Section titled “Try it”cratis build connect --studio --organization acme # once per machine; a maintainer approves it in Studiocratis build run --exec "$HOME/slice-sheets/generate.sh" --verify "test -d slices"Run the second command in a clean clone of the application’s repository. Connect and run a builder walks through it.
In this section
Section titled “In this section”- Run the Cratis builder locally: the builder Studio runs, from Screenplay only through static code and code refined by AI to AI only, in Docker, with model calls through Studio.
- Connect and run a builder: register a machine, have it approved, and run the loop in a terminal or as a service.
- Build with AI: a coding agent builds the slices, with a complete sample kit.
- Write a generator: build deterministically. The contract between the CLI and your program, with the same generator in Bash, TypeScript and C#.
- Deterministic with AI on top: a generator writes the structure and an agent completes it, with a complete sample kit.
- Agents and build kits: the agents, and the build kit reference.
cratis buildreference: every command and option.
In the Studio documentation
Section titled “In the Studio documentation”- Builders: how builders fit into Studio, and the builder protocol for those who want to talk to Studio without the CLI.
- Build a builder: the three ways to build, compared in depth.
- Connect a builder and approve it: the approval, step by step, in Studio.
- Choose who builds: pick the builder for an application or a slice.
- Follow a build and troubleshoot: what Studio shows while a slice is built.
- Build orders and outcomes: every field of the order your program reads and the outcome it writes.