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

# Install the CLI

> Install the caesar-search CLI with Homebrew, npm, or the standalone installer, then authenticate and keep it up to date.

The CLI binary is `caesar-search`. Install it, then authenticate with an API key from the [Caesar app](https://app.trycaesar.com). For a limited time, all accounts receive a \$1,000 starting credit grant.

## Install

<CodeGroup>
  ```bash Homebrew theme={"system"}
  brew install caesar-data/tap/caesar-search
  ```

  ```bash npm theme={"system"}
  npm install -g caesar-search-cli
  ```

  ```bash Installer script theme={"system"}
  curl -fsSL https://raw.githubusercontent.com/caesar-data/caesar-search-cli/main/install.sh | bash
  ```
</CodeGroup>

| Channel          | Notes                                                                                                                                                                   |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Homebrew         | A formula (not a cask) in the `caesar-data/homebrew-tap` repo.                                                                                                          |
| npm              | Package `caesar-search-cli`, binary `caesar-search`. Requires Node 20 or newer. No postinstall scripts, so `--ignore-scripts` works.                                    |
| Installer script | Verifies the sha256 checksum against the release `checksums.txt`, then installs to `~/.local/bin` (override with `CAESAR_INSTALL_DIR`). macOS and Linux, x64 and arm64. |

Prebuilt archives for all platforms (including Windows), with checksums and SBOMs, are on [GitHub Releases](https://github.com/caesar-data/caesar-search-cli/releases).

## Verify

```bash theme={"system"}
caesar-search version
caesar-search search "hello world" --max-results 1
```

`version` prints `caesar-search 0.2.0 (<commit>, <date>)`; with `--json` it returns `{"version": ..., "commit": ..., "build_date": ...}`. Search requires `CAESAR_API_KEY` or a key stored with `caesar-search auth login` (browser login).

## Authenticate

The default is browser login — no key ever touches your clipboard:

```bash theme={"system"}
caesar-search auth login            # opens the browser; stores a named, revocable key in the OS keychain
caesar-search auth login --device   # SSH/containers: approve with a short code on any device
```

Browser login creates a key labelled `CLI · <hostname> · <date>` that you can see and revoke in the console at any time. It lands in the OS keychain (macOS Keychain, libsecret on Linux) with a 0600 config-file fallback; `--insecure-storage` forces the file.

For CI and scripts, set the `CAESAR_API_KEY` environment variable, or pipe a key in directly:

```bash theme={"system"}
caesar-search auth login --key -    # reads the key from stdin, e.g. piped from a secret manager
```

<Warning>
  Never paste an API key into a chat or leave it in shell history. Prefer browser login; for raw keys, pipe them in with `--key -`. The CLI stores file-based keys with mode 0600, masks them in all output, and never logs them.
</Warning>

Check what the CLI is using:

```bash theme={"system"}
caesar-search auth status --json
```

The payload reports `key_present`, `key_source` (`flag`, `env`, `keychain`, `config`, or `none`), `key_masked`, `base_url`, `api_reachable`, and `config_path`. `caesar-search auth logout` removes the stored key. Full resolution order is on [Scripting and CI](/clients/cli/automation).

## Update

```bash theme={"system"}
caesar-search update                 # upgrade in place
caesar-search update --check --json  # report only, change nothing
```

`update` detects how the CLI was installed and uses the matching channel:

| Channel      | What `update` does                                                                                                     |
| ------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `npm`        | Runs `npm install -g caesar-search-cli@latest`                                                                         |
| `brew`       | Runs `brew upgrade caesar-data/tap/caesar-search`                                                                      |
| `standalone` | Downloads the release archive, verifies its sha256 against `checksums.txt`, and atomically replaces the running binary |
| `dev`        | Refuses (exit 2) — source builds update from source: `git pull && bun install`                                         |

`--check` works on every channel, including `dev`, and returns:

```json theme={"system"}
{"current": "0.2.0", "latest": "0.2.0", "update_available": false, "channel": "brew"}
```

<Note>
  Don't run `npm update -g` or `brew upgrade` by hand — `caesar-search update` picks the right channel itself. If a flag errors as unknown, the installed CLI is outdated: run `caesar-search update` and retry.
</Note>

## Shell completions

`caesar-search completion bash|zsh|fish` prints a completion script to stdout. Wire it up from your shell rc file:

<CodeGroup>
  ```bash bash (~/.bashrc) theme={"system"}
  eval "$(caesar-search completion bash)"
  ```

  ```bash zsh (~/.zshrc) theme={"system"}
  eval "$(caesar-search completion zsh)"
  ```

  ```bash fish (~/.config/fish/config.fish) theme={"system"}
  caesar-search completion fish | source
  ```
</CodeGroup>

## For agents

* The binary is `caesar-search`, not `caesar`.
* API calls require a key — verify `CAESAR_API_KEY` or run `caesar-search auth login` before search/read tasks.
* `npm install -g caesar-search-cli --ignore-scripts` is safe; there are no postinstall scripts.
* On an unknown-flag error, run `caesar-search update`, then retry the command.
* Never echo or log a key; `auth login --key -` reads it from stdin.

Full command reference and the common-mistakes table: [CLI usage](/clients/cli/usage).