Connect and run a builder with the Cratis CLI
A builder runs on any machine that can reach Studio and the application’s Git repository: your laptop, a build server or a container. This page takes one from nothing to building. Every option is in the cratis build reference.
Before you start
Section titled “Before you start”- The Cratis CLI.
- A clean clone of the application’s repository, with Git credentials that can push to it.
- A generator or a coding agent to build with. See Write a generator or Agents and build kits.
- A maintainer of the Studio organization, to approve the builder.
Connect the machine
Section titled “Connect the machine”cratis build connect --studio --organization acme--studio alone means the hosted Studio, https://app.cratis.studio. For another Studio, give its address, or the builder address Studio shows (https://<studio host>/builders/connect/<organization>), which names the organization too.
The command creates a token on this machine, registers it with the organization and prints a short code. The token is kept in the operating system’s credential store and never leaves the machine except to Studio. --name sets what maintainers see the builder as; it defaults to the machine’s name.
Have it approved
Section titled “Have it approved”connect waits until a maintainer approves the builder. In Studio, the maintainer opens Organization settings › Builders, finds the builder marked Waiting for approval, selects Approve and types the code the builder printed. The code is good for 15 minutes; after that, run cratis build connect again for a new one.
Only approve a builder you started yourself. The Studio documentation shows the approval step by step.
--no-wait returns as soon as the machine is registered. cratis build run waits for the approval itself, so you can start the loop straight away.
Run the build loop
Section titled “Run the build loop”In the clone of the repository:
cratis build run --exec "$HOME/slice-sheets/generate.sh" --verify "test -d slices"or, with a coding agent:
cratis build run --agent claude --verify "dotnet test"The loop connects, waits for slices, and builds each one Studio hands it. The repository must have no uncommitted changes, so a build commits only its own work. In Studio, choose the builder for the application or for one slice; the terminal then shows each build, its commit, and how Studio settled the slice.
| Option | What it does |
|---|---|
--verify <command> |
Runs after every build, in the project. Repeat it for several commands. A command that fails turns the outcome into failed. |
--no-push |
Commits without pushing. |
--once |
Stops after one slice. |
--project <path> |
Builds in another folder than the current one. |
Ctrl+C stops the loop, and Studio shows the builder as offline. Its slices wait for it.
Build an order offline
Section titled “Build an order offline”cratis build once builds an order from a file, without connecting to Studio. It runs the same steps as the loop (your program, verification, commit) and writes the outcome to the standard output, or to --outcome. It does not push unless you add --push.
cratis build once --order order.json --exec "$HOME/slice-sheets/generate.sh" --verify "test -d slices" --outcome outcome.jsonUse it to try a generator, an agent or a kit before connecting, and in CI. An example order is in Studio’s Build orders and outcomes.
Keep it running as a service
Section titled “Keep it running as a service”On macOS and Linux, install the loop as a user service from the clone of the repository. It starts when you sign in and restarts 30 seconds after it stops.
cratis build service install --exec "$HOME/slice-sheets/generate.sh" --verify "test -d slices"cratis build service statuscratis build service uninstallinstall takes the agent options of run (--agent, --agent-command, --exec, --kit, --project, --verify, --no-guidance) and --no-push; it does not accept --once, --board, --modeling, --name or --unattended. status says whether the service runs and where its output goes. On Windows, run cratis build run in a terminal instead. The reference has the service files, logs and lingering on Linux.
Check the setup
Section titled “Check the setup”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. It changes nothing.
Exit codes
Section titled “Exit codes”| Code | Meaning |
|---|---|
0 |
Done. For once, the outcome is not failed. |
2 |
Studio could not be reached. |
4 |
Studio no longer accepts the builder’s token. Register again with cratis build connect --force. |
5 |
The options, the kit or the order cannot be used, the repository has uncommitted changes, or the outcome of once is failed. |
The reference lists every code.
Related
Section titled “Related”- Write a generator: the program the loop runs.
- Agents and build kits: build with a coding agent, and add a kit.
- Follow a build and troubleshoot, in the Studio documentation.