CLI Command Reference

This section provides usage details for all CLI commands. See XTrace CLI Quick Start for installation and first-time setup.

Commands are grouped by submodule and invoked as:

xtrace <group> <command> [ARGS]       # subgroup command
xtrace <command> [ARGS]               # top-level command

Inside the interactive shell (xtrace shell), omit the xtrace prefix:

> xvec load /path/to/data/ KB_ID
> kb create my-kb

Shared commands

init

xtrace init [--env-file {path/to/env-file}] [--admin] [--inference] [--help]

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

xtrace version

Prints the installed SDK version.

shell

xtrace shell

Starts an interactive CLI shell with tab completion and command history. Inside the shell, run commands without the 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

xtrace kb create {NAME} [-d "{description}"] [-p {permission}] [--json] [-a {API_KEY}] [--help]

Creates a knowledge base named 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

xtrace kb delete {KB_ID...} [--json] [--help]

Permanently deletes one or more space-separated knowledge bases. Prompts for confirmation. --json outputs raw JSON results.

list

xtrace kb list [--all] [--json] [-a {api_key}] [--help]

Lists all knowledge bases accessible to your current API key. By default, only KBs with explicit permissions are shown. --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

xtrace kb describe {KB_ID ...} [--json] [-a {api_key}] [--help]

Prints details for one or more knowledge bases. --json returns raw JSON (list when multiple IDs are given). Override the API key with -a {api_key}.

x-vec commands — xtrace xvec

load

xtrace xvec load {/path/to/dir/} {KB_ID} [-f {file-types,...}] [--max-chunk-chars {N}] [--max-parallel-embeddings {N}] [--help]

Loads data from a directory into a knowledge base with id 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

xtrace xvec retrieve {KB_ID} {"query"} [-k {integer}] [--inference {provider} --model {"model"}] [--json] [-a {api_key}] [--help]

Returns the 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

xtrace xvec query {KB_ID} "{query}" [-k {integer}] [--inference {provider} --model {"model"}] [--json] [-a {api_key}] [--help]

Alias of retrieve. Same signature and behavior.

fetch

xtrace xvec fetch {KB_ID} {VECTOR_ID...} [--fullChunks] [--json] [-a {api_key}] [--help]

Fetches one or more vectors by ID. --fullChunks disables content truncation. --json returns a raw JSON list of {id, content} objects. Override the API key with -a {api_key}.

upsert

xtrace xvec upsert {KB_ID} "{text}" [--help]

Inserts a single text chunk into a knowledge base. Wrap text in quotes if it contains spaces.

upsert-file

xtrace xvec upsert-file {/path/to/file} {KB_ID} [--max-chunk-chars {N}] [--max-parallel-embeddings {N}] [--help]

Inserts and chunks the contents of a single file into a knowledge base. Supported types: .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 commands are coming soon.