Alopex CLI

Alopex CLI provides access to embedded and server-backed Alopex DB features. It supports SQL, KV, Vector, and Columnar workflows with streaming output and an interactive TUI by default on TTY terminals.

Quick start

Local (embedded) SQL:

alopex --data-dir ./data sql "SELECT 1"

Server profile (HTTPS required):

alopex --profile prod sql "SELECT * FROM users" --fetch-size 500 --max-rows 1000

Output formats

Use --output to control formatting:

• table (default)
• json
• jsonl
• csv
• tsv

Streaming flags

For SELECT queries, streaming output supports:

• --fetch-size <n>: server batch size (server profiles only)
• --max-rows <n>: stop after N rows
• --deadline <duration>: timeout (examples: 60s, 5m, 1h)

Example:

alopex sql "SELECT * FROM events" --fetch-size 1000 --max-rows 10000 --deadline 90s --output json

TUI mode

The CLI launches the TUI automatically on TTY terminals. For SQL, just run:

alopex sql "SELECT id, name FROM items"

Non-SQL commands that return rows also default to the TUI:

alopex kv list

Force batch output with --batch or any explicit --output format:

alopex sql "SELECT * FROM events" --output json

Keybindings (TUI):

• q / Esc: quit
• ?: help
• /: search
• n / N: next/previous match
• hjkl or arrow keys: move selection
• g / G: jump top/bottom
• Ctrl+d / Ctrl+u: page down/up
• Enter: toggle detail panel
• J / K: scroll detail panel

Note: the TUI requires a TTY. When running in non-interactive mode, the CLI falls back to batch output and preserves --output formatting. Use --max-rows (or --limit) to cap memory usage for large result sets.

Admin console

Run the CLI without a subcommand to open the admin console:

alopex

You can also open the admin console scoped to a target by omitting its subcommand:

alopex server

The admin console uses a three-pane layout inspired by rainfrog:

• Left: resource tree with search (tables, columns, segments, KV keys)
• Right top: detail/input panel (actions + parameters)
• Right bottom: status/preview panel

Focus controls:

• h / l or ←/→: move focus between Table/Detail/Status
• Table: j/k move, / search, g/G top/bottom, Ctrl+d/Ctrl+u page, Enter select
• Detail: Tab field, e edit, o list options, Enter execute
• Status: j/k scroll, g/G top/bottom, Ctrl+d/Ctrl+u page

Lifecycle actions (archive/restore/backup/export) live in the Actions list and respect server auth capabilities.

Profiles and server connections

Profiles are stored in ~/.alopex/config (TOML). Example with a local profile:

[profiles.local]
connection_type = "local"

[profiles.local.local]
path = "/var/lib/alopex"

Server profile with fallback to local data directory:

[profiles.prod]
connection_type = "server"

[profiles.prod.server]
url = "https://db.example.com"

# Optional local fallback when the server is unavailable
[profiles.prod.local]
path = "/var/lib/alopex"

Set a default profile:

default_profile = "prod"

Profile management commands (local profiles only):

alopex profile create dev --data-dir ./data
alopex profile list
alopex profile show dev
alopex profile delete dev
alopex profile set-default dev

Authentication

Token

[profiles.prod]
connection_type = "server"

[profiles.prod.server]
url = "https://db.example.com"
auth = "token"
token = "YOUR_TOKEN"

Basic (password_command)

[profiles.prod]
connection_type = "server"

[profiles.prod.server]
url = "https://db.example.com"
auth = "basic"
username = "alice"
password_command = "security find-generic-password -w -s alopex"

mTLS

[profiles.prod]
connection_type = "server"

[profiles.prod.server]
url = "https://db.example.com"
auth = "mtls"
cert_path = "/etc/alopex/client.pem"
key_path = "/etc/alopex/client-key.pem"

Server management commands

All server commands require a server profile. Commands:

alopex --profile prod server status
alopex --profile prod server metrics
alopex --profile prod server health
alopex --profile prod server compaction trigger

Examples

SQL streaming to CSV:

alopex sql "SELECT * FROM events" --output csv --fetch-size 1000 --max-rows 5000

KV get:

alopex kv get my-key

Vector search:

alopex vector search --index my_index --query "[0.1,0.2,0.3]" --k 10