CLI

Overview

The latitude CLI is a single, self-contained binary that exposes your Latitude organization on the command line. Like the MCP server, its commands are generated directly from the Latitude API, so the command surface automatically stays in sync with the platform. For the live list of commands and their input/output schemas, check the API reference. It’s built for two audiences:

Humans, a fast, scriptable way to inspect and manage projects, traces, datasets, members, keys, and more without leaving the terminal.
Agents, a zero-dependency way for an agent (Claude Code, Cursor, Codex, …) to act on Latitude without wiring up an MCP connection, using --format json for machine-readable output and --schema for machine-readable help.

Prefer a network connection? The MCP server exposes the same capabilities over OAuth.

Installation

The CLI ships as a pre-built binary on our GitHub Releases — grab the latest cli-vX.Y.Z release. Download the archive for your platform, extract it, and put the latitude binary somewhere on your PATH.

OS	Architecture
Linux	x86-64 (`amd64`)
Linux	ARM64 (`aarch64`)
macOS	Intel (`amd64`)
macOS	Apple Silicon (`arm64`)
Windows	x86-64 (`amd64`)

MacOS / Linux
Windows

# Set <version> and pick the asset for your OS/arch: latitude-<os>-<arch>.tar.gz
curl -fsSL -o latitude.tar.gz \
  https://github.com/latitude-dev/latitude-llm/releases/download/cli-<version>/latitude-macos-arm64.tar.gz

tar -xzf latitude.tar.gz
chmod +x latitude
sudo mv latitude /usr/local/bin/latitude   # or any directory on your PATH

latitude --version

On MacOS the first run may be blocked by Gatekeeper. Allow it with xattr -d com.apple.quarantine /usr/local/bin/latitude, or via System Settings → Privacy & Security.

Download latitude-windows-amd64.zip, extract latitude.exe, and move it to a directory on your PATH (or add its folder to PATH). Then:

latitude --version

Then verify it works and, optionally, set up shell completion and the man page.

Authentication

The CLI authenticates with an organization-scoped API key. Create one in the Latitude UI under Settings → Keys → API Keys. There are two ways to give the key to the CLI:

Keyring (recommended)
Environment variable

Store the key once in your operating system’s secret store (Keychain on MacOS, Secret Service on Linux, Credential Manager on Windows):

latitude auth login --with-token

Paste your API key when prompted and press Enter. It’s saved to the keyring under latitude:ApiKeyAuth and reused on every subsequent command. Manage it with:

latitude auth status    # show which credential sources are set, for each scheme
latitude auth logout    # remove the stored key from the keyring

Need more than one key, like one for production and one for your sandbox? Use profiles.

Export the key in your shell — handy for CI or ephemeral environments:

export LATITUDE_API_KEY="lat_..."
latitude projects list

LATITUDE_API_KEY takes precedence over the keyring, so it’s easy to override the stored credential per-session. latitude auth status shows every source the CLI can see and which one wins.

The CLI also reads a .env file from the current directory, or from the nearest parent directory that has one. The LATITUDE_API_KEY you keep there for tracing authenticates the CLI too. Variables exported in your shell win over .env. Settings that change where requests go or how TLS is checked (LATITUDE_BASE_URL, the proxy and CA bundle variables, LATITUDE_INSECURE) are ignored when they come from .env, so export those from your shell instead.

Profiles

A profile is a named setup for the CLI with its own API key, stored in the keyring. With profiles you can keep several keys side by side and choose one per command, per shell, or as your default, instead of re-exporting LATITUDE_API_KEY every time you switch.

Production and sandbox

The most common use is switching between your project’s live data and its sandbox. Both use the same project slugs. The API key alone decides which one a command reads: a live key from Settings → Keys → API Keys, or a lat_sandbox_ key from Sandbox configuration inside the sandbox. Give each key its own profile:

# Production: create the profile, make it the default, then paste your live key
latitude profiles create production --use
latitude auth login --with-token -p production

# Sandbox: create the profile, then paste your lat_sandbox_ key
latitude profiles create sandbox
latitude auth login --with-token -p sandbox

Commands now run against production by default. Add -p sandbox (or --profile sandbox) to run one against the sandbox. The project slug is the same in both, so set it once:

export LATITUDE_PROJECT_SLUG=my-app

latitude traces list                                 # production traces of my-app
latitude traces list -p sandbox                      # sandbox traces of my-app
latitude traces get --trace-id <traceId> -p sandbox  # one sandbox trace

To change the default instead of passing -p each time:

latitude profiles use sandbox       # sandbox is now the default
latitude profiles use production    # and back
export LATITUDE_PROFILE=sandbox     # or pick a profile for the current shell only

Managing profiles

latitude profiles list                        # every profile, with the default marked
latitude profiles current                     # the profile this command would use, and why
latitude profiles show sandbox                # one profile's settings
latitude auth login --with-token -p sandbox   # replace the sandbox key
latitude profiles remove sandbox              # delete the profile and its stored key
latitude profiles use -                       # clear the default profile

Profiles live in a profiles.toml file in the CLI’s config directory: ~/Library/Application Support/latitude/ on MacOS, ~/.config/latitude/ on Linux, and %APPDATA%\latitude\ on Windows. The file never holds a key. Each key stays in the keyring under latitude:ApiKeyAuth#<profile>. A profile can also carry a default project, which helps when your profiles point at different projects:

latitude profiles create support-bot --project-slug support-bot

A profile’s project wins over LATITUDE_PROJECT_SLUG and --global-project-slug. Passing --project-slug on a command still overrides it.

Which key a command uses

The CLI uses the first of these that’s set:

The profile passed with -p / --profile.
LATITUDE_API_KEY, from your shell or a .env file.
The profile named by LATITUDE_PROFILE, or else the default set with latitude profiles use.
The key stored by latitude auth login with no profile selected.

A selected profile only ever sends its own key. If it has none stored, the command fails to authenticate instead of falling back to another key.

LATITUDE_API_KEY beats both the default profile and LATITUDE_PROFILE. If it’s set in your shell or in .env (for example, because your app’s tracing reads it from there), commands keep using it after latitude profiles use. Pass -p to override it. latitude profiles current reports credential_overridden_by_env when this happens, and latitude auth status shows the profile’s key as shadowed. Profiles only affect the CLI, so your app keeps reading LATITUDE_API_KEY as before.

Usage

The general shape is latitude <resource> <command> [flags], where each resource mirrors an area of the Latitude API:

latitude --help                 # list every resource
latitude projects --help        # list the commands for a resource
latitude projects list          # run one

latitude projects create --help # discover a command's flags/arguments

Resources include projects, traces, datasets, and more — run latitude --help for the full list. Common examples:

latitude account get                       # the current org + your role
latitude usage get                         # credits used this period, by area and project
latitude projects usage --project-slug X   # the same, for one project
latitude projects list                     # every project in the org
latitude projects create --name "My App"   # create a project
latitude traces list --help                # inspect traces (project-scoped — see --help for the flags)
latitude api-keys list

Most resources are project-scoped and take --project-slug. Set the project once for a session with LATITUDE_PROJECT_SLUG (or the global --global-project-slug flag) and you can drop it from individual commands — --project-slug still wins wherever you pass it:

export LATITUDE_PROJECT_SLUG=my-app
latitude traces list                       # uses my-app
latitude traces list --project-slug other  # uses other
latitude projects list                     # unaffected — not project-scoped

A profile can carry its own default project as well. A few global flags worth knowing (run latitude --help for the full list):

--profile <name> / -p — run the command under a named profile.
--query <JMESPath> — project/filter the response before it’s formatted, e.g. --query "items[].slug". When an API operation has its own query parameter (like the free-text search on traces list), that parameter is exposed as --query-param instead.
--dry-run — validate the request locally without sending it to the API.
--quiet / -q — suppress success output (errors still print to stderr).
--human — force table output even when stdout is piped.
--schema — print a machine-readable JSON description of a command’s inputs and outputs, the agent-facing counterpart to --help.
--debug — dump the raw HTTP request and response to stderr.

API commands also take a few request options:

--params <JSON> — pass parameters as a JSON object. These override the individual flags.
--json <JSON|-> — on commands that send a request body, pass the whole body as JSON. Use - to read it from stdin.
--retries <N> / --no-retry — change how many times a failed request is retried, or turn retries off.

Output formats

Every command accepts --format to control how results are rendered. This makes the CLI equally good for humans reading a terminal and for scripts or agents parsing output.

Format	Description
`table`	Human-readable table. Default when stdout is a TTY.
`json`	Pretty JSON. Default when the output is piped.
`jsonl`	Newline-delimited JSON (NDJSON) — one compact value per line; arrays are flattened. Ideal for streaming into other tools.
`yaml`	YAML.
`csv`	CSV — convenient for spreadsheets.
`raw`	The unmodified server response bytes.
`http`	The full HTTP response (status line + headers + body), like `curl -i`.

latitude projects list --format json
latitude projects list --format csv > projects.csv
latitude traces list --format jsonl | jq .   # stream trace-by-trace

# Combine with --query to reshape before formatting
latitude projects list --query "items[].{slug: slug, name: name}" --format yaml

You can also set a default format for a session with the LATITUDE_OUTPUT environment variable (e.g. export LATITUDE_OUTPUT=json); the --format flag always overrides it. --human is shorthand for --format table, for when you pipe output but still want the table.

Environment variables

Variable	Purpose
`LATITUDE_API_KEY`	API key used to authenticate (alternative to the keyring).
`LATITUDE_PROFILE`	Profile to use when `--profile` is omitted.
`LATITUDE_PROJECT_SLUG`	Project used by project-scoped commands when `--project-slug` is omitted (same as the global `--global-project-slug`).
`LATITUDE_OUTPUT`	Default output format when `--format` is omitted.
`LATITUDE_RETRIES`	How many times to retry a failed request when `--retries` is omitted.
`LATITUDE_BASE_URL`	Override the API base URL (e.g. self-hosted or a mock server).
`LATITUDE_TIMEOUT_SECS`	Total request timeout, in seconds.
`LATITUDE_CONNECT_TIMEOUT_SECS`	Connection timeout, in seconds.
`LATITUDE_PROXY`	HTTP(S) proxy URL.
`LATITUDE_CA_BUNDLE`	Path to a PEM file with extra trust roots.
`LATITUDE_INSECURE=1`	Skip TLS verification (debugging only).
`LATITUDE_USER_AGENT_SUFFIX`	Product token appended to the `User-Agent`, e.g. `my-tool/1.0` (`--user-agent-suffix` overrides it).

The standard HTTPS_PROXY / HTTP_PROXY / NO_PROXY / SSL_CERT_FILE variables are honored as well. Any of these can also go in a .env file, except LATITUDE_BASE_URL and the proxy, CA bundle, and TLS variables, which the CLI only reads from your shell (see Authentication).

Shell completion

Generate a completion script for your shell — bash, zsh, fish, powershell, or elvish — and load it to get tab-completion for every resource, command, and flag:

zsh
bash
fish

latitude completion zsh > ~/.latitude-completion.zsh
echo 'source ~/.latitude-completion.zsh' >> ~/.zshrc

latitude completion bash | sudo tee /etc/bash_completion.d/latitude > /dev/null

latitude completion fish > ~/.config/fish/completions/latitude.fish

Man page

The CLI can emit its own manual page in roff format, so man latitude works like any native tool:

latitude man > latitude.1
man ./latitude.1
# or install it system-wide:
sudo mv latitude.1 /usr/local/share/man/man1/ && man latitude

For Agents

The CLI pairs naturally with agents: --format json/jsonl for structured output, --schema for machine-readable help, and latitude generate-skills to teach an agent the command surface — everything it needs to drive Latitude locally with no MCP connection. Have agents pass -p on every command when you use profiles, so each call names its environment and can’t be redirected by a LATITUDE_API_KEY in the environment. Prefer the MCP server when you’d rather connect the agent over the network with OAuth.

Overview

Getting Started

Observe

Understand

Refine

Security and Compliance

Deployment

Development

More

Overview

Installation

Authentication

Profiles

Production and sandbox

Managing profiles

Which key a command uses

Usage

Output formats

Environment variables

Shell completion

Man page

For Agents

​Overview

​Installation

​Authentication

​Profiles

​Production and sandbox

​Managing profiles

​Which key a command uses

​Usage

​Output formats

​Environment variables

​Shell completion

​Man page

​For Agents

Overview

Installation

Authentication

Profiles

Production and sandbox

Managing profiles

Which key a command uses

Usage

Output formats

Environment variables

Shell completion

Man page

For Agents