CLI
Sign in from a developer machine, upload agent session facts and report deploys.
Last updated
The waltz CLI connects developer machines and pipelines to your org. On a developer machine it records AI coding agent sessions through the harness hooks and uploads their facts; in a pipeline it reports deploys.
Install
Put the waltz binary on your PATH, then check it:
waltz version
Run waltz <command> -h for any command's flags.
Sign in
waltz login
- The CLI prints a link and a code (
BCDF-GHJK), and opens the link in your browser. The code expires in 15 minutes. - Sign in to the console if asked, check the code, choose the org and approve. Viewers can't connect a CLI.
- Return to the terminal. The CLI says which org and address it signed in as.
| Flag | Does |
|---|---|
-name |
What to call this machine's token (default waltz on <hostname>) |
-no-browser |
Print the link only |
-api-url |
The Waltz API (default $WALTZ_API_URL, else https://api.waltz.run) |
The token is stored in the macOS Keychain, or elsewhere in a credentials.json readable only by you. It is never written to a repository or a config.toml.
A CLI token belongs to one org and acts as the member who approved it. It can only upload sessions and read itself. It stops working when it is revoked, or when its member leaves the org, is made a viewer or is suspended.
waltz whoami # org, address, token name, whether automatic upload is on
waltz whoami -json
waltz logout # revokes the token and forgets it
Members revoke their own tokens, and admins any of the org's, under Settings → CLI.
Upload sessions
waltz sessions upload -id <session>
waltz sessions upload -all
| Flag | Does |
|---|---|
-id |
Upload one finished session |
-all |
Upload every finished session not uploaded yet |
-repo |
The repository directory (default: the current one) |
-dry-run |
Print the facts that would be sent, one per line, and send nothing |
-json |
Print results as JSON |
What is sent is facts only: the agent, model and product, start, end and duration, turn and commit counts, and which commits the session made. Never prompts, the agent's answers, paths or code. Uploading a session again changes nothing.
Automatic upload. When an admin turns it on under Settings → CLI, each session uploads when it ends on any signed-in machine. WALTZ_NO_UPLOAD=1 turns it off for one machine. The Claude Code recipe wires the hooks that record sessions.
Report deploys
waltz deploy tells Waltz a service was deployed or rolled back, so Briefs can count releases, failures and lead time.
waltz deploy -service api -env production -sha "$SHA" -status succeeded -url "$RUN_URL"
| Flag | Does |
|---|---|
-service, -env |
The service and environment (required) |
-sha |
The commit deployed; enables lead time |
-status |
succeeded (default), failed, canceled or timeout |
-kind |
deploy (default) or rollback |
-repo |
The repository, owner/name |
-version |
The version or tag deployed |
-url |
A link to the pipeline run, cited as evidence |
-started |
When the deploy started (RFC 3339) |
The command reads a push token from WALTZ_DEPLOY_TOKEN only, never from a flag. Connect the deploy integration in the console, make a push token there and keep it in your CI secret store. WALTZ_INGEST_URL overrides the endpoint (default https://ingest.waltz.run).
Local tools
The CLI also builds reports and Briefs on your own machine from a local checkout (waltz init, waltz doctor, waltz brief). They need no sign-in and send nothing to Waltz.