xtrace shell), omit the xtrace prefix:
Shared commands
init
init sets up your local SDK repo by connecting your XTrace credentials, creating or loading an execution context, and loading an embedding model. Must be run once before any data commands. --env-file / -f sets a custom path for the generated .env file (default: .env). --admin saves your admin key to .env for implicit admin access. --inference saves an inference API key.
version
shell
xtrace prefix.
Knowledge base admin — xtrace kb
KB commands require ADMIN_KEY input, entered once per session. To avoid repeated prompts, run init --admin to save the key to your .env.
create
NAME. Use -d for an optional description (wrap in quotes). Control access with -p {permission}: read, write, delete, or none (default: write). The permission applies to the API key in your .env unless overridden with -a {API_KEY}. --json returns the raw API response.
delete
--json outputs raw JSON results.
list
--all also shows KBs with no permissions (displayed as NONE). --json returns raw JSON including numeric permissionLabel values. Override the API key with -a {api_key}.
describe
--json returns raw JSON (list when multiple IDs are given). Override the API key with -a {api_key}.
x-vec commands — xtrace xvec
load
KB_ID, processing files of type .txt, .md, .json, and .csv. To filter by file type, use -f with a comma-separated list (e.g. txt,json).
--max-chunk-chars {N} sets a character limit per chunk. Chunks that exceed this limit (e.g. large JSON array elements) are split to fit. Useful when your embedding model has a small context window.
--max-parallel-embeddings {N} limits the number of concurrent embedding requests. Useful when your embedding provider has concurrency limits (e.g. a local Ollama instance).
retrieve
k most similar vectors to the query (default k=3). --inference {provider} --model {"model"} runs an LLM over the retrieved context (requires an inference key from init --inference). --json returns raw chunk data. Override the API key with -a {api_key}.
query
retrieve. Same signature and behavior.
head
--all shows every vector. --fullChunks disables content truncation. --json returns a raw JSON array. Override the API key with -a {api_key}.
fetch
--fullChunks disables content truncation. --json returns a raw JSON list of {id, content} objects. Override the API key with -a {api_key}.
upsert
text in quotes if it contains spaces.
upsert-file
.txt, .md, .json, .csv. For multiple files, use load.
--max-chunk-chars {N} and --max-parallel-embeddings {N} behave the same as in load (see above).
x-mem commands — xtrace xmem
x-mem CLI commands are coming soon.