Commands reference

Quatern has shell commands (quatern <command>) and an interactive session (the REPL) with slash commands. Every slash command runs the matching shell command, so the two give the same results.

Conventions

• --robot takes a robot name (c101, or c101.lab2 for the instance lab2) or a path to a .quatern.json file.
• --json prints machine-readable output. Every command takes it except login and agent.
• --yes answers a confirmation for you. Commands that would ask a question fail without a terminal unless you pass it. On hardware, motion questions in quatern hardware can't be answered by a flag.
• Exit codes: 0 success; 1 a negative result (doctor found a failure, verification was NOT READY, a deploy was refused or didn't complete); 2 a usage error or an error: message; 130 cancelled with Ctrl+C.

Global options

usage: quatern [-h] [--no-repl] [--verbose] command ...

Option	Meaning
--no-repl	With no command, print the help instead of opening the REPL.
--verbose	Also list keys missing from config.json and the defaults used. Can go anywhere on the line.

If the first word isn't a command, Quatern sends the whole line to the agent: quatern "verify a planner for c101".

Shell commands

quatern

Opens the REPL. The first time, it offers to sign you in and, if no robot is set up, a 2-minute tour in the simulator (see Quickstart). With no terminal (piped input or output), it prints the help instead.

quatern init

Sets up a robot from the catalog, your own URDF, or a wizard. Writes <name>.urdf and <name>.quatern.json. See Set up your robot.

quatern init --robot c101
quatern init --urdf ./robot.urdf --name mybot --backend ros2
quatern init --wizard

Flag	Meaning
--list	List the catalog.
--robot NAME	Copy a catalog robot: c101, jetson_rover, sim_arm, sim_diffbot, turtlebot3_burger, turtlebot3_waffle, turtlebot4, ur5e.
--urdf PATH	Use your own URDF as it is.
--wizard	Answer a few questions; Quatern writes the URDF.
--name NAME	Robot name. Required with --wizard.
--instance ID	Instance id (default default).
--dir DIR	Where to write (default ~/.quatern/robots).
--force	Overwrite existing files.
--backend {mock,sim2d,ros2}	Backend for the primary target. ros2 also adds a hardware target.
--no-sample	With --robot: don't import the bundled sample recording.
--yes	Accept every default without asking.

With --urdf: --cross-check (comma-separated sensors that estimate the robot's pose), --odometry {yes,no}, --encoders {yes,no}, --mobile-base LINK|no. With --wizard: --kind {wheeled,arm}, --sensors (from odometry, camera, pointcloud, laserscan, imu), --wheels, --wheel-diameter, --track-width, --wheelbase, --joints, --gripper {yes,no}, --mass. Measurements left out are marked TODO(measure).

quatern quickstart

Takes a catalog robot through the whole loop in the simulator: robot → world → recording → calibration → generate → verify → deploy, ending in a receipt. Never uses a hardware target.

quatern quickstart --robot turtlebot3_burger

Flag	Default	Meaning
--robot NAME	asks	A catalog robot (installed if needed) or an installed robot. Required without a terminal.
--world W	the robot's current world, usually room	hallway, room or warehouse_aisle. Choosing one sets it as the robot's sim world.
--goal G	the robot's catalog goal	Goal to plan to.
--seconds S	120	Simulated length of the recorded drive.
--realtime	off (5× faster)	Run the simulated deploy in real time.
--no-agent		Use the reference modules even when signed in.
--agent-rounds N	2	Cap on the agent's verification rounds.
--yes		Answer every question with its default and pass the sim gate.

Exits 0 only when the run ends COMPLETED.

quatern doctor

Checks the description, config, backend and sensor streams, calibration, sandbox, toolchains, stop-on-silence and the agent sign-in, and says how to fix each problem.

quatern doctor --robot c101
quatern doctor --robot c101 --target hardware --check-silence

Flag	Default	Meaning
--robot	required	Robot name or config path.
--target T	the config's default	Target to check.
--probe-seconds S	2.0	How long to watch the sensor streams.
--check-silence		Also verify stop-on-silence. The robot moves briefly.
--yes		Confirm the silence check without asking.

Exits 1 if any check fails.

quatern calibrate

Sweeps every actuated joint and reports how it tracks commands (R², tracking error, lag). The robot moves; you confirm first.

quatern calibrate --robot c101

Flag	Default	Meaning
--trials N	5	Sweeps to average per joint (1–20).
--yes		Skip the confirmation.

A calibration stays valid for 1 hour. Exits 0 only if it's VALID.

quatern capture

Records a sensor session. Quatern never commands motion during a capture: you drive the robot.

quatern capture --robot c101 --seconds 60 --label hallway

Flag	Default	Meaning
--seconds S	30	Length, 1–300.
--label L	unlabeled	Scenario label; becomes part of the capture id.
--notes TEXT		Free-text context for a human reader.
--yes		Start immediately, no countdown.

quatern verify

Runs offline verification against a recording and prints a plain-English report. Saves the result as a stack. See How verification works.

quatern verify --robot c101 --goal "Navigate around the island to reach (1.2, 2.0)"
quatern verify --robot c101 --goal "reach (2, 1)" --module ./my_localizer

Flag	Meaning
--goal G	Required. What to plan to, for example 'reach (3, 3)'.
--label L	Scenario label of the recording to reuse or record.
--no-reuse	Record a fresh capture instead of reusing one.
--module DIR	Verify your own module (a directory with module.toml and sources, any language) instead of generated code.

Needs no network. Exits 0 for READY, 1 for NOT READY.

quatern stacks, pin, unpin

quatern stacks --robot c101                    # list verified stacks; * marks the pinned one
quatern pin stk_c101.default_20261002T033736628654
quatern unpin --robot c101

• stacks --all-instances lists every instance of the robot type.
• pin marks a READY stack as last-known-good for its robot type. It refuses a stack that isn't READY.
• unpin removes the mark.

quatern deploy

Opens the deploy gate for the pinned stack. After you confirm, it runs the stack on the target behind the watchdog and prints a receipt. The robot moves. See Safety.

quatern deploy --robot c101
quatern deploy --robot c101 --target hardware --estop --max-seconds 30

Flag	Default	Meaning
--stack ID	the pinned stack	Stack to deploy.
--target T	the config's default	Where to deploy.
--yes		Answer the gate with yes.
--estop		Declare a physical e-stop in reach (recorded; never required).
--max-seconds S		End the run after this long.

Exits 0 only when the run ends COMPLETED. A refusal or a declined gate exits 1.

quatern hardware

A guided path from the simulator to the real robot: connect → sensors → capture → calibrate → verify → deploy. You confirm every motion at the terminal. A failed step prints the most likely fix and how to resume.

quatern hardware --robot turtlebot4 --goal "reach (2, 1)"
quatern hardware --robot turtlebot4 --from calibrate

Flag	Default	Meaning
--target T	the config's first hardware target	Hardware target.
--from STEP	connect	Resume at this step.
--goal G		Goal in your space, for verify and deploy.
--seconds S	60	Length of the guided recording.

quatern stats

Time from install to your first verified run, plus per-step timings of recent quickstarts. Kept on this computer only.

quatern stats --runs 10

--runs N (default 5) sets how many quickstart runs to show.

quatern login

Sign in with GitHub for Quatern's hosted agent, or store your own Anthropic key. See Accounts and usage.

quatern login
quatern login --github --no-browser
quatern login --anthropic-key

Flag	Meaning
--github	Sign in with GitHub without asking.
--anthropic-key	Paste your own Anthropic API key instead.
--no-browser	Print the sign-in address without opening a browser.

quatern logout

Forgets the stored sign-in or key.

$ quatern logout
signed out: removed the Quatern sign-in at ~/.quatern/credentials

If ANTHROPIC_API_KEY is still set, it tells you the agent keeps working until you unset it.

quatern whoami

Shows how the agent is connected, which model it uses, and on a Quatern account, how many tokens are left this month.

$ quatern whoami
Quatern account as octocat via https://api.quatern.co (token from ~/.quatern/credentials)
model: claude-sonnet-5-5 (default for Quatern accounts)
312,400 of 400,000 tokens left this month (resets November 1)

Exits 1 when you're not signed in.

quatern agent

Sends one request to the agent, or opens the REPL with --interactive.

quatern agent "verify a planner for c101 that reaches (1.2, 2.0)"
quatern agent --interactive --robot c101

Flag	Default	Meaning
--interactive		Open the REPL (the same as a bare quatern).
--robot R		With --interactive: robot to start on.
--model ID	see below	Claude model id.
--max-turns N	40	Cap on the agent's turns.
--max-tokens N	64000	Output tokens per response.
--backend {anthropic,claude-code}	anthropic	Agent backend. claude-code needs pip install "quatern[claude-code]".
--allow-builtin-tools		claude-code backend only: also expose its built-in tools.

Choosing the model. By default the agent uses Claude Sonnet 5.5 on a Quatern account and Claude Opus 5.5 with your own key. To override, in order of precedence: --model, then the QUATERN_MODEL environment variable, then runtime.agent_model in config.json. quatern whoami shows the model in use and where it came from.

Slash commands

Inside the REPL, the prompt shows the selected robot and target: quatern (c101 / sim2d:sim) >. Anything that doesn't start with / goes to the agent. Press Tab to complete commands, robot names and stack ids. Ctrl+D or /quit leaves.

Commands marked robot need a selected robot (/robot <name>).

Command	Does
/quickstart [robot] [--world W]	The simulator tour (quatern quickstart). Selects the robot when it finishes.
/robots	Robots installed here, and the catalog to install from.
/init [flags]	Set up a robot (quatern init). Selects it if it's the only one added.
/robot <name-or-config>	Select a robot. With no argument, show the current robot and its targets.
/backend <mock\|sim2d\|ros2\|target>	robot · Choose the deploy target by backend or by name. With no argument, list targets. Never picks a hardware target unless you name it.
/doctor [flags]	robot · quatern doctor for the selected robot and target.
/capture [--label L] [--duration S]	robot · Record a sensor session. --duration is the same as --seconds.
/calibrate [--trials N]	robot · Calibrate; you confirm first. The robot moves.
/verify [--goal G] [--module path]	robot · Offline verification. Without --goal, asks for one and remembers the last.
/stacks [--all-instances]	robot · List verified stacks.
/pin <stack-id>	Mark a stack last-known-good.
/unpin [stack-id]	robot · Remove the mark. With an id, only if that's the pinned stack.
/deploy [stack-id] [flags]	robot · The deploy gate, exactly as quatern deploy; you answer it. The robot moves.
/hardware [--from STEP]	robot · Guided path to the real robot; you confirm each motion.
/stats	Timings, kept locally.
/login [github\|key]	Sign in with GitHub, or store your own Anthropic key.
/help	List commands. Also /h, /?.
/quit	Leave. Also /exit, /q, Ctrl+D.

whoami, logout and agent are shell commands only. Run them as quatern whoami and so on.

Environment variables

Variable	Effect
QUATERN_DATA_DIR	Where Quatern keeps its data (default ~/.quatern).
ANTHROPIC_API_KEY	Use your own Anthropic key. Takes precedence over a stored sign-in.
QUATERN_API_KEY	A Quatern token. Takes precedence over everything else.
QUATERN_MODEL	Model override; --model beats it.
QUATERN_API_BASE	Hosted API address (default https://api.quatern.co).
QUATERN_SIM_REALTIME	1 runs the built-in simulator in real time.

Files

Everything lives in ~/.quatern (or $QUATERN_DATA_DIR):

Path	Holds
config.json	Thresholds, limits and agent settings, written with defaults on first run. Delete it to restore the defaults.
credentials	Your sign-in or key, readable by you only.
robots/	Robot descriptions and configs.
captures/, calibrations/, maps/	Recordings, calibrations (and silence checks), and maps.
stacks/	Verified stacks and the pin.
receipts/	Run records.
history, stats.json	REPL history and local timings.

Settings you're most likely to change in config.json:

Key	Default	What it does
runtime.agent_model	"auto"	Model id, or auto for the defaults above.
runtime.agent_max_turns	40	Agent turn cap.
runtime.agent_backend	"anthropic"	anthropic or claude-code.
limits.default_capture_duration_sec	30	Default capture length.
limits.calibration_max_age_sec	3600	When a calibration goes stale.
limits.estop_recommend_energy	10	Energy above which the gate recommends an e-stop.
thresholds.cross_check_defaults	planar 0.15/0.30, joints 0.08/0.20	Cross-check warn/fail bands.
thresholds.drift_warn, drift_critical	0.25, 1.00	Drift limits for verification.
thresholds.abort_deviation	base 0.5, joints 0.35	How far from the plan the watchdog allows.

An unknown key or a wrong type stops Quatern with an error naming it. A missing key uses its default; quatern doctor lists those, and other commands do with --verbose.