Skip to main content
The standard loop is search, pick a doc_id, read it, optionally send feedback: 
caesar-search search "kubernetes operator patterns" --max-results 5 --format compact --json -o /tmp/search.json
DID=$(jq -r '.results[0].doc_id' /tmp/search.json)
SID=$(jq -r '.search_id' /tmp/search.json)
caesar-search read "$DID" --query "reconciliation loop" --json
caesar-search feedback --event-type result_helpful --search-id "$SID" --doc-id "$DID"
Provenance fields (doc_id, search_id, capture_id, canonical_url) are stable handles — thread them between commands and cite them. See provenance.

​
Commands

CommandDoesKey flags
search <query|->Web search--mode, --max-results, --format, --objective
read <url|doc_id|->Read a page as markdown (aliases: fetch, extract)--query, --max-chars, --start-char, --include
feedbackSend result feedback--event-type (required), --search-id, --doc-id, --passage-id, --query, --rank, --notes
auth status|login|logoutManage the stored API key--key
config get|set|unset|list|pathManage config keys api_key and base_url—
api <method> <path>Raw authenticated API call (escape hatch)--input <file|->
updateChannel-aware self-update--check
versionPrint version, commit, and build date—
completion <shell>Completion script for bash, zsh, or fish—

​
Global flags

Available on every command:
FlagMeaningDefault
--jsonMachine output: data on stdout, JSON error envelope on stderroff (human output)
-o, --output <file>Write data output to a file and suppress stdout—
--key <key>API key (overrides CAESAR_API_KEY and the config file)—
--base-url <url>API base URL (overrides CAESAR_BASE_URL)https://search-api-staging-779189860552.europe-west1.run.app
--no-retryDisable rate-limit/5xx retriesretries on
--timeout <seconds>Request timeout in seconds30
--format is not a global flag — it belongs to search only.
FlagValuesDefault
--modefast, standard, researchstandard
--max-resultsinteger 1–5010
--objectivefree text — the broader task, to steer retrieval—
--formatids_only, compact, standard, fullstandard
--format maps to the API’s response shaping verbosity: compact is the token-efficient choice for search-then-read loops, standard adds quotable passages, full adds capture provenance.

​
read

The target should be a full URL (https://…) or a doc_id UUID; a scheme-less target (e.g. example.com) is normalized to https:// by the API.
FlagValuesDefault
--queryfocus content selection on this question—
--max-charscontent character cap, 1–5000012000
--start-charresume a truncated read from this offset0
--includecomma list of metadata,content,passages,capture_historymetadata,content
A truncated read reports content.truncated: true plus content.char_count and content.start_char (omitted when 0). Continue with --start-char set to start plus count — don’t retry with a bigger --max-chars: 
caesar-search read https://en.wikipedia.org/wiki/Web_crawler --max-chars 4000 --json
# content.truncated: true, content.char_count: 4000 (content.start_char omitted when 0)
caesar-search read https://en.wikipedia.org/wiki/Web_crawler --start-char 4000 --json

​
feedback

--event-type is required. Values: result_helpful, result_not_helpful, passage_used, read_abandoned, duplicate_result, stale_result, spam_or_low_quality, missing_expected_source, unsafe_or_policy_issue. Pair it with --search-id and/or --doc-id so the event lands on the right target.

​
Reading from stdin

- reads stdin to EOF for the search query, the read target, auth login --key -, and api --input -: 
echo "model context protocol spec" | caesar-search search - --json | jq -r '.results[0].doc_id'

​
JSON output

With --json, data is a single JSON object on stdout and errors are a JSON envelope on stderr (hint only when present): 
{"error": {"code": "rate_limited", "message": "rate limit exceeded", "hint": "Rate limited. Wait and retry, or lower request volume."}}
All fields are snake_case, exactly as the API returns them. Human (non---json) output is not a stable interface — never parse it. -o <file> writes the data payload to the file and suppresses stdout entirely, so output limits can’t truncate JSON mid-parse. The agent pattern is write-then-read: 
caesar-search search "rust async runtimes compared" --format compact --json -o /tmp/out.json
cat /tmp/out.json
Errors still go to stderr, and the exit code is unchanged.

​
Exit codes

CodeMeaning
0success (includes --help and --version)
2bad input (validation errors, unknown flags, usage errors)
3auth error (HTTP 401/403)
4API error (other HTTP errors, network failures, update failures)
5timeout
Branch on these, not on output parsing — see Scripting and CI.

​
For agents

MistakeCorrection
--results, --limit, -nThe flag is --max-results
--response-formatThe flag is --format (values: ids_only, compact, standard, full)
--mode deep / --mode quickModes are exactly fast, standard, research
Passing a bare domain to readread needs a full URL (https://…) or a doc_id UUID
Retrying a truncated read with bigger --max-charsUse --start-char to continue from where it stopped
Parsing human outputUse --json; human output is not a stable interface
Shell-redirecting and also reading stdoutUse -o <file>; it suppresses stdout so nothing competes with the file
npm update -g / brew upgrade by handcaesar-search update picks the right channel itself
Expecting camelCase JSONAll fields are snake_case, exactly as the API returns them
caesar searchThe binary is caesar-search