CLI reference

Reference · CLI

The askdb binary covers the full local workflow: scaffolding a project, introspecting a database, authoring schema artifacts, and asking questions. All commands use the same @askdb/core pipeline as the library.

Install

npm

npm install askdb
npx askdb --help

pnpm

pnpm add askdb
pnpm exec askdb --help

yarn

yarn add askdb
yarn askdb --help

For global install:

npm

npm install -g askdb
askdb --help

pnpm

pnpm add -g askdb
askdb --help

yarn

yarn global add askdb
askdb --help

Commands

askdb init

Scaffolds a tailored askdb.config.ts and installs only the packages your setup needs. In a TTY it opens a short wizard; in CI or with --yes it runs silently.

npx askdb@latest init          # wizard in a terminal
npx askdb@latest init --yes    # non-interactive, Postgres + OpenAI defaults

General flags

Flag	Description
-y, --yes	Accept defaults without prompts.
--interactive	Force wizard mode; errors if stdin/stdout are not TTYs.
--no-interactive	Never prompt; use defaults or flags.
--path <file>	Write the config to a custom path.
--force	Overwrite an existing file.
--skip-install	Only write the file; don’t install packages.

Database flags

Flag	Description
--database <db>	postgres | mysql | sqlite | sqlserver | prisma
--connection-env <name>	Env var name for the connection URL.
--sqlite-file <path-or-env>	SQLite file path or env var name.
--prisma-schema <path>	Path to schema.prisma.
--schema-out <dir>	Schema output directory (default ./askdb).

AI flags

Flag	Description
--ai-provider <name>	openai | anthropic | google | azure | foundry
--ai-key-env <name>	Env var name for the API key.
--ai-model-env <name>	Env var name for the model override.

RAG flags

Flag	Description
--rag-store <name>	file | memory | pgvector (default file)
--pgvector-env <name>	Env var name for the pgvector connection URL.

Studio flags

Flag	Description
--studio-execute	Enable Studio execute (query playground).
--no-studio-execute	Disable Studio execute.

init generates only the config branches you selected — SQL Server users won’t see a pg import, SQLite users get a file: field instead of DATABASE_URL, and Prisma users don’t get a live DB driver unless they explicitly enable Studio execute. It does not create a .env — example variable names live inside askdb.config.ts.

askdb introspect

Reads your database (or a Prisma schema file) and writes an AskDB schema artifact to disk.

askdb introspect \
  --url "$DATABASE_URL" \
  --out ./my-app.schema \
  --schema-id my-app

Flag	Description
--url <connstr>	Live database connection string.
--engine <id>	Engine override: postgres, mysql, sqlite, sqlserver, prisma.
--prisma-schema <path>	.prisma file or directory. With --engine prisma.
--from-export <bundle-dir>	Introspect from a previously exported bundle directory instead of a live connection. Postgres only. Mutually exclusive with --url.
--out <dir>	Output directory for the schema artifact. Falls back to introspection.outputDir in askdb.config.ts.
--schema-id <id>	Identifier embedded in schema.json.
--schemas <list>	Comma-separated database schemas to include (e.g. public,sales).
--exclude-schemas <list>	Comma-separated database schemas to skip.
--tables <list>	Comma-separated tables to include. Repeatable — values accumulate.
--print	Print the introspection result without writing.
--diff <existing>	Diff against an existing schema artifact.

askdb introspect also accepts the shared logging flags.

Live introspection requires the matching engine driver (pg, mysql2, better-sqlite3, or mssql) in the project running askdb, or supplied in the same one-off command:

pnpm dlx -p askdb -p pg askdb introspect --engine postgres --url "$DATABASE_URL"
npx -p askdb -p mssql askdb introspect --engine sqlserver --url "$SQLSERVER_URL"

askdb enrich

Alias of askdb studio: opens Studio for authoring per-table descriptions, aliases, concepts, and sensitive markers.

askdb enrich --schema ./my-app.schema

Flag	Description
-s, --schema <path>	Path to the schema artifact.

askdb studio

Launches Studio — the browser-based authoring UI — pointed at your schema artifact.

askdb studio --schema ./my-app.schema

Flag	Description
-s, --schema <path>	Path to the schema artifact.
--port <n>	Override the listen port (default 5556; or set studio.listen.port in config).
--host <host>	Override the bind host (default 127.0.0.1; or set studio.listen.host in config).

Requires @askdb/studio to be installed (lazy-imported on first use). Studio schema browsing, enrichment, and SQL generation do not require a database driver; the optional Playground execute path requires the matching driver (pg, mysql2, better-sqlite3, or mssql). askdb init --studio-execute installs the correct driver automatically.

askdb studio is the one command that also works before setup: run it with no config (or no schema artifact) and Studio opens a guided setup wizard in the browser that scaffolds both. An explicit --schema pointing at a missing directory is an error, since you asked for a specific artifact.

askdb bundle

Writes the entire schema artifact (physical layer + enrichment + tenant policy) as a single JSON file for distribution.

askdb bundle ./my-app.schema --out ./my-app.schema.bundle.json

askdb ask

Generates SQL from a natural-language question against a loaded schema artifact.

askdb ask \
  --schema ./my-app.schema \
  --question "Top 5 customers by lifetime value"

Flag	Description
-s, --schema <path>	Path to the schema artifact. Optional — defaults to the configured introspection.outputDir, or ./askdb/.
-q, --question <text>	The natural-language question (required).
--mode <mode>	Operating mode: schema_only (default) or bounded_results.
--explain	After the SQL, print a JSON block describing the heuristic guardrails satisfied.
--omit-sensitive-from-prompt	Exclude sensitive columns from the prompt entirely.
--mock-sql <sql>	Deterministic output for tests — bypasses the live model call.

askdb ask also accepts the shared logging flags.

You never pass a SQL dialect — it resolves automatically: dialect in askdb.config.ts when set, otherwise the engine recorded in the schema artifact at introspection time, otherwise postgres.

askdb ask returns the validated SQL on stdout. Execution is not part of the CLI.

Shared logging flags

askdb ask, askdb introspect, and the askdb-rag binary all accept the same structured-logging flags:

Flag	Description
-v, --verbose	Emit structured JSON log events (level info) to stderr.
--log-level <level>	trace, debug, info, warn, error, fatal, or silent. Default reads logging.level from askdb.config.ts.
--log-file <path>	Append structured JSON logs to a file.
--log-stdout	Mirror structured JSON logs to stdout.
--correlation-id <id>	Tag every log event with a correlation ID of your choosing.

The askdb-rag binary

@askdb/rag ships its own small binary with three commands.

askdb-rag setup-store

Provisions the pgvector schema for @askdb/rag idempotently. Safe to run in CI / deploy steps.

askdb-rag setup-store --pg-url "$DATABASE_URL" --dimensions 1536

Flag	Description
--pg-url <connstr>	Postgres connection string (required).
--pg-table <name>	Custom table name. Default askdb_rag_chunks.
--dimensions <n>	Embedding dimensions. Default 1536.

askdb-rag index

Chunks and embeds a schema artifact into the configured store — the CLI equivalent of buildSchemaIndex.

askdb-rag index ./my-app.schema --store pgvector --embedder openai

Flag	Description
--store <id>	memory, file (default — persists next to the artifact), or pgvector.
--embedder <id>	mock (default, deterministic, CI-safe) or openai (reads OPENAI_API_KEY, or pass --api-key).
--embedder-model <id>	Embedding model. Default text-embedding-3-small.
--dimensions <n>	Embedding dimensions, when the model needs them specified.
--pg-url / --pg-table	pgvector connection when --store pgvector.

askdb-rag query

Runs a similarity query against an indexed store — useful for checking what retrieval would hand the model.

askdb-rag query ./my-app.schema --question "customer signups" -k 8

Flag	Description
--question <text>	The query text (required).
-k <n>	Top-k chunks to return. Default 8.
--types <list>	Restrict chunk types, e.g. table,column,cql.

All three commands accept the shared logging flags.

Exit codes

Code	Meaning
0	Success.
1	Generic error (config, IO, generation, validation).
2	Invalid CLI arguments.

Errors print to stderr in human form; structured log events (with -v) follow the contract in @askdb/core logging.

Read next

ConfigurationdefineConfig, env vars, and how the CLI resolves settings.Package referenceWhat each @askdb/* package adds to the CLI.