> ## Documentation Index
> Fetch the complete documentation index at: https://cortex-e852fafe-t3code-rewrite-docs-declutter.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={"dark"}
        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={"dark"}
        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 [HydraDB](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={"dark"}
    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={"dark"}
    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={"dark"}
    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={"dark"}
    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={"dark"}
    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={"dark"}
    [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={"dark"}
export HYDRADB_OUTPUT=json
```

Or per-command, before the subcommand:

```bash theme={"dark"}
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={"dark"}
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={"dark"}
# 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={"dark"}
# 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`. Setting it switches the query to keyword (text) search |
| `--max-results`, `-n` | Maximum results, 1 to 50 (default `10`) |
| `--mode`, `-m` | Retrieval mode: `fast` or `thinking`. Omit it and the API picks one per query (`auto`) |
| `--alpha` | Hybrid search weight (`0.0` keyword to `1.0` semantic). Omitted means the API default, `0.8` |
| `--recency-bias` | Preference for newer content (`0.0` to `1.0`). Omitted means a mild `0.4` tilt. Pass `0` to turn it off |
| `--graph-context` / `--no-graph-context` | Include knowledge graph relations. On by default. `--no-graph-context` only takes effect in `fast` mode |
| `--context` | Additional context to guide retrieval |

#### Inspecting and deleting

```bash theme={"dark"}
# 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 to 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={"dark"}
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

Use `--output json` to pipe results into `jq`, Python, or other tools:

```bash theme={"dark"}
# 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 code

<Card title="hydradb-cli" icon="github" href="https://github.com/hydra-db/hydradb-cli">
  View the source on GitHub.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.