Skip to main content
The CLI binary is caesar-search. It works without an API key on the anonymous tier, so you can install and run your first search in under a minute.

​
Install

brew install caesar-data/tap/caesar-search
ChannelNotes
HomebrewA formula (not a cask) in the caesar-data/homebrew-tap repo.
npmPackage caesar-search-cli, binary caesar-search. Requires Node 20 or newer. No postinstall scripts, so --ignore-scripts works.
Installer scriptVerifies 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.

​
Verify

caesar-search version
caesar-search search "hello world" --max-results 1
version prints caesar-search 0.1.4 (<commit>, <date>); with --json it returns {"version": ..., "commit": ..., "build_date": ...}. The search runs keyless — the anonymous tier is live at a lower rate limit.

​
Authenticate

An API key raises your rate limits; without one the CLI runs anonymously. Either set the CAESAR_API_KEY environment variable, or store the key in the config file: 
caesar-search auth login            # prompts for the key, input hidden
caesar-search auth login --key -    # reads the key from stdin, e.g. piped from a secret manager
Never paste an API key into a chat or leave it in shell history. Use the hidden auth login prompt, or pipe it in with --key -. The CLI stores keys with mode 0600, masks them in all output, and never logs them.
Check what the CLI is using: 
caesar-search auth status --json
The payload reports key_present, key_source (flag, env, 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.

​
Update

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:
ChannelWhat update does
npmRuns npm install -g caesar-search-cli@latest
brewRuns brew upgrade caesar-data/tap/caesar-search
standaloneDownloads the release archive, verifies its sha256 against checksums.txt, and atomically replaces the running binary
devRefuses (exit 2) — source builds update from source: git pull && bun install
--check works on every channel, including dev, and returns: 
{"current": "0.1.4", "latest": "0.1.4", "update_available": false, "channel": "brew"}
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.

​
Shell completions

caesar-search completion bash|zsh|fish prints a completion script to stdout. Wire it up from your shell rc file: 
eval "$(caesar-search completion bash)"

​
For agents

  • The binary is caesar-search, not caesar.
  • Anonymous access works keyless — don’t block a task on authentication.
  • 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.