●ctx0.1.0

Reference

The command line, the HTTP API, configuration, exit codes and limits, as of ctx 0.1.0.

Command line

Global options: --config FILE (else CTX_CONFIG, else ~/.config/ctx/config.yaml), --url URL (or CTX_URL), --writer NAME, and --json for a machine-readable envelope on stdout. A VALUE is JSON if it parses and a string otherwise; -s forces a string and -f FILE reads it from a file (- for stdin).

CommandOptionsDoes
get [KEY]--format json|md|ndjson|raw --rev --max-age --since-rev --stale-after --max-bytes --compact --allow-missingA key and its subtree; empty reads everything.
ls [PREFIX]-r --limit --afterChildren, or with -r every descendant, with counts, ages and writers.
set KEY VALUE-s -f --if-revReplace.
update KEY PATCH-s -f --if-revJSON merge patch (RFC 7386).
append KEY VALUE-s -f --max-items --if-revAdd to an array.
rm KEY-r --if-revDelete a key or subtree.
batch [FILE]A JSON array or NDJSON of operations, all or none.
history KEY--limit --before-revVersions, newest first.
changes PATTERN--since --limit --with-prevChanges after a revision.
watch PATTERN--since --with-prev --exec --once --until --timeoutStream, wait or react; reconnects by itself.
search WORDS…--prefix --limit --max-age --raw --mode fts|semantic|hybridFind entries.
prompt--project --machine --agent --cwd --key --max-bytes --max-age --stale-after --settingsThe preload as Markdown.
statusDaemon version, head revision, counts, size, watchers, embeddings.
export [PREFIX]Entries as NDJSON.
import [FILE]--chunk (500)NDJSON {"key","value"} lines, in atomic chunks.
daemon--bind --unix-socket --database --token-fileRun the daemon.
mcp stdioThe MCP server.
configshow path status init validate schema export importManage config.yaml.
tui [KEY]--theme nord|light|mono --no-mouseBrowse live: key tree, values, history diffs, filter and search.
guideThe agent guide: conventions, tools and examples.
completions SHELLShell completions.

ls and rm are aliases of list and delete. For --exec, each change's event is on stdin and CTX_KEY, CTX_REV, CTX_OP, CTX_VALUE, CTX_PREV_VALUE and CTX_WRITER are set.

Exit codes

CodeMeaningHTTP
0OK200
1Internal error500
2Invalid input: a bad key, value, pattern or operation400 (413 when too large)
3Not found404
4Conflict: if_rev did not match409
5Daemon unavailable, or too many watchers503
6Unauthorized: missing or wrong token401
7Timeout, including watch --timeout504
8Configuration error

Errors print one line, then a next: hint when there is an obvious next step. With --json they are an envelope with a category, a code and details:

ctx --json set flow.release.state '"rejected"' --if-rev 10{"status":"error","meta":{"schema_version":1,"command":"set"},"error":{"category":"execution_failure","code":"conflict","message":"conflict on `flow.release.state`: expected rev 10, current rev 9","details":{"key":"flow.release.state","expected":10,"current":9}}}

HTTP

EndpointTakesReturns
POST /v1/opOne operation as JSON: {"op": "get", …}An envelope: {"status":"success","meta":{…},"data":{…}} or an error
GET /v1/watchpattern, since (default 0), with_prevNDJSON events: change, then ready after replay, and heartbeat
GET /v1/healthNothing; no token needed{"ok":true,"version":"0.1.0","head_rev":24}

Send Authorization: Bearer TOKEN on /v1/op and /v1/watch, and the writer name in x-ctx-writer (else unknown). Request bodies are limited to daemon.max-body-bytes.

Operations

opFields
getkey, rev, max_age, since_rev, stale_after, meta, max_bytes
listprefix, recursive, limit (200, at most 10,000), after
historykey, limit (20, at most 1,000), before_rev
changespattern, since_rev, limit (100, at most 10,000), with_prev; returns next_since and more
searchquery, prefix, limit (20, at most 200), max_age, raw, mode
statusnone
setkey, value, if_rev
updatekey, patch, if_rev
appendkey, value, max_items, if_rev
deletekey, recursive, if_rev
batchops: a list of set, update, append and delete objects, each with its own op

Unknown fields are rejected. A write's result says whether it changed anything and gives its rev, prev_rev and version; reads carry the store's head_rev. ctx config schema prints the configuration's JSON Schema.

Configuration

~/.config/ctx/config.yaml, with every default, as ctx config show prints it. Unknown keys are errors.

client:  daemon-url: http://127.0.0.1:7641     # or https://…, or unix:///path/ctx.sock  token-file: ~/.config/ctx/daemon-token  writer: null                          # else CTX_WRITER, CACO_AGENT_ID, user@host  timeout-secs: 30daemon:  bind: 127.0.0.1:7641                  # null disables TCP  unix-socket: null                     # created owner-only  token-file: ~/.config/ctx/daemon-token  # created owner-only if absent  database: ~/.local/share/ctx/ctx.sqlite  durability: normal                    # or full: fsync every commit  max-value-bytes: 1048576  max-body-bytes: 8388608  max-batch-ops: 1000  readers: 4  heartbeat-secs: 15  max-watchers: 4096  embeddings: nullrender:  stale-after: null                     # defaults for reads  max-age: nullpi:  preload: true  keys:  - global  - project.{project}  - machine.{machine}  - agent.{agent}  max-age: null  stale-after: 7d  max-bytes: 8000  delivery: follow-up                   # or steer  debounce-ms: 1500

Embeddings

Set daemon.embeddings to enable semantic and hybrid search through any OpenAI-compatible endpoint:

daemon:  embeddings:    base-url: http://litellm.lan:4000/v1    # /embeddings is appended    model: text-embedding-3-large    dimensions: 1024                         # optional, for models that shorten    api-key-file: ~/.config/ctx/embeddings-key   # or CTX_EMBEDDINGS_API_KEY_FILE    batch: 64                                # entries per request    max-chars: 8000                          # characters of each entry embedded    timeout-secs: 30

Environment

VariableUsed for
CTX_CONFIGThe config file.
CTX_URLThe daemon URL, overriding client.daemon-url.
CTX_WRITER, CACO_AGENT_IDThe writer name, in that order.
CTX_MACHINE{machine} in preload keys; else the short host name.
CTX_AGENT, CACO_AGENT_ID{agent} in preload keys.
CTX_EMBEDDINGS_API_KEY_FILEThe embeddings key file.
CTX_LOGThe daemon's log filter, for example debug; default info, on stderr.
CTX_BINThe ctx binary the Pi plugin and pi-daemon module run.
CTX_AHP_URL, CTX_AHP_TOKEN_FILEWhere the pi-daemon module delivers subscription messages.

Keys, patterns and limits

ItemRule
KeySegments of [A-Za-z0-9_-]+ joined by dots; at most 32 segments and 512 bytes.
ValueAny JSON, at most max-value-bytes (1 MiB).
Patterna.b exact · a.b.* children · a.b.** or a.b.> subtree including a.b.
BatchAt most max-batch-ops (1,000) operations.
WatchersAt most max-watchers (4,096) at once.
AgesNumbers with units s, m, h, d or w, combinable: 90s, 1h30m, 2w.
HistoryKept forever: no TTLs, no expiry.