Skip to content

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.

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.

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.

cratis build run is one loop. For every slice Studio hands it, the CLI:

  1. Connects to Studio with the machine’s builder token and tells Studio what it can build.
  2. Asks for work and receives a build order: the slices to build, their Screenplay model and their specifications.
  3. 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.
  4. Hands the order to your program, in a folder outside the project.
  5. Verifies the result with the kit’s verification commands and every --verify command, such as dotnet test or npm test.
  6. Commits the files your program reported, on the branch Studio names.
  7. Pushes with your own Git credentials.
  8. Reports the outcome to Studio, with the commit and the branch.
  9. 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.

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.

Terminal window
cratis build connect --studio --organization acme # once per machine; a maintainer approves it in Studio
cratis 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.