Guides

The roast CLI

roast: every operation of the server from a shell, for people, scripts and agents, with tokens, approvals and exit codes.

roast uses and administers Roastwarden from a shell: for you, for scripts, and for AI agents. It is a thin client over the server's API with an API token, so it works on any machine that reaches your server. Nearly everything the dashboard does with your records has a command: roasts and their records, green coffee, orders and the shopping list, roasted coffee, the plan, profiles, labels, reports, roasters, notifications, settings and backups. What it leaves out is live control of a roaster (setpoint, heater, fan, mode, a profile drive) and PID tuning: you do those at the roaster, and roast api reaches the API for anything without a command.

An AI agent with a shell uses roast through Roastwarden's Agent Skill, which teaches it the commands, the exit codes and the rules: see Agents.

Setup

Each release on the project's releases page has roast for Linux x86_64 and aarch64 with its SHA-256 sums (roast-linux-<arch>, roast-SHA256SUMS); the server's image has it too (/usr/local/bin/roast). Use the one of the server's version: roast status shows the server's, roast --version its own.

export ROASTWARDEN_URL=https://roast.example.com        # default http://localhost:8080
export ROASTWARDEN_TOKEN=rr_…                           # Settings → Tokens
roast status

--url and --token override the environment; --json and --text choose the output (Output). roast never picks up the owner key by itself, not even inside the container where ROASTWARDEN_API_KEY is set: you pass it on purpose, docker exec roastwarden sh -c 'roast -t "$ROASTWARDEN_API_KEY" …'. Reads need a credential too (any token), unless the server runs with ROASTWARDEN_READS=open (Security); a token that is sent must be valid even for a read. The audit log is the owner's and admin tokens' only.

On a finished roast weigh and landmark work on any roaster; on one still running, a token needs Tokens may control this roaster switched on under Roasters → the roaster → Control (Control, "The real-hardware rule").

Which preset a token needs (Control, "Tokens"): read_only for every read but the audit log (admin); inventory for beans, stock and the plan (roast may change the plan too); roast for a roast's record (weights, landmarks, notes, cupping); admin for profiles, settings, imports, deletes of roasts and backups --now. A token never controls a physical roaster unless you allowed it for that roaster.

Commands

Every API operation has its way from the command line: one of these commands, or roast api when there is no command (live control, tuning and parts of roaster setup, which you do at the roaster), or none (the owner's alone, or a browser's). roast openapi --find <word> shows it per operation, with the preset each command needs.

A bean, profile or roaster is named by its id or by its name (ignoring case). A name that matches nothing is NOT_FOUND with the names there are in error.details.known; two beans with the same name are AMBIGUOUS (use the id).

Units. Temperatures are °C, weights grams. A weight argument also reads 5kg, 2500g, 2,5kg, 2lb and 12oz, and is stored in grams to 0.1 g.

Local commands run where the database is, without the server or a token: docker exec roastwarden roast backup writes the same copy as the nightly run (recorded as cli in the run history, so Settings → Backups shows it), and docker exec roastwarden roast restore <name> checks a copy from the backup folder and stages it; docker restart roastwarden then puts it in place (Running it, "Backups"). --db defaults to ROASTWARDEN_DB_PATH, which the image sets.

Approvals

A token that asks first (the default for new tokens) has some calls held for the owner: starting a roast on a physical roaster and deletes (Control, "Approvals"). roast then prints the held request ({"approval": {id, status, summary, url, …}, "message": …, "wait_url": …}) and exits 3: a human must act. With --wait (bean rm, api) it waits for the answer instead (up to --wait-timeout, default an hour) and prints the decided request: exit 0 when it was approved and done, 1 when it was denied, expired or the call failed. roast approval <id> --wait waits on one later. An agent tells the owner what it asked for and where to approve it; it never looks for another way.

Output

Lists are for finding: roasts, beans, plan, profiles and audit leave out timestamps, descriptions and the browser's user agent; the show of one item has them. Filter with the flags (--low, --roaster, --limit), not with jq.

On a terminal: short text. On a pipe (an agent, a script), or with --json: one compact JSON line, the server's own answer with every null left out (an absent key means null). --text forces text on a pipe.

Errors are one JSON document on stdout (on a pipe) or two lines on stderr (on a terminal):

{"error":{"code":"TOKEN_SCOPE","message":"…","hint":"This token's preset does not cover that; …","status":403}}

code is the API's (Control, "Errors") or roast's own: UNREACHABLE, AMBIGUOUS, BAD_RESPONSE (the server answered something this roast does not read: two different versions), NOT_READY, NO_FILE, FAILED. hint says what to do next.

Exit codes

TOO_MANY_FAILURES (429) means ten wrong keys or tokens came from this address within a minute: wait the seconds the message names and fix ROASTWARDEN_TOKEN; retrying in a loop keeps it blocked. REAL_HARDWARE is a refusal on purpose: the roaster has a heater, and only the owner allows tokens to control it (Security). An agent asks the owner; it does not look for another way. CONTROL_OFF is the same kind of answer for everyone, the owner key included: the roaster's control level does not allow the command (off logs only; manual takes heater, fan, heater on/off and STOP; Roaster kind and control level). OUTPUT_NOT_DECLARED likewise: the roaster has no such output (a logger has none). The level goes up only with the owner's yes: roaster control asks for it, and the owner approves or denies. Declared channels (Extra channels) are in the setup; roaster show lists them, and each roast keeps the list it started with (roast review reads that list).