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 install askdb
npx askdb --help

For global install:

npm install -g askdb
askdb --help

Commands

askdb init

Scaffolds askdb.config.ts (and adds @askdb/config + dotenv to your project) so the rest of the CLI can resolve config.

npx askdb init

Flag	Description
--path <file>	Write the template to a custom path.
--force	Overwrite an existing askdb.config.ts.
--skip-install	Only write the file; don’t install packages.

init doesn’t create a .env — example keys live in comments inside askdb.config.ts. It intentionally skips config loading so a broken config can’t block scaffolding.

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.
--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.
--print	Print the introspection result without writing.
--diff <existing>	Diff against an existing schema artifact.

askdb enrich

Launches the TUI for authoring per-table descriptions, aliases, concepts, and sensitive markers.

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

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

Requires @askdb/tui to be installed (the CLI lazy-imports it).

askdb studio

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

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

Flag	Description
--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).

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.
--log-level <level>	Log level (default reads from logging.level in askdb.config.ts).
-v, --verbose	Show structured log events.

There is no dialect flag: the dialect resolves from dialect in askdb.config.ts, falling back to the provider recorded in the schema artifact at introspection time, then to postgres.

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

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.

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.