CLI reference

The ballot command-line tool is a thin client for Ballot’s API. Anything you can do in the dashboard, you can do here, with the same permissions.

uv tool install ballot-cli

Connection

Command	What it does
`ballot connection configure`	Saves your API URL, project and key file location, then checks them
`ballot connection show`	Shows the connected project, what your key allows and when it expires
`ballot capabilities show`	Lists what your key can do and which features are available

Simulations

Command	What it does
`ballot sim profiles list`	Lists runtime profiles, with their frameworks and supported robots
`ballot sim init --entry MODULE:FUNCTION`	Creates `ballot.toml` for a complete simulation
`ballot sim init --world REF --robot REF --task REF`	Creates a recipe from parts
`ballot sim prepare`	Uploads, builds and checks your simulation
`ballot sim inspect PREPARATION_ID --open`	Opens the preparation results, including anything that needs your input
`ballot sim preview [PREPARATION_ID] --open`	Starts a private session and returns a link for your headset
`ballot sim publish [PREPARATION_ID] --visibility unlisted`	Publishes a release
`ballot sim release rollback RELEASE_ID`	Points new joins back at an earlier release

Invites and sessions

Command	What it does
`ballot sim invites create --release RELEASE_ID`	Creates a private invite link. Options: `--max-sessions`, `--expires-in`
`ballot sim invites show INVITE_ID`	Shows an invite’s limits and whether it’s been used
`ballot sim invites revoke INVITE_ID`	Stops an invite, and any session it pays for
`ballot sim sessions show SESSION_ID`	Shows a session’s state, pilot activity and recording progress
`ballot sim stop SESSION_ID`	Ends a session and shuts its machine down

Episodes

Command	What it does
`ballot sim records list`	Lists episodes. Filters include `--release`, `--status` and `--limit`
`ballot sim records show RECORD_ID`	Shows an episode’s outcome, end reason and status
`ballot sim replay RECORD_ID --open`	Opens the replay in your browser
`ballot sim records download RECORD_ID`	Downloads the full episode

Parts

Command	What it does
`ballot package init`	Creates `ballot.toml` for a world, robot or task
`ballot package prepare`	Checks the part and uploads it
`ballot package publish --visibility project`	Makes the part available to recipes in your project
`ballot package list`	Lists parts you can use

Robots

Package a robot with its controller. Publishing uses ballot package publish.

Command	What it does
`ballot robot families list`	Lists robot types and the commands each one sends
`ballot robot init --model PATH --family TYPE`	Creates `ballot.toml` for a robot package
`ballot robot prepare`	Builds the robot and runs the checks for its type
`ballot robot preview [PREPARATION_ID] --open`	Starts a private session with the robot on its own, for your headset

Scenarios and teams

Scenarios with several seats, and invites for teams.

Command	What it does
`ballot sim init --world REF --task REF --seat NAME=ROBOT_REF`	Creates a scenario recipe. Repeat `--seat` for each robot
`ballot sim invites create --release RELEASE_ID --team`	Creates one link for a whole team. Pilots pick their seats in the lobby
`ballot sim invites create --release RELEASE_ID --seat NAME`	Creates a link that goes straight to one seat
`ballot sim records list --seat NAME`	Lists team episodes, with one seat’s tracks
`ballot sim records download RECORD_ID --seat NAME`	Downloads one seat’s tracks from a team episode

Long-running jobs

Preparation and other slow work runs as a job. Every command that starts one returns straight away with --no-wait.

Command	What it does
`ballot job show JOB_ID`	Shows progress and stage
`ballot job wait JOB_ID --timeout 60`	Waits up to the timeout, then reports where it got to
`ballot job results JOB_ID`	Shows the job’s results
`ballot job cancel JOB_ID`	Cancels the job

Global options

Option	What it does
`--format json`	Prints machine-readable JSON on stdout. Progress messages go to stderr
`--no-wait`	Returns as soon as a job has started
`--max-cost-usd AMOUNT`	Refuses to start work that could cost more than this
`--credential-file PATH`	Uses this key file for one command

Environment variables

Variable	Meaning
`BALLOT_API_URL`	Your Ballot API address
`BALLOT_PROJECT_ID`	Your project
`BALLOT_API_KEY`	Your key, for automation. Prefer a protected key file on your own machine

Scripts and agents

Every command works without prompts when you pass the options it needs. With --format json, a missing choice returns a clear error instead of waiting for input.

ballot --format json sim prepare --no-wait --max-cost-usd 2
ballot --format json job wait JOB_ID --timeout 60
ballot --format json sim publish PREPARATION_ID --visibility unlisted
ballot --format json sim records list --release RELEASE_ID --status saved --limit 20

Starting work returns an ID straight away. Waiting is always bounded: when a timeout passes, the command reports the last known state and the job carries on. Repeating a request that already succeeded doesn’t start it again.

Get started

Build

Simulators

Collect

Reference

Connection

Simulations

Invites and sessions

Episodes

Parts

Robots

Scenarios and teams

Long-running jobs

Global options

Environment variables

Scripts and agents

​Connection

​Simulations

​Invites and sessions

​Episodes

​Parts

​Robots

​Scenarios and teams

​Long-running jobs

​Global options

​Environment variables

​Scripts and agents

Connection

Simulations

Invites and sessions

Episodes

Parts

Robots

Scenarios and teams

Long-running jobs

Global options

Environment variables

Scripts and agents