Use the CLI

Use lambdadb for project-scoped collection management, JSONL imports, queries, and ID-based fetches. To transfer data from Qdrant, Pinecone, or Elasticsearch with inventory, mappings, and checkpoints, use the separate Migration CLI.

Install

The stable release covered by this guide is 0.1.4. Choose one installation 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@0.1.4
lambdadb --version
lambdadb --help

To update to the current stable channel:

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

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 CLI 0.1.4 with its Node 24 runtime. No separate Node/npm setup is needed.

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; @dev is a separate prerelease channel. See CLI releases and the public tap for availability.

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.

Use an existing development project and replace the placeholders below. The endpoint is your region’s HTTPS API origin, without /projects/.... The CLI does not create projects or issue keys.

lambdadb configure --endpoint YOUR_REGION_BASE_URL --project YOUR_PROJECT_NAME

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

configure saves only the endpoint, project, and name of the key environment variable; it makes no service call. doctor checks authentication and collection-list access. Success does not prove write permission or search readiness.

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; files are limited to 64 MiB and 100,000 documents. 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 <= 100. 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. The CLI does not create or manage refs. Branches and aliases can move between calls.
If a query file contains ref, it must match --ref. Query size is 1–100 for document results; size: 0 requires nonempty facets for counts only. Fetch accepts up to 100 IDs.

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.

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	Value of the selected environment variable only; no fallback to another key
Config path	`--config`, `LAMBDADB_CONFIG`, default user path
Network timeout	`--timeout-ms`, `LAMBDADB_TIMEOUT_MS`, default `30000` milliseconds

Explicit empty values fail validation. An explicitly selected missing config file fails except when configure creates 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. No command accepts the raw API key as an argument. Config files are written atomically with mode 0600 on POSIX; only the variable name is persisted. 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

--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. 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 reports 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. The shared network budget covers retries, pages, batches, and large-result downloads. Use --timeout-ms 120000 for a longer operation. Optional --mode bulk uses bulk ingestion; it is unsupported for native embedding vector fields. See Bulk upsert data.

Next steps

Search overview for query types
Use with MCP 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

Configure a project

Create a collection and import JSONL

Query and fetch by ID

Native reranking

Bayesian hybrid search

Select collections and refs

Configuration and credentials

JSON output and failures

Next steps

​Install

​Configure a project

​Create a collection and import JSONL

​Query and fetch by ID

​Native reranking

​Bayesian hybrid search

​Select collections and refs

​Configuration and credentials

​JSON output and failures

​Next steps

Install

Configure a project

Create a collection and import JSONL

Query and fetch by ID

Native reranking

Bayesian hybrid search

Select collections and refs

Configuration and credentials

JSON output and failures

Next steps