> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lambdadb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Use the CLI

> Install the LambdaDB CLI, configure a project, import JSONL, and query or fetch documents from your terminal.

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](/guides/migrations/overview).

## Install

The stable release covered by this guide is `0.1.0`. Choose one installation method and check `command -v lambdadb` before switching package managers.

<Tabs>
  <Tab title="npm">
    Requires Node.js **22.14.0 or later** and npm.

    ```bash theme={null}
    npm install --global @functional-systems/lambdadb-cli@0.1.0
    lambdadb --version
    lambdadb --help
    ```

    To update to the current stable channel:

    ```bash theme={null}
    npm install --global @functional-systems/lambdadb-cli@latest
    ```

    To remove:

    ```bash theme={null}
    npm uninstall --global @functional-systems/lambdadb-cli
    ```
  </Tab>

  <Tab title="Homebrew">
    On macOS or Linux with [Homebrew](https://brew.sh/):

    ```bash theme={null}
    brew install lambdadb/tap/lambdadb-cli
    lambdadb --version
    lambdadb --help
    ```

    The public tap installs the stable CLI and its Node 24 runtime. No separate Node/npm setup is needed.

    ```bash theme={null}
    brew update
    brew upgrade lambdadb/tap/lambdadb-cli
    ```

    To remove:

    ```bash theme={null}
    brew uninstall lambdadb/tap/lambdadb-cli
    ```
  </Tab>
</Tabs>

Installed copies do not update themselves. Pin an exact version for reproducible npm installs; `@dev` is a separate prerelease channel. See [CLI releases](https://github.com/lambdadb/lambdadb-cli/releases) and the [public tap](https://github.com/lambdadb/homebrew-tap) for availability.

## Configure a project

<Note>
  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](/guides/get-started/quickstart#manage-api-keys). Do not assume a global default URL or a fixed project name.
</Note>

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.

```bash theme={null}
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:

```bash theme={null}
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

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:

```bash theme={null}
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:

```bash theme={null}
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.

<Note>
  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.
</Note>

## Query and fetch by ID

Save a query request and select the read ref explicitly:

```bash theme={null}
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:

```bash theme={null}
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](/guides/data-versioning/branches-tags-aliases).

### 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, and 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 managed embedding vector fields. See [Bulk upsert data](/guides/documents/bulk-upsert-data).

## Next steps

* [Search overview](/guides/search/search-overview) for query types
* [Use with MCP](/guides/get-started/use-with-mcp) for assistant-driven access
* [Migration CLI](/guides/migrations/overview) for transfers from other databases
* [CLI repository](https://github.com/lambdadb/lambdadb-cli) for source builds and maintainer documentation