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 optional TUI preview for SELECT queries.

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
• csv
• tsv

Streaming flags

For SELECT queries, streaming output supports:

• --fetch-size <n>: server batch size
• --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 preview

Launch the TUI for SELECT results:

alopex sql --tui "SELECT id, name FROM items"

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: --tui requires a TTY. When running in non-interactive mode, the CLI falls back to batch output and preserves --output formatting.

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"

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