Skip to content

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.

  • 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.
Terminal window
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.

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.

In the clone of the repository:

Terminal window
cratis build run --exec "$HOME/slice-sheets/generate.sh" --verify "test -d slices"

or, with a coding agent:

Terminal window
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.

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.

Terminal window
cratis build once --order order.json --exec "$HOME/slice-sheets/generate.sh" --verify "test -d slices" --outcome outcome.json

Use 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.

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.

Terminal window
cratis build service install --exec "$HOME/slice-sheets/generate.sh" --verify "test -d slices"
cratis build service status
cratis build service uninstall

install 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.

Terminal window
cratis build status

Shows 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.

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.