@agentdb/cli

Command-line interface for the AgentDB database service. Talks to AgentDB entirely through the official @agentdb/sdk — no hand-rolled HTTP.

Install

npm install -g @agentdb/cli

Requires Node.js 18 or later.

Quick start

You need two credentials: an API key (AGENTDB_API_KEY) and a database token (AGENTDB_DB_TOKEN, a UUID). Get them from the AgentDB web UI.

Either export them as env vars:

export AGENTDB_API_KEY=sk_...
export AGENTDB_DB_TOKEN=00000000-0000-0000-0000-000000000000
agentdb list

…or save them to the on-disk config and forget about them:

agentdb config set apiKey sk_...
agentdb config set dbToken 00000000-0000-0000-0000-000000000000
agentdb list

Config resolution priority (highest wins): CLI flags → env vars → ~/.agentdb/config.json → built-in defaults.

Environment variables

| Variable | Purpose | | --------------------- | -------------------------------------------- | | AGENTDB_BASE_URL | Service URL (default https://api.agentdb.dev) | | AGENTDB_API_KEY | API key (alias: AGENTDB_AUTH_TOKEN) | | AGENTDB_DB_TOKEN | Database token (UUID) | | AGENTDB_DB_NAME | Database name (default database) | | AGENTDB_DB_TYPE | sqlite or duckdb (default sqlite) | | NO_COLOR | Disable ANSI colors |

Global flags

--base-url <url>       Service base URL
--auth-token <token>   API key
--db-token <token>     Database token (UUID)
--db-name <name>       Database name
--db-type <type>       sqlite | duckdb
--debug                Send debug=true with API calls
--format <fmt>         table | json | ndjson | csv
-o, --output <file>    Write output to file (- for stdout)
--no-color             Disable colored output

Output formats

• table (default) — ASCII table per result set, same shape as the legacy CLI.
• json — JSON.stringify of the full StatementResult[] array.
• ndjson — one JSON object per row; multi-statement batches add a statementIndex field.
• csv — RFC 4180 (CRLF, quote-escaped). Multi-statement batches add a statementIndex column.

Use -o <file> to write output anywhere; -o - (the default) writes to stdout.

Commands

agentdb sql [sql]

Execute one or more SQL statements. Semicolon-separated batches run in order; empty statements are skipped.

--param <value>            Positional ? parameter (repeatable)
--named-param key=value    Named :key parameter (repeatable)
-f, --file <path>          Read SQL from file (- for stdin)
--fail-fast                Stop at the first failing statement
--ordered-batch            Retry on transient failures
--max-retries <n>          Retry budget for --ordered-batch
--explain                  Prepend EXPLAIN QUERY PLAN and pretty-print

Example:

agentdb sql "SELECT * FROM users WHERE id = ?" --param 42

agentdb prompt <prompt>

Run a natural-language query against the configured database.

agentdb prompt "show me the five most recent orders"

agentdb list

List every database visible to the current dbToken.

agentdb list --format json

agentdb delete <name>

Delete a database. This is immediate and irreversible.

agentdb delete sandbox

agentdb rename <newName>

Rename the current database (the one selected by --db-name / config).

agentdb --db-name old-name rename new-name

agentdb copy <destName>

Copy a database. Use -s / -d to override the source / destination database tokens when copying across accounts.

agentdb copy staging-clone -s $SRC_TOKEN -d $DEST_TOKEN

agentdb upload <filePath>

Upload a local .sqlite / .duckdb file and register it as a database.

agentdb upload ./dump.sqlite

agentdb download <outputPath>

Download the current database to a local file.

agentdb download ./backup.sqlite

agentdb template ...

Manage database templates. Subcommands:

• list — list all templates.
• get <name> — print SQL + description for a template.
• create <name> — create from --sql-file and/or repeatable --sql-statement, with --description or --description-file.
• update <name> — replace SQL + description.
• delete <name> — delete a template. This is immediate and irreversible.
• info <name> — applied state of a template on the current database.
• apply <name> — apply a template to the current database.
• applied — list templates applied to the current database.
• upload <file> [--name <name>] — upload a file and create a template from it.

agentdb template apply schema-v1

agentdb mcp ...

Manage permanent MCP slug URLs.

• create --param key=value ... — create a slug; prints the slug and full URL.
• get <slug> — look up a slug and print its query parameters.

agentdb mcp create --param dbName=analytics --param dbType=duckdb

agentdb interactive

Launch the interactive REPL. Statements span multiple lines until a terminating ;. Meta-commands:

.help         Show help
.tables       List tables in the current database
.schema [tbl] Show CREATE TABLE for one or all tables
.use <name>   Switch current database
.format <fmt> Switch output format (table|json|ndjson|csv)
.timing       Toggle per-query timing display
.explain      Toggle EXPLAIN QUERY PLAN prefixing
.quit         Exit the REPL

agentdb config ...

Manage ~/.agentdb/config.json. Valid keys: baseUrl, apiKey, dbToken, dbName, dbType.

• set <key> <value> — write the value (file mode 0600, dir 0700).
• get <key> — print the stored value (exits non-zero if unset).
• unset <key> — remove the value (the file is deleted when empty).
• list — table of stored values; apiKey and long dbToken values are redacted to ****<last4>.
• path — print the absolute config file path.

agentdb config set apiKey sk_live_...
agentdb config list

agentdb health

Ping the service /health endpoint and print the JSON response. Exits non-zero on any non-2xx status.

agentdb health

What this CLI does not cover

A number of AgentDB endpoints require browser session authentication (cookie-based) and are therefore not exposed by this CLI. Use the web UI for:

• /api/keys — API key management.
• /api/tokens — database token management.
• /api/auth/* — sign-in / sign-out flows.
• /api/templates session-auth variant — only the Bearer-authed /db/api/templates endpoints are wired up here (see the template command).

All /db/api/* endpoints that accept Bearer auth are fully supported.

License

MIT. See LICENSE.