> ## Documentation Index
> Fetch the complete documentation index at: https://cortex-e852fafe-auto-update-openapi-6a9e3873a7492d091ac8c1f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# HydraDB CLI

> Agent-friendly command line interface for HydraDB. Query context, ingest knowledge and memories, and inspect stored data from the terminal.

## Quick Start

<Steps>
  <Step title="Install the CLI">
    <Tabs>
      <Tab title="curl">
        ```bash theme={null}
        curl -fsSL https://cli.hydradb.com/install | bash
        ```

        Installs the wheel from the latest [GitHub release](https://github.com/hydra-db/hydradb-cli/releases).
        Uses `pipx` when available so the CLI stays isolated, and falls back to
        `pip install --user`.
      </Tab>

      <Tab title="pip">
        ```bash theme={null}
        pip install https://github.com/hydra-db/hydradb-cli/releases/download/v0.2.0/hydradb_cli-0.2.0-py3-none-any.whl
        ```
      </Tab>
    </Tabs>

    <Note>
      Requires Python 3.10 or later, and `hydradb-cli` 0.2.0 for the commands and flags on
      this page. On earlier versions, see [Deprecated aliases](#deprecated-aliases).
    </Note>

    <Warning>
      `pip install hydradb-cli` installs **0.1.0**, which predates every command name on
      this page. PyPI publishing is paused, so releases are served from GitHub until it
      resumes. Use one of the commands above.
    </Warning>
  </Step>

  <Step title="Get credentials">
    * Create an API key from [Hydra DB](https://app.hydradb.com/keys)
    * Create or copy your database ID from the [HydraDB dashboard](https://app.hydradb.com/databases)
  </Step>

  <Step title="Authenticate">
    ```bash theme={null}
    hydradb login --database my-db
    ```

    You are prompted for your API key. Both it and the database are saved to
    `~/.hydradb/config.json` (file permissions `0600`).

    For scripts and agents, pass the key explicitly instead of being prompted:

    ```bash theme={null}
    hydradb login --api-key "$HYDRADB_API_KEY" --database my-db
    ```

    <Tip>
      Agents can skip `login` altogether  -  every command reads `HYDRADB_API_KEY` and
      `HYDRADB_DATABASE` directly from the environment, so no credential is written to
      disk. It also keeps the key out of `ps` output, which shows any value passed as a
      command-line argument to every other user on the machine.
    </Tip>
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    hydradb doctor
    ```

    Reports your resolved config and whether the API is reachable.
  </Step>
</Steps>

## Configuration

### Authentication

The CLI resolves credentials in this order (first match wins):

1. Environment variables (`HYDRADB_API_KEY`, `HYDRADB_DATABASE`)
2. Config file (`~/.hydradb/config.json`, written by `hydradb login`)

<Tabs>
  <Tab title="macOS/Linux (bash)">
    ```bash theme={null}
    echo 'export HYDRADB_API_KEY="your-api-key"' >> ~/.bashrc
    echo 'export HYDRADB_DATABASE="your-database-id"' >> ~/.bashrc
    source ~/.bashrc
    ```
  </Tab>

  <Tab title="macOS/Linux (zsh)">
    ```bash theme={null}
    echo 'export HYDRADB_API_KEY="your-api-key"' >> ~/.zshrc
    echo 'export HYDRADB_DATABASE="your-database-id"' >> ~/.zshrc
    source ~/.zshrc
    ```
  </Tab>

  <Tab title="Windows (PowerShell)">
    ```powershell theme={null}
    [System.Environment]::SetEnvironmentVariable("HYDRADB_API_KEY", "your-api-key", "User")
    [System.Environment]::SetEnvironmentVariable("HYDRADB_DATABASE", "your-database-id", "User")
    ```
  </Tab>
</Tabs>

### Environment Variables

| Variable             | Description                               | Default                   |
| -------------------- | ----------------------------------------- | ------------------------- |
| `HYDRADB_API_KEY`    | Your HydraDB API key                      | *Required*                |
| `HYDRADB_DATABASE`   | Your HydraDB database identifier          | *Required*                |
| `HYDRADB_COLLECTION` | Collection for data partitioning          | -                         |
| `HYDRADB_BASE_URL`   | API base URL                              | `https://api.hydradb.com` |
| `HYDRADB_OUTPUT`     | Default output format (`human` or `json`) | `human`                   |

<Note>
  The older `HYDRA_DB_API_KEY`, `HYDRA_DB_TENANT_ID`, `HYDRA_DB_SUB_TENANT_ID`,
  `HYDRA_DB_BASE_URL` and `HYDRADB_API_URL` spellings are still read, but each prints a
  one-line deprecation warning to stderr. The canonical name wins when both are set.
</Note>

### Output Formats

Every command supports `--output human` (default, Rich-formatted tables) or
`--output json` (machine-readable). Set the default globally with the environment
variable:

```bash theme={null}
export HYDRADB_OUTPUT=json
```

Or per-command, before the subcommand:

```bash theme={null}
hydradb -o json list --database my-db
```

<Note>
  Warnings and errors always go to stderr, so `--output json` stdout stays a clean
  document you can pipe straight into `jq`.
</Note>

### Persistent Configuration

```bash theme={null}
hydradb config show
hydradb config set database my-db
```

`hydradb config set` accepts `api_key`, `database`, `collection` and `base_url`.
Environment variables always take precedence over the config file.

## Commands

Every command that reads or writes data takes `--database` (`-d`) to choose the
database, and `--collection` to scope to a partition within it. Both fall back to
your configured defaults, so the examples below can omit them once `hydradb login`
has run.

### Context Operations

| Command                       | Description                                                       |
| ----------------------------- | ----------------------------------------------------------------- |
| `hydradb query QUERY`         | Retrieve knowledge or memories - the single retrieval entry point |
| `hydradb ingest`              | Store a memory, knowledge text, or knowledge file(s)              |
| `hydradb list`                | List ingested sources and memories                                |
| `hydradb inspect SOURCE_ID`   | Fetch a source's content by ID                                    |
| `hydradb delete IDS...`       | Delete memories or knowledge sources by ID                        |
| `hydradb relations SOURCE_ID` | Explore knowledge-graph relations for a source                    |
| `hydradb verify IDS...`       | Check per-source ingestion status                                 |

#### Ingesting

`ingest` stores a memory by default. Pass `--kind knowledge` for knowledge text, or
give it file paths - files are always knowledge sources.

```bash theme={null}
# Store a memory
hydradb ingest --text "The user prefers dark mode and uses VS Code" --database my-db

# Store knowledge text
hydradb ingest --kind knowledge --text "Project uses PostgreSQL 15 with pgvector" --database my-db

# Upload one or more files
hydradb ingest ./docs/architecture.md ./docs/runbook.md --database my-db

# Read from stdin
cat notes.txt | hydradb ingest --database my-db
```

| Option                     | Description                                                  |
| -------------------------- | ------------------------------------------------------------ |
| `--kind`                   | `memory` (default) or `knowledge`                            |
| `--text`, `-t`             | Text to ingest. Use `-` to read from stdin                   |
| `--title`                  | Optional title                                               |
| `--source-id`              | Client-assigned source identifier                            |
| `--user-name`              | User name (memory only)                                      |
| `--infer` / `--no-infer`   | Extract insights and build the knowledge graph (default on)  |
| `--markdown`               | Treat text as markdown (memory only)                         |
| `--upsert` / `--no-upsert` | Update existing items with the same `source_id` (default on) |

<Note>
  `--text`, `--title`, `--source-id`, `--user-name`, `--markdown` and `--no-infer` do not
  apply to file ingest. Passing them alongside file arguments is rejected rather than
  silently ignored.
</Note>

#### Querying

```bash theme={null}
# Search knowledge
hydradb query "How is authentication implemented?" --kind knowledge --database my-db

# Search memories
hydradb query "What IDE does the user prefer?" --kind memory --database my-db

# Deterministic keyword search
hydradb query "PostgreSQL migration" --operator and --database my-db
```

| Option                                   | Description                                                                       |
| ---------------------------------------- | --------------------------------------------------------------------------------- |
| `--kind`                                 | Corpus to query: `memory` or `knowledge`. Omit to search both                     |
| `--operator`                             | Keyword operator: `or`, `and`, or `phrase`                                        |
| `--max-results`, `-n`                    | Maximum results, 1–50 (default `10`)                                              |
| `--mode`, `-m`                           | Retrieval mode: `fast` or `thinking`                                              |
| `--alpha`                                | Hybrid search weight (`0.0` keyword → `1.0` semantic)                             |
| `--recency-bias`                         | Preference for newer content (`0.0`–`1.0`)                                        |
| `--graph-context` / `--no-graph-context` | Include knowledge graph relations                                                 |
| `--context`                              | Additional context to guide retrieval                                             |
| `--title`                                | Restrict the search to documents with this exact title, ignoring case. Repeatable |

#### Filtering by document title

Use `--title` when you know document names but not their source IDs. Repeat the flag
for several titles; they are ORed.

```bash theme={null}
hydradb query "What changed in the rollout plan?" --title "Q3 Roadmap.md" --database my-db
hydradb query "ownership" --title "Q3 Roadmap.md" --title "Launch Plan.md" --database my-db
```

* **Exact, complete titles.** `--title last-usage` does not match `last-usage.csv`.
* **Case-insensitive.** `--title "q3 roadmap.md"` matches `Q3 Roadmap.md`.
* **Surrounding whitespace is trimmed**, and repeated values are de-duplicated.
  Punctuation such as commas is part of the title, so quote it:
  `--title "Smith, John"`.
* **No match returns an empty result** rather than widening to the whole corpus.

<Note>
  Because matching ignores case, two documents whose names differ only by case -
  `Report.md` and `report.md` - are treated as the same title and both are returned.
</Note>

#### Inspecting and deleting

```bash theme={null}
# List what is stored
hydradb list --kind knowledge --database my-db

# Read one source back
hydradb inspect 39e8872d-1c4a-4f0b-9c1e-7d2a5b8e4f10 --database my-db

# Check indexing progress
hydradb verify 39e8872d-1c4a-4f0b-9c1e-7d2a5b8e4f10 --database my-db

# Delete (prompts unless --yes)
hydradb delete 39e8872d-1c4a-4f0b-9c1e-7d2a5b8e4f10 --kind knowledge --database my-db --yes
```

`list` accepts `--kind`, `--page` and `--page-size` (1–100). `inspect` accepts
`--mode content` (default), `url`, or `both`. `delete` defaults to `--kind knowledge`,
so pass `--kind memory` to remove a memory.

### Database Management

| Command                                   | Description                                                 |
| ----------------------------------------- | ----------------------------------------------------------- |
| `hydradb database create DATABASE`        | Create a new database                                       |
| `hydradb database list`                   | List all databases for the authenticated user               |
| `hydradb database collections [DATABASE]` | List collections within a database                          |
| `hydradb database stats [DATABASE]`       | Row-count statistics                                        |
| `hydradb database readiness [DATABASE]`   | Whether the database is provisioned and ready for ingestion |
| `hydradb database monitor [DATABASE]`     | Merged stats + readiness                                    |
| `hydradb database delete DATABASE`        | Delete a database and all its data (irreversible)           |

```bash theme={null}
hydradb database create my-db
hydradb database readiness my-db
hydradb database delete my-db --yes
```

<Warning>
  `hydradb database delete` permanently removes the database and all associated memories,
  knowledge, and graph data. This action cannot be undone. It prompts for confirmation
  unless you pass `--yes`.
</Warning>

### Authentication & Configuration

| Command                        | Description                                                   |
| ------------------------------ | ------------------------------------------------------------- |
| `hydradb login`                | Authenticate and save credentials to `~/.hydradb/config.json` |
| `hydradb logout`               | Remove stored credentials                                     |
| `hydradb doctor`               | Check resolved config and API reachability                    |
| `hydradb config show`          | Show current CLI configuration                                |
| `hydradb config set KEY VALUE` | Set `api_key`, `database`, `collection`, or `base_url`        |

### Deprecated aliases

The command groups below still work and behave identically, but each prints a
deprecation warning to stderr naming its replacement. They will be removed in a future
major version.

| Deprecated                                            | Use instead                   |
| ----------------------------------------------------- | ----------------------------- |
| `memories add`                                        | `ingest`                      |
| `memories list`, `fetch sources`                      | `list`                        |
| `memories delete`, `knowledge delete`                 | `delete`                      |
| `knowledge upload`, `knowledge upload-text`           | `ingest`                      |
| `knowledge verify`                                    | `verify`                      |
| `recall full`, `recall preferences`, `recall keyword` | `query --kind … --operator …` |
| `fetch content`                                       | `inspect`                     |
| `fetch relations`                                     | `relations`                   |
| `tenant …`                                            | `database …`                  |
| `whoami`                                              | `doctor`                      |
| `--tenant-id`, `--sub-tenant-id`                      | `--database`, `--collection`  |

## Scripting & Automation

The CLI is designed for both interactive use and scripting. Use `--output json` to get
machine-readable output that pipes cleanly into `jq`, Python, or other tools:

```bash theme={null}
# List sources as JSON and pull out their IDs
hydradb -o json list --database my-db | jq '.sources[].id'

# Query and extract just the matched text
hydradb -o json query "user preferences" --kind memory --database my-db \
  | jq '.chunks[].chunk_content'

# Batch upload — ingest accepts many files in one invocation
hydradb ingest ./docs/*.md --database my-db

# Or drive it from find
find ./docs -name "*.md" -exec hydradb ingest --database my-db {} +
```

<Note>
  `query` returns `chunks`, each with `chunk_content`, `source_title` and
  `relevancy_score`. `list` returns `sources`. Both memories and knowledge appear in the
  same `sources` array, distinguished by their `type`.
</Note>

## Source & Show Support

<Note>
  If HydraDB CLI makes your workflow faster, please star the open-source repo that
  powers it. It helps keep it discoverable and motivates maintainers to keep shipping
  improvements.

  <Card title="hydradb-cli" icon="star" href="https://github.com/hydra-db/hydradb-cli">
    Star on GitHub if you found it useful.
  </Card>
</Note>