CLI

The Judgment CLI is a command-line client for the Judgment API. Most commands are auto-generated from the API's OpenAPI spec, so the CLI surface always tracks the latest server changes.

For the full command and flag reference, see the CLI reference.

Install

curl -fsSL https://judgmentlabs.ai/install.sh | bash

Pin a specific version:

curl -fsSL https://github.com/JudgmentLabs/cli/releases/download/v0.1.0/install.sh | bash

The installer creates an isolated venv at ~/.local/share/judgment-cli/venv and symlinks judgment into ~/.local/bin. Override locations with INSTALL_DIR=... and PREFIX=.... Requires Python ≥ 3.9 — set PYTHON=... to pick a specific interpreter. Set NO_COMPLETIONS=1 to skip wiring up shell completions.

brew install JudgmentLabs/tap/judgment-cli

brew upgrade judgment-cli picks up new releases automatically. Formula source: JudgmentLabs/homebrew-tap.

The formula installs the zsh completion script in $(brew --prefix)/share/zsh/site-functions/. zsh picks it up once you've followed Homebrew's one-time shell-completion setup.

Authenticate

Log in

judgment login
# API key: ****
# Organization ID (leave blank to skip): org-...

Credentials are written atomically with 0600 permissions to a platform-appropriate config dir resolved via platformdirs:

OS	Path
macOS	`~/Library/Application Support/judgment/credentials.json`
Linux	`$XDG_CONFIG_HOME/judgment/credentials.json` (default `~/.config/...`)
Windows	`%APPDATA%\JudgmentLabs\judgment\credentials.json`

Use judgment configure to update stored credentials interactively, judgment status to see which sources are resolved, and judgment logout to delete the credentials file.

Other credential sources

Priority	Method	Variables / Path
1	Env vars	`JUDGMENT_API_KEY`, `JUDGMENT_ORG_ID`, `JUDGMENT_BASE_URL`
2	Config file	Written by `judgment login`

Environment variables always win over the config file.

Shell completion

The curl installer wires up completions automatically (zsh, bash, fish). To install completions manually:

# bash (~/.bashrc, or ~/.bash_profile on macOS)
eval "$(judgment completion bash)"

# zsh (~/.zshrc)
autoload -Uz compinit && compinit
eval "$(judgment completion zsh)"

# fish (~/.config/fish/completions/judgment.fish — auto-loaded)
judgment completion fish > ~/.config/fish/completions/judgment.fish

Quickstart

Run judgment --help for the full command list, and judgment <group> <command> --help for the flags on a specific command. JSON-shaped flags (filters, pagination, conditions, actions) accept inline JSON strings.

# Projects
judgment projects list
judgment projects create "My Project"

# Traces
judgment traces search    <PROJECT_ID> --pagination '{"limit":25,"cursorSortValue":null,"cursorItemId":null}'
judgment traces get       <PROJECT_ID> <TRACE_ID>
judgment traces spans     <PROJECT_ID> <TRACE_ID>
judgment traces add-tags  <PROJECT_ID> <TRACE_ID> --tags reviewed --tags urgent
judgment traces evaluate  <PROJECT_ID> --trace-ids <TRACE_ID>

# Sessions
judgment sessions search          <PROJECT_ID> --pagination '{"limit":25,"cursorSortValue":null,"cursorItemId":null}'
judgment sessions get             <PROJECT_ID> <SESSION_ID>
judgment sessions trace-behaviors <PROJECT_ID> <SESSION_ID>

# Behaviors / judges / automations
judgment behaviors list   <PROJECT_ID>
judgment judges list      <PROJECT_ID>
judgment judges upload    ./my_judge.py --project-id <PROJECT_ID>
judgment automations list <PROJECT_ID>

# Docs
judgment docs search   "how do I instrument my app"
judgment docs get-page /docs/getting-started

For the per-group, per-command, per-flag reference — including the JSON shapes accepted by complex flags like --conditions, --actions, --filters, and --span-triggers — see the CLI reference.

Development

The CLI source lives at JudgmentLabs/cli. Most command implementations are regenerated from the API's OpenAPI spec:

uv sync --extra dev
uv run python scripts/generate_cli.py

generate_cli.py rewrites src/judgment_cli/generated_commands.py from the OpenAPI spec. Pass --spec <url-or-file> to point at a different spec.

CLI