> ## Documentation Index
> Fetch the complete documentation index at: https://docs.latitude.so/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Install and use the Latitude CLI to manage your Latitude organization right from the terminal

## Overview

The **`latitude` CLI** is a single, self-contained binary that exposes your Latitude organization on the command line. Like the [MCP server](/getting-started/mcp), 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](https://api.latitude.so/docs).

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.

<Info>
  Prefer a network connection? The [MCP server](/getting-started/mcp) exposes the same capabilities over OAuth.
</Info>

## Installation

The CLI ships as a pre-built binary on our [GitHub Releases](https://github.com/latitude-dev/latitude-llm/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`) |

<Tabs>
  <Tab title="MacOS / Linux">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    # 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
    ```

    <Info>
      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**.
    </Info>
  </Tab>

  <Tab title="Windows">
    Download `latitude-windows-amd64.zip`, extract `latitude.exe`, and move it to a directory on your `PATH` (or add its folder to `PATH`). Then:

    ```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
    latitude --version
    ```
  </Tab>
</Tabs>

Then verify it works and, optionally, set up [shell completion](#shell-completion) and the [man page](#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:

<Tabs>
  <Tab title="Keyring (recommended)">
    Store the key once in your operating system's secret store (Keychain on MacOS, Secret Service on Linux, Credential Manager on Windows):

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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](#profiles).
  </Tab>

  <Tab title="Environment variable">
    Export the key in your shell — handy for CI or ephemeral environments:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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.
  </Tab>
</Tabs>

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](/telemetry/start-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](/observability/features/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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

1. The profile passed with `-p` / `--profile`.
2. `LATITUDE_API_KEY`, from your shell or a `.env` file.
3. The profile named by `LATITUDE_PROFILE`, or else the default set with `latitude profiles use`.
4. 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.

<Warning>
  `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.
</Warning>

## Usage

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](#profiles) 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](#profiles).
* `--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`. |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](#profiles) 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](#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:

<Tabs>
  <Tab title="zsh">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    latitude completion zsh > ~/.latitude-completion.zsh
    echo 'source ~/.latitude-completion.zsh' >> ~/.zshrc
    ```
  </Tab>

  <Tab title="bash">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    latitude completion bash | sudo tee /etc/bash_completion.d/latitude > /dev/null
    ```
  </Tab>

  <Tab title="fish">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    latitude completion fish > ~/.config/fish/completions/latitude.fish
    ```
  </Tab>
</Tabs>

## Man page

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](#profiles), so each call names its environment and can't be redirected by a `LATITUDE_API_KEY` in the environment. Prefer the [MCP server](/getting-started/mcp) when you'd rather connect the agent over the network with OAuth.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.