Quickstart

Get started with XMDB in under 5 minutes. This guide covers CLI installation, authentication, and basic memory operations.

Prerequisites

• An XMDB account and API token (get one from the Dashboard)
• A workspace and scope configured in the dashboard

Install the CLI

Download and install xmdbctl for your platform:

# macOS / Linux
curl -fsSL https://get.xmdb.cloud/install.sh | sh

# Or with Homebrew
brew install xmdb/tap/xmdbctl

Verify the installation:

xmdbctl --version

Authenticate

Login to the XMDB API with your token:

xmdbctl login https://api.xmdb.cloud --token $XMDB_API_TOKEN

If your token has access to multiple scopes, specify the default scope:

xmdbctl login https://api.xmdb.cloud --token $XMDB_API_TOKEN --scope my-scope

Note: xmdbctl token create requires an existing admin token. If you don't have one, get your initial token from the Dashboard first.

Check your connection status:

xmdbctl status

This displays your authenticated identity, workspace, and available scopes.

Capture your first memory

Store a memory item with the capture command:

xmdbctl capture "Project kickoff meeting completed. Decided on Next.js + Tailwind stack."

Add source metadata for better organization:

xmdbctl capture "Deployed v1.0.0 to production" --source-kind deployment --source-ref "github.com/org/repo/releases/v1.0.0"

List items

View your captured memory items:

xmdbctl items

Filter by source kind:

xmdbctl items --source-kind deployment

Query memory

Search your memory with natural language:

xmdbctl query --q "deployment"

Explain a query

Explain mode annotates results with match mode, policy checks, signature status, and revision metadata so you can see why an item was included.

xmdbctl query --q "deployment" --explain

Build a context pack

Create a deterministic context pack for your AI agent:

xmdbctl pack "project decisions" --token-budget 2000

The pack includes:

• Relevant memory chunks based on your query
• A pack_hash for verification
• Optional signature for attestation

Next steps

• MCP Integration - Connect XMDB to Claude, Cursor, ChatGPT, or Gemini
• CLI Reference - Full command reference
• Security - Token management and best practices