Use XDB from an agent

Each resource command has the same grammar:

xdb <resource> <action> <URI> [--filter CEL] [--fields MASK] [--json|--file|-] [-o FMT]

the grammar

Discover the CLI

xdb context prints the CLI guide as Markdown. xdb describe returns structured reference data.

xdb context                                  # the CLI guide
xdb describe --actions                       # the actions on each resource
xdb describe records.create                  # the parameters of one action
xdb describe --uri xdb://com.example/posts   # the live schema
xdb describe --filter                        # CEL operators and functions
xdb describe --errors                        # the error codes
xdb describe --value-types                   # the value types

The CLI also contains skills: Markdown recipes for getting-started, bulk-data, query-and-filter, and schema-evolution. The skills are in the binary, so they work offline.

xdb skills                  # list the skills
xdb skills get bulk-data    # print one skill

Parse errors

Each error has the same shape in each output format:

{
  "code": "NOT_FOUND",
  "message": "[xdb/api] records.get xdb://com.example/posts/nope: [xdb/core] not found",
  "resource": "records",
  "action": "get",
  "uri": "xdb://com.example/posts/nope",
  "hint": "try: xdb records list xdb://com.example/posts"
}

The exit code gives the class of the error:

Exit code	Meaning
0	Success
1	Application error: NOT_FOUND, ALREADY_EXISTS, CONFLICT, SCHEMA_VIOLATION, or NOT_IMPLEMENTED
2	Connection error
3	Invalid argument
4	Internal error

Errors explains each code.

Pipe JSON

On a terminal, the default output is a table. In a pipe, the default output is JSON. -o selects json, ndjson, table, or yaml.

- reads the URI or the payload from stdin:

echo '{"title":"Hello"}' | xdb records create xdb://com.example/posts/p-1 -
xdb records get xdb://com.example/posts/p-1 | jq -r .title

json in, json out

xdb batch reads one operation from each line of NDJSON:

echo '{"op":"records.upsert","uri":"xdb://com.example/posts/p-2","data":{"title":"Hi"}}' | xdb batch -

A batch is atomic on the sqlite and memory backends. On the fs and redis backends, pass --non-atomic.

Use the aliases

An alias selects the resource from the depth of the URI. Aliases make shell commands shorter. In a script, the full form is easier to read.

Alias	Runs
xdb get <uri>	get on the namespace, schema, or record
xdb ls [uri]	list. Without a URI, it lists the namespaces.
xdb put <uri>	records upsert
xdb rm <uri> --force	delete on the record or schema
xdb make-schema <uri>	schemas create

Find the stored data

To find all the data, start at the namespaces:

xdb namespaces list
xdb namespaces get xdb://com.example
xdb records list xdb://com.example

namespaces get returns the schemas in the namespace:

{ "namespace": "com.example", "schemas": ["xdb://com.example/posts"], "total_schemas": 1 }

Check the daemon

The CLI sends each command to the daemon. xdb daemon status exits with code 2 when the daemon is stopped, so a script can stop before the first command:

xdb daemon status --quiet && xdb records list xdb://com.example/posts