Judgment CLI

Legacy documentation for the deprecated Judgment CLI

The documentation below is retained for existing CLI users.

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

Legacy installation

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
# Opens your browser to authorize the CLI.

By default, judgment login opens your browser to complete an OAuth flow. Two flags adjust this behavior:

judgment login --api-key     # prompt for an API key instead of opening the browser
judgment login --no-browser  # print the authorization URL instead of opening a browser (useful for remote shells)

OAuth access tokens are refreshed automatically when they expire, so you stay logged in without re-running judgment login.

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`, `JUDGMENT_AUTH_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 <ORGANIZATION_ID>
judgment projects create <ORGANIZATION_ID> "My Project"

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

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

# Automations
judgment automations list <ORGANIZATION_ID> <PROJECT_ID>

# Prompts
judgment prompts list     <ORGANIZATION_ID> <PROJECT_ID>
judgment prompts get      <ORGANIZATION_ID> <PROJECT_ID> <PROMPT_NAME> [--commit-id <SHA> | --tag <TAG>]
judgment prompts versions <ORGANIZATION_ID> <PROJECT_ID> <PROMPT_NAME>
judgment prompts commit   <ORGANIZATION_ID> <PROJECT_ID> <PROMPT_NAME> "<PROMPT_TEXT>" [--tags production --tags staging]
judgment prompts tag      <ORGANIZATION_ID> <PROJECT_ID> <PROMPT_NAME> <COMMIT_ID> --tags production
judgment prompts untag    <ORGANIZATION_ID> <PROJECT_ID> <PROMPT_NAME> --tags production

# 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.