Use the CLI

Use lambdadb to sign in, list organizations, create and select projects, view usage, connect coding agents, and manage collections, documents, branches, tags, and aliases. For a guided first search with a coding agent, see Start with an AI agent. To transfer data from Qdrant, Pinecone, or Elasticsearch with inventory, mappings, and checkpoints, use the separate Migration CLI.

Install

This guide covers CLI 0.1.9. Install the latest stable release using one method, and check command -v lambdadb before switching package managers.

npm
Homebrew

Requires Node.js 22.14.0 or later and npm.

npm install --global @functional-systems/lambdadb-cli@latest
lambdadb --version
lambdadb --help

Run the same command again to update an existing installation.To remove:

npm uninstall --global @functional-systems/lambdadb-cli

On macOS or Linux with Homebrew:

brew install lambdadb/tap/lambdadb-cli
lambdadb --version
lambdadb --help

The public tap provides the CLI with its Node 24 runtime. No separate Node/npm setup is needed; a new release may reach the tap after npm.

brew update
brew upgrade lambdadb/tap/lambdadb-cli

To remove:

brew uninstall lambdadb/tap/lambdadb-cli

Installed copies do not update themselves. Pin an exact version for reproducible npm installs. See CLI releases and the public tap for availability.

Guided setup

Start with init to connect a project and optionally install coding-agent settings:

lambdadb init

Choose account login to sign in and approve the CLI in your browser, then select or create a project in the terminal. Project creation and new key issuance require explicit confirmation. The CLI saves account and project credentials in the OS credential store and non-secret references in its configuration. Account setup requires an accessible OS credential store; use environment-variable setup for CI or environments without one. On SSH or a machine without a visible browser, use lambdadb init --no-browser and open the printed approval URL on another device. Browser approval is still required. If a project is provisioning, select that existing project when it becomes active instead of creating another. You can then choose agents and review their configuration files; see Connect coding agents for scope and write-tool defaults. Choose Skip agent setup to configure only the CLI. init does not create collections or documents. Connection verification checks authentication and collection-list access, not write permission or search readiness.

Configure a project

LambdaDB Cloud uses region-specific API base URLs. Use your project’s base URL and project name, together with a project API key created in its API Keys tab. Project creation does not automatically issue a key; save the full value when you create it, because it is shown only once. See API key management. Do not assume a global default URL or a fixed project name.

For environment-variable setup, use an existing development project and replace the placeholders below. The endpoint is your region’s HTTPS API origin, without /projects/.... This path uses an existing project key and does not require account login.

lambdadb configure --endpoint YOUR_REGION_BASE_URL --project YOUR_PROJECT_NAME --api-key-env LAMBDADB_API_KEY

Supply the key through your shell or a CI secret manager. For example, in Bash, read it without putting the value in shell history:

read -r -s -p 'LambdaDB project API key: ' LAMBDADB_API_KEY
printf '\n'
export LAMBDADB_API_KEY
lambdadb doctor

This environment-variable setup saves the endpoint, project, and name of the key environment variable; configure makes no service call. Explicit --api-key-env selects environment mode even after an earlier init saved an OS credential reference. doctor checks authentication and collection-list access. Success does not prove write permission or search readiness.

Manage your account and projects

Account commands use a saved account login independently of the project key used for data commands. Keep the same --config path throughout if you override it. Only init prompts for choices; other commands require their arguments explicitly.

lambdadb login
lambdadb orgs list --json
lambdadb projects regions --json
lambdadb projects list --org-id ORG_UUID --json

login waits for browser approval and saves an account session; it does not select a project or configure agents. Use login --no-browser to approve from another device. Expired or unavailable account credentials require login or unlocking the OS store; ordinary management commands do not start login automatically. Replace ORG_UUID with an ID from orgs list. Account commands take organization and project UUIDs; the global --project NAME option selects a project by name for data commands.

Create and select a project

Choose a region returned by projects regions, then create a project in an existing organization:

lambdadb projects create --org-id ORG_UUID --name my-project --region REGION --json
lambdadb projects list --org-id ORG_UUID --json

For a new account without an organization, use --default-org instead of --org-id. Creation requires exactly one of those options plus --name and --region. It does not select the CLI default, issue a project key, or install agent settings. If the organization has reached its project limit, follow the reported billing guidance; only an organization owner can activate billing. Wait until the project reports ACTIVE, then use its UUID from projects list:

lambdadb projects use --org-id ORG_UUID --project-id PROJECT_UUID --issue-key
lambdadb doctor

First connection or deliberate key replacement requires --issue-key and organization Owner or Admin permission. To switch back to a project with a saved key, omit --issue-key:

lambdadb projects use --org-id ORG_UUID --project-id PROJECT_UUID

projects use changes the saved CLI connection. Existing agent settings stay pinned to their selected project; rerun init for the same agents and scope and approve the updated file plan to switch them too.

View usage

After account login, inspect usage for the saved project connection or select an organization explicitly:

lambdadb usage
lambdadb usage --org-id ORG_UUID --json
lambdadb usage --org-id ORG_UUID --project-id PROJECT_UUID --json

Environment-key setups or overridden targets need explicit IDs; a project key alone does not authorize usage. --project-id requires --org-id.

Plan	Report
Free	Current per-project read, write, storage, and inference usage against reported quotas; no price conversion. Historical quota windows are unavailable, so omit `--month`
Pay as You Go	Recorded usage and USD list-rate estimates for the current UTC month; requires organization Owner or Admin permission. Use `--month YYYY-MM` for a current or past month

For example, to inspect a paid project’s recorded October usage:

lambdadb usage --org-id ORG_UUID --project-id PROJECT_UUID --month 2026-10 --json

Usage can lag recent activity. Estimates are neither forecasts nor final invoices and exclude free allowances, credits, taxes, and billing rounding. Missing counters or prices remain unavailable; a total with unpriced metrics is a partial subtotal. JSON preserves paid usage totals and costs as decimal strings; Free quota counters are numbers. See Understanding costs for the billing model.

Sign out or remove a local key

lambdadb logout revokes the account session and removes it locally. It requires access to the saved OS entry and server connectivity; a failed revocation retains metadata. It does not revoke project keys or disconnect existing agents. lambdadb credentials remove deletes the selected connection’s local OS credential while retaining its metadata. Agents using that credential reference will need a usable credential again. It does not revoke the server key; revoke unused project keys in Console. For environment mode, remove the key from the shell or secret manager instead.

Connect coding agents

init installs MCP configuration and a LambdaDB usage skill for selected agents. Choose agents explicitly; detection does not preselect them or prove a working connection.

Agent	`--agents` value	Scope
Codex	`codex`	Project or user
Claude Code	`claude`	Project or user
Cursor editor/CLI	`cursor`	Project or user
VS Code	`vscode`	Project or user
Gemini CLI	`gemini`	Project or user
OpenCode	`opencode`	Project or user
GitHub Copilot CLI	`copilot`	Project or user
Kiro IDE/CLI	`kiro`	Project or user
Cline VS Code extension	`cline`	User only

--scope project writes agent files in the current working directory; run from your repository root. --scope user writes them in the agent’s user configuration. Scope does not change the selected LambdaDB project or CLI config path. Claude Desktop uses the manual MCP setup, not the claude adapter.

Setup mode	Scope and write tools
Guided `init`	Defaults to user scope and enabled MCP write tools. Review the file plan and use Change options to choose project scope or disable writes
`init --non-interactive`	Requires explicit `--agents` and `--scope`; write tools are disabled unless `--write-tools` is supplied

With an existing saved connection, install a read-only project-scoped connection for two agents:

lambdadb init --non-interactive --agents codex,claude --scope project --json

Add --write-tools to enable mutations, or use --agents none to configure only the CLI. For an existing environment-held key, pass the target and variable name explicitly:

lambdadb init --non-interactive --agents codex,claude --scope project \
  --endpoint YOUR_REGION_BASE_URL --project YOUR_PROJECT_NAME \
  --api-key-env LAMBDADB_API_KEY --json

Supply the key securely before running. Non-interactive setup applies the requested file plan without prompts; it does not log in or issue a key. In a non-TTY session or with --json, init requires --non-interactive. Generated agent settings pin the installed CLI version and launch its mcp command with the chosen target. CLI 0.1.9 launches MCP 0.3.0. The bridge reads the OS credential or selected environment variable at startup and forwards it to MCP without putting the key value in agent files or command arguments. OS-store connections require the same OS user and access to the unlocked store; environment-mode connections require the selected variable in the agent’s launch environment. GUI applications may not inherit terminal exports. After upgrading the CLI or changing projects, rerun init for the same agents and scope, review the changes, then restart or reload the agents. Reruns preserve unrelated settings and edited skills; conflicting custom MCP entries require manual resolution. Check the agent’s MCP tool list and make a small read to verify access. If a sandboxed CLI reports CREDENTIAL_STORE_ERROR, no server request was made. The agent can use the configured MCP connection after confirming that its endpoint and project match the CLI target; server authentication and permission failures must not be bypassed by switching connections. See the agent setup reference for configuration paths and per-agent reload instructions. To launch the bridge directly from an MCP client’s command configuration, use lambdadb mcp, adding --write-tools if needed. It is read-only by default and reserves stdout for MCP protocol traffic, so --json is not supported. The flag controls writes even if LAMBDADB_MCP_ENABLE_WRITE_TOOLS is set in the parent environment. See MCP connection methods for the distinction from launching the MCP package directly.

Create a collection and import JSONL

The CLI supports all 49 fixed text analyzer presets. For generated vectors, use the native embedding configuration in the same field-to-index map. The CLI also supports lambdadb collections update --collection NAME --index-config FILE with that map format. Existing field-update constraints still apply; see Configure a collection. Choose a new collection name in your development project. Run these examples in a scratch directory. Create an index configuration file containing the field-to-index map, without an indexConfigs wrapper:

cat > index-config.json <<'JSON'
{
  "text": { "type": "text", "analyzers": ["english"] },
  "category": { "type": "keyword" }
}
JSON

lambdadb collections create --collection cli-demo-docs --index-config index-config.json
lambdadb collections describe --collection cli-demo-docs

Create and import a UTF-8 JSONL file:

cat > documents.jsonl <<'JSONL'
{"id":"doc-1","text":"LambdaDB supports serverless search.","category":"database"}
{"id":"doc-2","text":"Developers can search documents using a shared CLI.","category":"developer-tools"}
{"id":"doc-3","text":"A successful write is accepted before committed search visibility is verified.","category":"database"}
JSONL

lambdadb docs import --collection cli-demo-docs --branch main --file documents.jsonl --json

--branch main explicitly selects the writable branch. Import validates the entire file before sending sequential batches. Each nonblank line must be a JSON object. See CLI limits for file size, document count, batch byte caps, and page sizes. Existing IDs are upserted, so replay can replace data. Omitted IDs are generated by the service and are not returned in the acceptance response; replay can create duplicates.

Creation reports state: "created"; successful import reports state: "accepted". Both report searchable: "not_verified". Accepted writes are not proof that indexing has completed or documents are searchable. After a delay, repeat reads and inspect the expected IDs and contents. Do not recreate the collection or replay imports as a waiting mechanism.

Query and fetch by ID

Save a query request and select the read ref explicitly:

cat > query.json <<'JSON'
{
  "size": 10,
  "query": { "queryString": { "query": "serverless", "defaultField": "text" } },
  "consistentRead": false
}
JSON

lambdadb query --collection cli-demo-docs --ref branch:main --file query.json --json
lambdadb docs fetch --collection cli-demo-docs --ref branch:main --ids doc-1 doc-2 doc-3 --json

After indexing, the query should include doc-1, and fetch should return the three IDs. Initial reads can be empty or encounter a transient loading error. A successful empty result still exits with 0; fetch includes missingIds for absent documents. For eligible pending ordinary writes, fetch can use:

lambdadb docs fetch --collection cli-demo-docs --ref branch:main --ids doc-1 --consistent-read --json

For query, set "consistentRead": true in the request file. These reads require a direct branch ref, exclude pending bulk imports, and can return 429. They do not establish committed indexing. See Data versioning. The CLI also accepts keyword facets and an omitted query for match-all requests. Use size: 0 with nonempty facets for counts without document results.

Native reranking

The CLI accepts the query-level rerank object through the same JSON request file. No separate reranking flags or provider API key are needed. Save this as rerank-query.json for the sample collection above:

{
  "size": 2,
  "query": { "queryString": { "query": "serverless", "defaultField": "text" } },
  "rerank": {
    "provider": "typesafe",
    "model": "jev-1.13.0",
    "queryText": "Which documents explain serverless search?",
    "fields": ["text"]
  }
}

lambdadb query --collection cli-demo-docs --ref branch:main --file rerank-query.json --json

Read data.rerank.status in the CLI JSON envelope. On applied results, data.docs contains final evaluation score and original retrievalScore alongside each doc. Fallback retains search scores and server order with scoredCount: 0; it does not expose partial evaluation scores. The CLI preserves numeric zero and precision, including downloaded results, and does not sort again. See Native reranking for custom criteria, candidate depth, eligible returnOriginal failures, and query/sort/facet restrictions.

Bayesian hybrid search

Save the complete Bayesian request as bayesian-query.json and run it against a collection with the example’s body and bodyEmbedding fields:

lambdadb query --collection semantic-docs --ref branch:main --file bayesian-query.json --json

Without reranking, supply top-level candidateSize with 1 <= size <= candidateSize within the candidate limit. With reranking, omit that field and use rerank.candidateSize. No separate fusion flags are needed; existing search defaults are unchanged.

Select collections and refs

Endpoint and project come from configuration, environment, or flags. --collection is required for collection-specific operations.
Import requires --branch NAME. Query and fetch require --ref branch:NAME, --ref tag:NAME, or --ref alias:NAME; the CLI does not silently select main.
Tags and aliases must already exist; see Branches, tags, and aliases. Branches and aliases can move between calls.
If a query file contains ref, it must match --ref. Query size must be positive for document results; size: 0 requires nonempty facets for counts only. See search and fetch limits for result and ID counts.

List, update, and delete documents

docs list pages through documents at a ref without ranking. Set --size within the CLI page limit; use --page-token with the returned nextPageToken, or --all to follow pages to the end within the network budget. An optional --file holds filter, partitionFilter, and fields:

lambdadb docs list --collection cli-demo-docs --ref branch:main --size 5 --json

cat > list-filter.json <<'JSON'
{
  "filter": { "queryString": { "query": "category:database" } },
  "fields": { "include": ["id", "text", "category"] }
}
JSON

lambdadb docs list --collection cli-demo-docs --ref branch:main --file list-filter.json --json

Use a tag for a stable export; a branch can advance and an alias can be retargeted between pages. List does not support consistent reads, and total counts the page, not the collection. docs update merges JSONL rows into existing documents. Every row needs a nonempty string id that already exists; omitted fields are kept, nested objects merge, arrays are replaced, and null is rejected for indexed fields. Batches run sequentially and stop at the first failure, with the same result fields and exit codes as import:

cat > updates.jsonl <<'JSONL'
{"id":"doc-1","category":"database","metadata":{"reviewed":true}}
{"id":"doc-2","category":"developer-tools"}
JSONL

lambdadb docs update --collection cli-demo-docs --branch main --file updates.jsonl --json

docs delete takes exactly one selector: --ids, or a --file with ids or a filter in the query DSL plus an optional partitionFilter. Deletion runs without confirmation and is reported as accepted; deleted documents can remain visible until the write commits. Preview a filter with docs list --file using the same filter first.

lambdadb docs delete --collection cli-demo-docs --branch main --ids doc-2 --json

cat > delete-filter.json <<'JSON'
{ "filter": { "queryString": { "query": "category:developer-tools" } } }
JSON

lambdadb docs delete --collection cli-demo-docs --branch main --file delete-filter.json --json

Manage collections

List collections with lambdadb collections list --json. One page is returned by default; use --page-token with the returned nextPageToken, or --all to fetch all pages within the network budget. collections create also accepts --description, repeated --tag KEY=VALUE metadata tags, --partition-config with a JSON object, and --snapshot-retention-days. collections update takes any combination of --index-config, --description ("" clears it), --tag or --clear-tags (replacing the whole tag map), and --snapshot-retention-days, following the collection update rules:

lambdadb collections update --collection cli-demo-docs --description "Support articles" --tag team=search --json
lambdadb collections update --collection cli-demo-docs --index-config index-config.json --json

Branches, tags, and aliases

The branches, tags, and aliases commands manage data versioning refs. Sources and targets use the same kind:NAME form as --ref:

lambdadb branches list --collection cli-demo-docs --json
lambdadb branches create --collection cli-demo-docs --branch candidate --json
lambdadb branches create --collection cli-demo-docs --branch replay --source branch:main --as-of 2026-10-01T00:00:00Z --json
lambdadb tags create --collection cli-demo-docs --tag release-one --source branch:candidate --json
lambdadb aliases create --collection cli-demo-docs --alias production --target tag:release-one --json
lambdadb aliases retarget --collection cli-demo-docs --alias production --target branch:main --json
lambdadb aliases delete --collection cli-demo-docs --alias production --json
lambdadb tags delete --collection cli-demo-docs --tag release-one --json
lambdadb branches delete --collection cli-demo-docs --branch candidate --json

branches create copies the committed state of a branch (--source branch:NAME, default main); tags create pins the committed snapshot of a branch or tag. Pending writes are not included in either. --as-of takes Unix epoch milliseconds or an ISO 8601 time and applies to branch sources only. Aliases are read names for a branch or tag, never write targets or targets of other aliases, and retarget changes what every reader of the alias sees immediately. Deletes take effect without confirmation. The server refuses to delete main and refuses to delete a branch or tag while an alias references it (HTTP 409); list aliases, then retarget or delete them first. Mutations are never retried; an unverifiable outcome exits with code 5, so list the refs before retrying.

Clean up the example collection

After completing the examples, use collections delete to permanently remove the collection with all documents, branches, tags, and aliases, without confirmation:

lambdadb collections delete --collection cli-demo-docs --json

CLI limits

These local limits apply to the documented CLI release. They apply in addition to LambdaDB service limits; raising a batch setting does not increase an API limit. MiB means 1,048,576 bytes; the --batch-bytes values below are exact byte counts.

Operation	Limit	Behavior and guidance
`docs import` and `docs update` input	64 MiB per JSONL file; 100,000 documents	The whole file is validated before sending batches; split larger files
import/update `--batch-size`	1–10,000 documents; default 1,000	The byte cap can make a batch smaller
upsert/update `--batch-bytes`	64–4,000,000 bytes; default 4,000,000	Serialized request cap, including the envelope
bulk `--batch-bytes`	64–64,000,000 bytes; default 16,000,000	Serialized upload cap; this is lower than the service bulk limit
`docs list --size`	1–100; default 20	Use pagination or `--all` for more

Configuration and credentials

The default config path is ${XDG_CONFIG_HOME:-$HOME/.config}/lambdadb/config.json. It is user-local, not discovered from the working repository. The CLI does not load .env files.

Setting	Precedence, highest first
Endpoint	`--endpoint`, `LAMBDADB_ENDPOINT`, saved `endpoint`
Project	`--project`, `LAMBDADB_PROJECT`, saved `project`
Key variable name	`--api-key-env`, `LAMBDADB_API_KEY_ENV`, saved `apiKeyEnv`, default `LAMBDADB_API_KEY`
Key value	Explicit `--api-key-env` or `LAMBDADB_API_KEY_ENV` selects environment mode; otherwise use the saved OS credential reference when present, else the selected variable. An explicit OS reference in generated agent arguments stays bound to its store. No automatic fallback on read failure
Config path	`--config`, `LAMBDADB_CONFIG`, default user path
Network timeout	`--timeout-ms`, `LAMBDADB_TIMEOUT_MS`, default `30000` milliseconds

Explicit empty values fail validation. Data commands fail if an explicitly selected config file is missing; configure and init can create it. configure uses the same precedence when saving settings. For a different secret variable, use lambdadb configure --api-key-env MY_PROJECT_KEY, then supply MY_PROJECT_KEY in the process environment. Setting only the key value in an environment variable does not override a saved OS credential reference. No command accepts the raw API key as an argument. Config files are written atomically with mode 0600 on POSIX and contain connection settings and non-secret credential metadata, never the key value. Environment mode saves the variable name; account setup adds credentialStore, credentialId, credentialKeyId, and credentialKeyName. Avoid shell tracing around secrets. The active key is redacted from output, but document contents remain visible. SDK debug logging is disabled even if LAMBDADB_DEBUG is set.

JSON output and failures

For ordinary CLI commands, --json emits one object and a newline on stdout, including command failures. It uses schemaVersion: 1, command, ok, and optional target, data, and error. Diagnostics go to stderr. Help and version remain plain text; mcp uses stdout for MCP protocol traffic instead. Invoke the executable directly for machine-readable output.

Exit code	Meaning
`0`	Success, including empty results and write acceptance
`2`	Invalid input, file, request, configuration, or missing credentials
`3`	API/request failure, or import with no accepted or unknown batches
`4`	Partial import: some accepted records, no unknown outcomes
`5`	At least one write outcome is unknown; inspect before retrying

Import and update report accepted, failed, unknown, and notAttempted counts plus batch line ranges. A timeout or disconnect after dispatch can mean an unknown outcome. There are no automatic write retries, durable checkpoints, or resume support in the general CLI. Inspect the target and report before constructing a retry. For data commands, the shared network budget covers retries, pages, batches, and large-result downloads. Account, project, and usage commands apply --timeout-ms to each HTTP request; it does not bound browser approval, prompts, or project provisioning. Use --timeout-ms 120000 for a longer request budget. Optional --mode bulk on docs import uses bulk ingestion, which never generates native embeddings; a record with a present source must supply its native vector directly. See Bulk upsert data. Management mutations are never retried automatically. An uncertain project creation or key issuance exits with code 5 and data.state: "unknown"; inspect the project list or named key in Console before retrying. See the account command reference for session recovery.

Next steps

Search overview for query types
Use the MCP server for assistant-driven access
Migration CLI for transfers from other databases
CLI repository for source builds and maintainer documentation

Get started

Migrations

Collections

Data versioning

Documents

Search

Manage Costs

Security

Install

Guided setup

Configure a project

Manage your account and projects

Create and select a project

View usage

Sign out or remove a local key

Connect coding agents

Create a collection and import JSONL

Query and fetch by ID

Native reranking

Bayesian hybrid search

Select collections and refs

List, update, and delete documents

Manage collections

Branches, tags, and aliases

Clean up the example collection

CLI limits

Configuration and credentials

JSON output and failures

Next steps

​Install

​Guided setup

​Configure a project

​Manage your account and projects

​Sign in and list organizations

​Create and select a project

​View usage

​Sign out or remove a local key

​Connect coding agents

​Create a collection and import JSONL

​Query and fetch by ID

​Native reranking

​Bayesian hybrid search

​Select collections and refs

​List, update, and delete documents

​Manage collections

​Branches, tags, and aliases

​Clean up the example collection

​CLI limits

​Configuration and credentials

​JSON output and failures

​Next steps

Install

Guided setup

Configure a project

Manage your account and projects

Sign in and list organizations

Create and select a project

View usage

Sign out or remove a local key

Connect coding agents

Create a collection and import JSONL

Query and fetch by ID

Native reranking

Bayesian hybrid search

Select collections and refs

List, update, and delete documents

Manage collections

Branches, tags, and aliases

Clean up the example collection

CLI limits

Configuration and credentials

JSON output and failures

Next steps