CLI

Quick Start

Install the CLI

curl
pip

curl -fsSL https://cli.hydradb.com/install | bash

Installs the wheel from the latest GitHub release. Uses pipx when available so the CLI stays isolated, and falls back to pip install --user.

pip install https://github.com/hydra-db/hydradb-cli/releases/download/v0.2.0/hydradb_cli-0.2.0-py3-none-any.whl

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.

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.

Get credentials

Create an API key from HydraDB
Create or copy your database ID from the HydraDB dashboard

Authenticate

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:

hydradb login --api-key "$HYDRADB_API_KEY" --database my-db

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.

Verify

hydradb doctor

Reports your resolved config and whether the API is reachable.

Configuration

Authentication

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

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

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

echo 'export HYDRADB_API_KEY="your-api-key"' >> ~/.bashrc
echo 'export HYDRADB_DATABASE="your-database-id"' >> ~/.bashrc
source ~/.bashrc

echo 'export HYDRADB_API_KEY="your-api-key"' >> ~/.zshrc
echo 'export HYDRADB_DATABASE="your-database-id"' >> ~/.zshrc
source ~/.zshrc

[System.Environment]::SetEnvironmentVariable("HYDRADB_API_KEY", "your-api-key", "User")
[System.Environment]::SetEnvironmentVariable("HYDRADB_DATABASE", "your-database-id", "User")

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`

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.

Output Formats

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

export HYDRADB_OUTPUT=json

Or per-command, before the subcommand:

hydradb -o json list --database my-db

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

Persistent Configuration

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.

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

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

Querying

# 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

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

hydradb database create my-db
hydradb database readiness my-db
hydradb database delete my-db --yes

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.

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:

# 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 {} +

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.

Feedback and contributions

The CLI is open source. Feel free to raise an issue or contribute on GitHub.

Get Started

Usage

Organize

Understand

Plugins

For Agents

Quick Start

Configuration

Authentication

Environment Variables

Output Formats

Persistent Configuration

Commands

Context Operations

Ingesting

Querying

Inspecting and deleting

Database Management

Authentication & Configuration

Deprecated aliases

Scripting & Automation

Feedback and contributions

​Quick Start

​Configuration

​Authentication

​Environment Variables

​Output Formats

​Persistent Configuration

​Commands

​Context Operations

​Ingesting

​Querying

​Inspecting and deleting

​Database Management

​Authentication & Configuration

​Deprecated aliases

​Scripting & Automation

​Feedback and contributions

Quick Start

Configuration

Authentication

Environment Variables

Output Formats

Persistent Configuration

Commands

Context Operations

Ingesting

Querying

Inspecting and deleting

Database Management

Authentication & Configuration

Deprecated aliases

Scripting & Automation

Feedback and contributions