HydraDB CLI

Quick Start

Install the CLI

pip install hydradb-cli

Requires Python 3.10 or later.

Get credentials

Create an API key from Hydra DB
Create or copy your tenant ID from the Hydra DB dashboard

Authenticate

hydradb login

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

Verify

hydradb whoami

Configuration

Authentication

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

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

macOS/Linux (bash)
macOS/Linux (zsh)
Windows (PowerShell)

echo 'export HYDRA_DB_API_KEY="your-api-key"' >> ~/.bashrc
echo 'export HYDRADB_TENANT_ID="your-tenant-id"' >> ~/.bashrc
source ~/.bashrc

echo 'export HYDRA_DB_API_KEY="your-api-key"' >> ~/.zshrc
echo 'export HYDRADB_TENANT_ID="your-tenant-id"' >> ~/.zshrc
source ~/.zshrc

[System.Environment]::SetEnvironmentVariable("HYDRA_DB_API_KEY", "your-api-key", "User")
[System.Environment]::SetEnvironmentVariable("HYDRADB_TENANT_ID", "your-tenant-id", "User")

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:

hydradb config set output json

Or per-command:

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)

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

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

# 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

# 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

# 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:

# 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

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.

hydradb-cli

Star on GitHub if you found it useful.

Get Started

Usage

Concepts

Plugins

For Agents

Quick Start

Configuration

Authentication

Environment Variables

Output Formats

Commands

Authentication

Tenant Management

Memory Operations

Knowledge Base

Context Retrieval (Recall)

Data Inspection

CLI Configuration

Scripting & Automation

Source & Show Support

hydradb-cli

​Quick Start

​Configuration

​Authentication

​Environment Variables

​Output Formats

​Commands

​Authentication

​Tenant Management

​Memory Operations

​Knowledge Base

​Context Retrieval (Recall)

​Data Inspection

​CLI Configuration

​Scripting & Automation

​Source & Show Support

hydradb-cli

Quick Start

Configuration

Authentication

Environment Variables

Output Formats

Commands

Authentication

Tenant Management

Memory Operations

Knowledge Base

Context Retrieval (Recall)

Data Inspection

CLI Configuration

Scripting & Automation

Source & Show Support