nlq — CLI reference

nlqdb command-line tool. Two data verbs: ask (NL → answer) and run (raw SQL).

Global flags

Flag	Type	Default	Description
--api-url	string	—	override the API base URL (default: from config or https://app.nlqdb.com)
--json	bool	false	emit JSON output (default: human)
--no-update-check	bool	false	skip the once-per-day update check

Commands

nlq ask

Ask a question in plain English

nlq ask <goal>

Ask runs the /v1/ask pipeline. With –db it pins to a specific database (and fails if the DB doesn’t exist); without –db it resolves the active DB from ~/.config/nlqdb/state.json, creating a new one from the goal if there is none (SK-CLI-012).

Pass –json for machine-readable output.

Flags

Flag	Type	Default	Description
--confirm	bool	false	approve a destructive plan returned by an earlier call
--db	string	—	pin the call to this database id (errors if missing)
--engine	string	—	engine override on the create branch (postgres|clickhouse)
--model	string	—	model preset (auto|fast|best); best needs a BYOLLM key (nlq byollm set) or a paid plan

nlq byollm

Bring your own LLM provider key (0% markup)

nlq byollm

Route nlq ask through your own LLM provider key at 0% markup. The key is stored in your OS keychain (never config.toml) and sent only on nlq ask — never on nlq run, nlq keys, or any other call. The lane is signed-in only, so it activates once you run nlq login.

nlq byollm clear

Remove the stored BYOLLM credential

nlq byollm clear

nlq byollm set

Store a provider key (openai|anthropic|google-ai-studio|grok|openrouter)

nlq byollm set <provider> <model>

Store a BYOLLM credential. The key is read from –key, else from stdin — prefer stdin so the secret never lands in your shell history:

echo “$ANTHROPIC_API_KEY” | nlq byollm set anthropic claude-sonnet-5

Run interactively, the key is prompted for without echo. Provider is one of openai, anthropic, google-ai-studio, grok, or openrouter; model is the raw upstream id (e.g. claude-sonnet-5, gpt-5.6, or an OpenRouter id like openai/gpt-5.6).

Flags

Flag	Type	Default	Description
--key	string	—	provider API key (omit to read from stdin / prompt)

nlq byollm status

Show the stored BYOLLM credential (key redacted)

nlq byollm status

nlq db

Database management (list, create, connect)

nlq db

nlq db connect

Register an existing engine by its connection URL

nlq db connect

Connect registers an existing ClickHouse or Postgres database with nlqdb via POST /v1/db/connect, so nlq ask can query it.

The connection URL is a credential. Provide it via –url, pipe it on stdin, or let the interactive prompt read it without echo — prefer the latter two so the URL never lands in your shell history:

echo “$DATABASE_URL” | nlq db connect –engine postgres

The URL is sent to the API and discarded; it is never printed back and never written to config.toml or state.json.

Flags

Flag	Type	Default	Description
--engine	string	clickhouse	engine of the database to connect (clickhouse|postgres)
--name	string	—	optional display name for the connected database
--url	string	—	connection URL (omit to read from stdin / prompt — keeps it out of shell history)

nlq db create

Create a database explicitly (power-user verb)

nlq db create [name]

Create a database from an optional name and engine. Most users should prefer nlq new "<goal>" so the schema is inferred from the goal — this verb is the GLOBAL-015 escape hatch.

Flags

Flag	Type	Default	Description
--engine	string	—	engine override (postgres|clickhouse)

nlq db list

List databases visible to the current credential

nlq db list

nlq grants

Manage cross-tenant read grants (list, revoke)

nlq grants

nlq grants list

List cross-tenant grants you sold or hold

nlq grants list

nlq grants revoke

Revoke a grant by id (fails closed within ~30s)

nlq grants revoke <id>

Revoke a single grant by its id — the UUID shown by nlq grants list. Only the grant’s owner can revoke it. Revocation fails closed within the SK-EKP-008 bound (~30s, including in-flight queries); the buyer loses read access to your knowledge DB. Idempotent — re-revoking an already-revoked grant is a no-op, not an error.

nlq help

Help about any command

nlq help [command]

Help renders the command’s docs.

Pass –json to emit the full command tree as machine-readable JSON (consumed by apps/docs/scripts/gen-cli.ts to regenerate docs.nlqdb.com/cli/).

Flags

Flag	Type	Default	Description
--api-url	string	—	override the API base URL (default: from config or https://app.nlqdb.com)
-h, --help	bool	false	help for help
--json	bool	false	emit JSON output (default: human)
--no-update-check	bool	false	skip the once-per-day update check

nlq keys

Manage API keys (list, revoke)

nlq keys

nlq keys list

List API keys visible to the current credential

nlq keys list

nlq keys revoke

Revoke an API key by id (irreversible in this slice)

nlq keys revoke <id>

Revoke a single API key by its id. The id is the UUID column shown by nlq keys list. Revocation is hard — once a key is revoked, mint a fresh one to recover. MCP-host sessions holding the revoked key disconnect within ~1 second.

nlq login

Sign in via OAuth device-code flow (ships in the next slice)

nlq login

nlq login runs the OAuth 2.0 Device Authorization Grant per SK-CLI-006. The server-side endpoints (POST /v1/auth/device, POST /v1/auth/device/token) land in a follow-up slice; until then, set NLQDB_API_KEY or use anonymous mode (default).

nlq logout

Clear keychain credentials and local state

nlq logout

nlq mcp

MCP host helpers (detect, install)

nlq mcp

nlq mcp detect

List MCP hosts present on this machine

nlq mcp detect

nlq mcp install

Wire nlqdb into an MCP host (requires nlq login, ships next slice)

nlq mcp install [host]

mcp install mints a host-scoped sk_mcp_* key via POST /v1/keys and writes it into the host’s config (SK-CLI-011). The key-mint endpoint is session-only, so this verb requires the device-flow nlq login shipping in a follow-up slice. Until then, detection is exposed via nlq mcp detect.

nlq new

Create a database from a goal and run the first query

nlq new <goal>

Create a fresh DB from the goal, overwrite the active DB pointer in ~/.config/nlqdb/state.json, and immediately ask the goal against it.

This is sugar for the create branch of /v1/ask (SK-CLI-003).

Flags

Flag	Type	Default	Description
--engine	string	—	engine override (postgres|clickhouse)

nlq query

Ask a question against an explicit database

nlq query <db> <goal>

Pinned ask: nlq query <db> "<goal>" is the explicit form that errors when the database doesn’t exist. Same wire shape as nlq ask --db=<id>.

nlq remember

Write a typed memory row into an agent_memory_v1 database (no LLM)

nlq remember [--db <id>] <text>

Remember materialises a structured memory row via POST /v1/memory/remember. The server composes a deterministic parameterised INSERT — the LLM is never in the loop and you never write SQL. The target must be an agent_memory_v1 preset database (provisioned via the SDK/MCP db.create preset path); a normal DB is rejected with a wrong_preset error.

The positional <text> is the row’s primary content: • fact — the thing to remember (default kind) • episode — the message content (use –role to set the speaker) • entity — the entity’s canonical name (use –type to set its type)

DB resolution mirrors nlq ask: –db pins one, else the active DB from ~/.config/nlqdb/state.json (nlq use <db> switches it).

Examples: nlq remember “user prefers dark mode” nlq remember –type preference –tag ui “user prefers dark mode” nlq remember –ttl 7d “promo code expires next week” nlq remember –kind episode –role user “what’s my deal pipeline?” nlq remember –kind entity –type person “Alice Chen”

Pass –json for machine-readable output.

Flags

Flag	Type	Default	Description
--db	string	—	database id to write to (default: active DB)
--end-user	string	—	scope the row to an end-user id
--kind	string	fact	row kind: fact, episode, or entity
--role	string	—	episode speaker role, e.g. user/assistant (episode only)
--tag	stringArray	—	fact tag (repeatable; fact only)
--thread	string	—	scope the row to a thread id
--ttl	string	—	fact expiry, e.g. 7d / 24h / 30m (fact only)
--type	string	—	fact category or entity type (payload.kind)

nlq run

Run raw SQL against a database (escape hatch — no LLM)

nlq run [--db <id>] <sql>

Run executes raw SQL via POST /v1/run. The same SQL allow-list as nlq ask applies (SELECT / INSERT / UPDATE / DELETE / WITH / EXPLAIN / SHOW). DDL is rejected — use nlq new to provision schema.

DB resolution mirrors nlq ask: • –db pins to the given id and errors if it’s missing. • Without –db the active database from ~/.config/nlqdb/state.json is used. nlq use <db> switches it. • Pipe SQL on stdin to skip the positional argument: cat schema.sql | nlq run –db finance

Pass –json for machine-readable output.

Flags

Flag	Type	Default	Description
--db	string	—	database id to run against (default: active DB)

nlq update

Check for and (when applicable) install the latest nlq

nlq update

update prints the latest available version and either replaces the curl-installed binary in place or hints at the package-manager command for brew / npm. dev builds are inert (SK-CLI-015).

nlq use

Switch the active database for bare-form nlq "<goal>" calls

nlq use <db>

nlq whoami

Show the resolved identity and active database

nlq whoami