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

# HydraDB CLI

> Agent-friendly command line interface for HydraDB. Manage memories, recall context, and ingest knowledge from the terminal.

## Quick Start

<Steps>
  <Step title="Install the CLI">
    ```bash theme={"dark"}
    pip install hydradb-cli
    ```

    <Note>
      Requires Python 3.10 or later.
    </Note>
  </Step>

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

  <Step title="Authenticate">
    ```bash theme={"dark"}
    hydradb login
    ```

    The interactive prompt asks for your API key and tenant ID, then saves them
    to `~/.hydradb/config.json` (file permissions `0600`).
  </Step>

  <Step title="Verify">
    ```bash theme={"dark"}
    hydradb whoami
    ```
  </Step>
</Steps>

## Configuration

### Authentication

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

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

<Tabs>
  <Tab title="macOS/Linux (bash)">
    ```bash theme={"dark"}
    echo 'export HYDRA_DB_API_KEY="your-api-key"' >> ~/.bashrc
    echo 'export HYDRADB_TENANT_ID="your-tenant-id"' >> ~/.bashrc
    source ~/.bashrc
    ```
  </Tab>

  <Tab title="macOS/Linux (zsh)">
    ```bash theme={"dark"}
    echo 'export HYDRA_DB_API_KEY="your-api-key"' >> ~/.zshrc
    echo 'export HYDRADB_TENANT_ID="your-tenant-id"' >> ~/.zshrc
    source ~/.zshrc
    ```
  </Tab>

  <Tab title="Windows (PowerShell)">
    ```powershell theme={"dark"}
    [System.Environment]::SetEnvironmentVariable("HYDRA_DB_API_KEY", "your-api-key", "User")
    [System.Environment]::SetEnvironmentVariable("HYDRADB_TENANT_ID", "your-tenant-id", "User")
    ```
  </Tab>
</Tabs>

### Environment Variables

| Variable                | Description                               | Default                   |
| ----------------------- | ----------------------------------------- | ------------------------- |
| `HYDRA_DB_API_KEY`      | Your HydraDB API key                      | *Required*                |
| `HYDRADB_TENANT_ID`     | Your HydraDB tenant identifier            | *Required*                |
| `HYDRADB_API_URL`       | API base URL                              | `https://api.hydradb.com` |
| `HYDRADB_OUTPUT`        | Default output format (`human` or `json`) | `human`                   |
| `HYDRADB_SUB_TENANT_ID` | Sub-tenant for data partitioning          | -                         |

### Output Formats

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

```bash theme={"dark"}
hydradb config set output json
```

Or per-command:

```bash theme={"dark"}
hydradb -o json memories list TENANT_ID
```

## Commands

### Authentication

| Command          | Description                                                                 |
| ---------------- | --------------------------------------------------------------------------- |
| `hydradb login`  | Interactive login - saves API key and tenant ID to `~/.hydradb/config.json` |
| `hydradb logout` | Remove stored credentials                                                   |
| `hydradb whoami` | Show current authentication status and tenant info                          |

### Tenant Management

| Command                                     | Description                                     |
| ------------------------------------------- | ----------------------------------------------- |
| `hydradb tenant create`                     | Create a new tenant                             |
| `hydradb tenant monitor TENANT_ID`          | Get tenant infrastructure status and statistics |
| `hydradb tenant list-sub-tenants TENANT_ID` | List all sub-tenant IDs                         |
| `hydradb tenant delete TENANT_ID`           | Delete a tenant and all its data (irreversible) |

<Warning>
  `hydradb tenant delete` permanently removes the tenant and all associated memories,
  knowledge, and graph data. This action cannot be undone.
</Warning>

### Memory Operations

| Command                                       | Description                                            |
| --------------------------------------------- | ------------------------------------------------------ |
| `hydradb memories add TENANT_ID TEXT`         | Add a user memory (auto-extracts insights via `infer`) |
| `hydradb memories list TENANT_ID`             | List all user memories                                 |
| `hydradb memories delete TENANT_ID MEMORY_ID` | Delete a specific memory by ID                         |

```bash theme={"dark"}
# Store a memory
hydradb memories add my-tenant "The user prefers dark mode and uses VS Code"

# List all memories
hydradb memories list my-tenant

# Delete a memory
hydradb memories delete my-tenant mem_abc123
```

### Knowledge Base

| Command                                            | Description                                 |
| -------------------------------------------------- | ------------------------------------------- |
| `hydradb knowledge upload TENANT_ID FILES...`      | Upload files to the knowledge base          |
| `hydradb knowledge upload-text TENANT_ID TEXT`     | Upload text content directly                |
| `hydradb knowledge verify TENANT_ID SOURCE_ID`     | Check processing status of uploaded content |
| `hydradb knowledge delete TENANT_ID SOURCE_IDS...` | Delete knowledge sources by ID              |

```bash theme={"dark"}
# Upload a document
hydradb knowledge upload my-tenant ./docs/architecture.md

# Upload inline text
hydradb knowledge upload-text my-tenant "Project uses PostgreSQL 15 with pgvector"

# Check processing status
hydradb knowledge verify my-tenant src_abc123
```

### Context Retrieval (Recall)

| Command                                      | Description                                            |
| -------------------------------------------- | ------------------------------------------------------ |
| `hydradb recall full TENANT_ID QUERY`        | Search over indexed knowledge (documents, files)       |
| `hydradb recall preferences TENANT_ID QUERY` | Search over user memories (preferences, conversations) |
| `hydradb recall keyword TENANT_ID QUERY`     | Deterministic keyword/boolean search                   |

```bash theme={"dark"}
# Semantic search over knowledge
hydradb recall full my-tenant "How is authentication implemented?"

# Search user memories
hydradb recall preferences my-tenant "What IDE does the user prefer?"

# Keyword search
hydradb recall keyword my-tenant "PostgreSQL migration"
```

### Data Inspection

| Command                                       | Description                                        |
| --------------------------------------------- | -------------------------------------------------- |
| `hydradb fetch sources TENANT_ID`             | List all ingested sources (knowledge and memories) |
| `hydradb fetch content TENANT_ID SOURCE_ID`   | Fetch the full content of a source                 |
| `hydradb fetch relations TENANT_ID SOURCE_ID` | Fetch knowledge graph relations for a source       |

### CLI Configuration

| Command                        | Description                                           |
| ------------------------------ | ----------------------------------------------------- |
| `hydradb config show`          | Show current CLI configuration                        |
| `hydradb config set KEY VALUE` | Set a configuration value (e.g., `output`, `api_url`) |

## 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={"dark"}
# List memories as JSON and filter with jq
hydradb -o json memories list my-tenant | jq '.[] | .id'

# Recall context and pipe to another tool
hydradb -o json recall preferences my-tenant "user preferences" | jq '.results'

# Batch upload files
find ./docs -name "*.md" -exec hydradb knowledge upload my-tenant {} +
```

## 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/usecortex/hydradb-cli">
    Star on GitHub if you found it useful.
  </Card>
</Note>