hippo — HippoDB CLI

Command-line interface for HippoDB: create tables, manage columns, insert and query rows, and compute aggregates.

Installation

# Install globally
npm install -g hippodb-cli
hippo <command>

# Or run without installing
npx hippodb-cli <command>

Requires Node.js ≥ 18.

Quick start

hippo login
hippo table create contacts name:text email:text age:number
hippo rows insert contacts name=Alice [email protected] age=30
hippo query contacts --where "age > 25"

Global options

| Flag | Description | |---|---| | --output <format> | Output format: json, table, csv | | --explain | Dry run — print what would happen without making API calls |

Environment variable: HIPPODB_OUTPUT sets the default output format. When writing to a TTY, the default is table; otherwise json.

Authentication

hippo login [--api-url <url>]

Authenticate via device flow. Saves credentials to ~/.hippodb/config.json.

Options:
  --api-url <url>   API base URL (default: https://api.hippodb.ai)

hippo logout

Clear saved credentials from ~/.hippodb/config.json.

Config file

~/.hippodb/config.json stores:

{
  "baseUrl": "https://api.hippodb.ai",
  "token": "<your-token>"
}

Environment variable overrides

| Variable | Description | |---|---| | HIPPODB_TOKEN | API token (overrides config file) | | HIPPODB_ENDPOINT | API base URL (overrides config file) | | HIPPODB_OUTPUT | Default output format |

Tables

hippo table list

List all tables.

hippo table create <table> [colSpecs...]

Create a table with optional column definitions.

hippo table create users
hippo table create products name:text price:number in_stock:boolean
hippo table create orders --if-not-exists customer:text total:number

Options:
  --if-not-exists   Return existing table if name already taken

Column specs use name:type syntax. See Column types for valid types.

hippo table describe <table>

Show a table's schema (columns, types, settings).

hippo table drop <table>

Drop a table and all its data.

Options:
  --confirm   Skip interactive confirmation prompt

In non-TTY environments (scripts, CI), --confirm is required. In a TTY, the command prompts interactively.

Columns

hippo columns list <table>

List all columns in a table.

hippo columns add <table> <name:type>

Add a column to an existing table.

hippo columns add users bio:text
hippo columns add products price:number --setting '{"precision": 2}'
hippo columns add orders status:select

Options:
  --setting <json>   Type-specific settings as a JSON object

See Column types for valid types and their settings.

hippo columns rename <table> <oldName> --to <newName>

Rename a column. --to is required.

hippo columns rename users bio --to biography

hippo columns drop <table> <colName>

Drop a column from a table.

Options:
  --confirm   Skip interactive confirmation prompt

In non-TTY environments, --confirm is required.

Rows

hippo rows insert <table> [kvArgs...]

Insert a new row. Always inserts; never updates an existing row.

# Key=value arguments
hippo rows insert users name=Alice age=30

# JSON string
hippo rows insert users --json '{"name":"Bob","age":25}'

# JSON from stdin
echo '{"name":"Carol"}' | hippo rows insert users

Input priority: --json flag > stdin (when non-TTY) > key=value args.

Value coercion: numeric strings become numbers; true/false become booleans.

hippo rows upsert <table> [kvArgs...]

Insert or update a row matched by a key column.

hippo rows upsert users name=Alice age=31 --key name
hippo rows upsert users --json '{"name":"Alice","age":31}' --key name --replace

Options:
  --key <field>   Column name/ID to match an existing row for update
  --json <json>   Row data as a JSON object
  --replace       Replace the entire row instead of merging fields

hippo rows get <table> <rowId>

Fetch a single row by its public ID (row_xxx).

hippo rows list <table>

List rows with optional filtering.

hippo rows list users
hippo rows list users --where "age > 25" --limit 10 --offset 20

Options:
  --where <expr>   Filter expression (see Filter syntax)
  --limit <n>      Maximum rows to return
  --offset <n>     Number of rows to skip

hippo rows update <table> <rowId> [kvArgs...]

Update specific fields of a row (JSONB merge — unspecified fields are preserved).

hippo rows update users row_abc123 age=32
hippo rows update users row_abc123 --json '{"age":32}'

Options:
  --json <json>   Fields to update as a JSON object

hippo rows delete <table> [rowId]

Delete a row by ID, or delete all rows matching a filter.

hippo rows delete users row_abc123
hippo rows delete users --where "age < 18"

Options:
  --where <expr>   Delete all rows matching this filter

Query

hippo query <table>

Query rows with filtering, sorting, and pagination.

hippo query users --where "age > 25" --sort age:asc --limit 10
hippo query products --sort price:desc --limit 5 --offset 10

Options:
  --where <expr>   Filter expression
  --sort <col>     Sort by column; append :asc or :desc (default: asc)
  --limit <n>      Maximum rows to return
  --offset <n>     Number of rows to skip

Aggregates

hippo aggregate <table>

Compute aggregates over rows. Multiple --sum, --avg, --min, --max flags are supported.

hippo aggregate orders --count
hippo aggregate orders --sum total --avg total
hippo aggregate orders --sum total --group-by status
hippo aggregate products --min price --max price --where "in_stock = true"

Options:
  --count          Count rows
  --sum <col>      Sum a numeric column (repeatable)
  --avg <col>      Average a numeric column (repeatable)
  --min <col>      Minimum value of a column (repeatable)
  --max <col>      Maximum value of a column (repeatable)
  --group-by <col> Group results by column
  --where <expr>   Filter expression
  --limit <n>      Maximum number of groups to return

Filter expression syntax

Filters are passed as --where strings with the form <column> <op> <value>.

| Operator | Symbol | Example | |---|---|---| | Equal | = | status = active | | Not equal | != | status != archived | | Greater than | > | age > 25 | | Greater than or equal | >= | score >= 100 | | Less than | < | price < 50 | | Less than or equal | <= | rating <= 3 | | Contains (substring) | contains | name contains Alice | | In (comma-separated list) | in | status in active,pending |

Numeric columns are compared numerically. String columns use string comparison.

Output formats

| Format | Description | |---|---| | table | Human-readable aligned table (default when writing to a TTY) | | json | JSON array or object (default when not writing to a TTY) | | csv | Comma-separated values |

Set globally with --output <format> or the HIPPODB_OUTPUT environment variable.

Name resolution

All commands that accept a <table>, <colName>, or <rowId> argument accept either:

• Human name — e.g. users, name, row_abc123
• Public ID — e.g. tbl_abc123, col_xyz789, row_abc123

When a name matches multiple tables (e.g. after a rename), the CLI will suggest the correct public ID to use.

Column types

| Type | Description | Settings | |---|---|---| | text | Arbitrary text string | — | | url | URL string | — | | number | Numeric value | {"precision": N} — decimal places | | boolean | true / false | — | | date | ISO 8601 date or datetime string | — | | select | Single value from a set of options | — | | image | Image URL or reference | — |

Options for select columns are created automatically on first use.