Official command line client for Judoscale. Built for humans, CI and AI agents: JSON output by default, a single static binary.
With Homebrew:
brew install judoscale/tap/judoOr with the install script:
curl -fsSL https://raw.githubusercontent.com/judoscale/judoscale-cli/main/install.sh | shThe script installs the latest release for macOS or Linux (amd64 or arm64), verifies its checksum, and puts judo (plus a judoscale alias) in /usr/local/bin, or ~/.local/bin when that isn't writable. Set JUDO_VERSION to pin a version and JUDO_INSTALL_DIR to choose the directory.
Windows binaries are on the releases page.
From source (Go required):
go build -o judo ./cmd/judoRun judo auth logout to remove the saved token, then remove the CLI. With Homebrew:
brew uninstall judoIf you used the install script, delete the binary and the alias:
rm "$(command -v judo)" "$(command -v judoscale)"The CLI keeps its other data, such as the cached API spec, in ~/.config/judoscale/; delete that directory to remove everything.
Create an API token in your Judoscale team settings and log in with it:
judo auth loginThe token is checked against the API and saved to ~/.config/judoscale/credentials, readable only by you. In CI and scripts, set JUDO_API_TOKEN instead (or pipe the token in with judo auth login --with-token). The environment variable takes precedence over the saved token.
judo auth status shows where the token comes from and which team it belongs to, and judo auth logout removes the saved one.
judo help # list resources
judo apps # list the commands for apps
judo apps list
judo processes list 123
judo metrics get-series 456 queue_time --from 2026-01-01T00:00:00Z --to 2026-01-02T00:00:00Z
judo scale-events list 456 --all # follow next_cursor, merge all pages
judo processes update 456 --max_scale 10 --autoscaling_enabled
judo processes update 456 --queue_names '["default","mailers"]'
judo api-tokens create --data '{"label":"ci","read_only":true}'
judo api GET /v1/team # raw request
judo update # refresh the API specCommands are built from the Judoscale API's OpenAPI spec. They are grouped by resource: run judo help to list the resources, judo <resource> to list its commands, and judo <resource> <command> --help for details.
Request body fields are flags. Boolean flags are set with --name or --name=false, and array or object fields take a JSON value. Pass -d/--data to send a whole JSON body instead (--data - reads it from stdin).
Destructive commands, like judo apps delete 123, refuse to run without --yes. judo api never asks.
Add --dry-run to preview any command, including judo api. It prints the method, URL, headers (with the token masked) and the JSON body.
When the API rate-limits a request, the CLI waits as long as the API asks and retries, up to three times.
Agents can use judo as is: output is JSON, errors go to stderr with a non-zero exit code, and judo <resource> <command> --help lists every flag. Give an agent its own token, and make it read-only unless it needs to change things (a member token also can't use admin-only actions):
judo api-tokens create --label agent --role member --read_onlyCreating a token needs an admin token, and the plain token is only shown once.
To point an agent at the CLI, add something like this to its instructions (AGENTS.md, CLAUDE.md):
## Judoscale
Use the `judo` CLI for the Judoscale API. Output is JSON.
- `judo help` lists resources, and `judo <resource> <command> --help` shows a command's flags.
- Preview a change with `--dry-run` first. Deletes need `--yes`.
- Use `--all` on list commands to follow pagination.| Variable | Description |
|---|---|
JUDO_API_TOKEN |
API token, overrides the one from judo auth login |
JUDO_NO_UPDATE_CHECK |
Set to turn off the daily update check |
The binary embeds a snapshot of the spec. judo update downloads the latest spec from the Judoscale API to ~/.config/judoscale/openapi.json (or $XDG_CONFIG_HOME/judoscale/, %AppData%\judoscale\ on Windows), and that copy overrides the snapshot. The CLI never updates it on its own. If the latest spec needs a newer CLI, judo update asks you to upgrade instead.
On a terminal, the CLI checks once a day whether a newer release or API spec exists and prints a one-line notice. It never updates itself: run judo update for the spec, and upgrade the CLI the way you installed it: brew upgrade judo for Homebrew, or run the install script again. It stays quiet in CI (CI set), for judo api, and when piped, and JUDO_NO_UPDATE_CHECK turns it off.
0 success, 1 API or runtime error (details on stderr), 2 usage error.
script/test # go vet + go test
script/buildThe embedded snapshot lives in internal/spec/openapi.json, with its ETag alongside it in openapi.etag. Refresh both with script/update-spec [base-url] (production by default; requires jq), which downloads the spec through judo update, drops examples and points servers at production. Run script/build afterwards to embed it. A daily workflow also runs script/update-spec and opens a PR when the spec changes.
Use conventional commit messages and squash-merge PRs. release-please keeps a release PR open with the next version and changelog; merging it tags the release, attaches the binaries built by GoReleaser, and updates the Homebrew formula in judoscale/homebrew-tap.