AimDB CLI

Command-line interface for introspecting and managing running AimDB instances.

Overview

The AimDB CLI is a thin client over the AimX v1 remote access protocol, providing intuitive commands for:

• Discovering running AimDB instances
• Listing and inspecting records
• Getting current record values
• Watching records for live updates
• Setting writable record values

Installation

Build from source:

cd /aimdb
cargo build --release -p aimdb-cli

The binary will be available at target/release/aimdb.

Quick Start

1. Discover Running Instances

aimdb instance list

Example output:

┌──────────────────────┬────────────────┬──────────┬─────────┬──────────┬───────────────┐
│ Socket Path          │ Server Version │ Protocol │ Records │ Writable │ Authenticated │
├──────────────────────┼────────────────┼──────────┼─────────┼──────────┼───────────────┤
│ /tmp/aimdb-demo.sock │ aimdb          │ 1.0      │ 2       │ 0        │ no            │
└──────────────────────┴────────────────┴──────────┴─────────┴──────────┴───────────────┘

2. List All Records

aimdb record list

Example output:

┌──────────────────────┬────────────────────────────────────────────┬───────────────┬───────────┬───────────┬──────────┐
│ Name                 │ Type ID                                    │ Buffer Type   │ Producers │ Consumers │ Writable │
├──────────────────────┼────────────────────────────────────────────┼───────────────┼───────────┼───────────┼──────────┤
│ server::Temperature  │ TypeId(0xaee15e261d918c67cee5a96c2f604ce0) │ single_latest │ 1         │ 2         │ no       │
│ server::Config       │ TypeId(0xc2af5c8376864a24e916c87f88505fac) │ mailbox       │ 0         │ 3         │ yes      │
└──────────────────────┴────────────────────────────────────────────┴───────────────┴───────────┴───────────┴──────────┘

3. Get Current Record Value

aimdb record get server::Temperature

Example output:

{
  "celsius": 23.5,
  "sensor_id": "sensor-001",
  "timestamp": 1730379296
}

4. Watch a Record for Live Updates

aimdb watch server::Temperature

Example output:

📡 Watching record: server::Temperature (subscription: sub-123)
Press Ctrl+C to stop

2025-11-02 10:30:45.123 | seq:42 | {"celsius":23.5,"sensor_id":"sensor-001","timestamp":1730379296}
2025-11-02 10:30:47.456 | seq:43 | {"celsius":23.6,"sensor_id":"sensor-001","timestamp":1730379298}
2025-11-02 10:30:49.789 | seq:44 | {"celsius":23.7,"sensor_id":"sensor-001","timestamp":1730379300}
^C
✅ Stopped watching

5. Set a Writable Record

aimdb record set server::Config '{"log_level":"debug","max_connections":100}'

Command Reference

Instance Commands

instance list

List all running AimDB instances by scanning for Unix domain socket files.

aimdb instance list [--format <FORMAT>]

Options:

• -f, --format <FORMAT>: Output format (table, json, json-compact, yaml)

instance info

Show detailed information about a specific instance.

aimdb instance info [--socket <PATH>]

Options:

• -s, --socket <PATH>: Socket path (uses auto-discovery if not specified)

instance ping

Test connection to an instance.

aimdb instance ping [--socket <PATH>]

Record Commands

record list

List all registered records in an AimDB instance.

aimdb record list [OPTIONS]

Options:

• -s, --socket <PATH>: Socket path (uses auto-discovery if not specified)
• -f, --format <FORMAT>: Output format (table, json, json-compact, yaml)
• -w, --writable: Show only writable records

record get

Get the current value of a specific record.

aimdb record get <RECORD> [OPTIONS]

Arguments:

• <RECORD>: Record name (e.g., server::Temperature)

Options:

• -s, --socket <PATH>: Socket path
• -f, --format <FORMAT>: Output format (default: json)

record set

Set the value of a writable record.

aimdb record set <NAME> <VALUE> [OPTIONS]

Arguments:

• <NAME>: Record name
• <VALUE>: JSON value to set

Options:

• -s, --socket <PATH>: Socket path
• --dry-run: Validate but don't actually set

Note: Only records without producers can be set remotely.

Watch Command

watch

Watch a record for live updates, displaying updates as they arrive.

aimdb watch <RECORD> [OPTIONS]

Arguments:

• <RECORD>: Record name to watch

Options:

• -s, --socket <PATH>: Socket path
• -q, --queue-size <SIZE>: Subscription queue size (default: 100)
• -c, --count <N>: Maximum number of events to receive (0 = unlimited)
• -f, --full: Show full pretty-printed JSON for each event

Press Ctrl+C to stop watching and unsubscribe cleanly.

Graph Commands

Commands for exploring the dependency graph of records in an AimDB instance.

graph nodes

List all nodes in the dependency graph, showing record origins, buffer types, and connection counts.

aimdb graph nodes [OPTIONS]

Options:

• -s, --socket <PATH>: Socket path (uses auto-discovery if not specified)
• -f, --format <FORMAT>: Output format (table, json, json-compact, yaml)

Example output:

┌──────────────────────┬───────────┬───────────────┬──────────┬──────┬──────────┐
│ Key                  │ Origin    │ Buffer Type   │ Capacity │ Taps │ Outbound │
├──────────────────────┼───────────┼───────────────┼──────────┼──────┼──────────┤
│ temp.vienna          │ link      │ single_latest │ 1        │ 1    │ -        │
│ temp.berlin          │ link      │ single_latest │ 1        │ 1    │ -        │
│ weather.aggregate    │ transform │ single_latest │ 1        │ 0    │ yes      │
└──────────────────────┴───────────┴───────────────┴──────────┴──────┴──────────┘

graph edges

List all edges in the dependency graph, showing how data flows between records.

aimdb graph edges [OPTIONS]

Options:

• -s, --socket <PATH>: Socket path
• -f, --format <FORMAT>: Output format

Example output:

┌────────────────┬───────────────────┬─────────────────┐
│ From           │ To                │ Edge Type       │
├────────────────┼───────────────────┼─────────────────┤
│ temp.vienna    │ weather.aggregate │ transform_input │
│ temp.berlin    │ weather.aggregate │ transform_input │
└────────────────┴───────────────────┴─────────────────┘

graph order

Show the topological ordering of records (spawn/initialization order).

aimdb graph order [OPTIONS]

Options:

• -s, --socket <PATH>: Socket path
• -f, --format <FORMAT>: Output format

Example output:

┌───┬───────────────────┐
│ # │ Record Key        │
├───┼───────────────────┤
│ 1 │ temp.vienna       │
│ 2 │ temp.berlin       │
│ 3 │ weather.aggregate │
└───┴───────────────────┘

graph dot

Export the dependency graph in DOT format for visualization with Graphviz.

aimdb graph dot [OPTIONS]

Options:

• -s, --socket <PATH>: Socket path
• -n, --name <NAME>: Graph name (default: "aimdb")

Example:

# Generate DOT file and render as PNG
aimdb graph dot > graph.dot
dot -Tpng graph.dot -o graph.png

# Or pipe directly to dot
aimdb graph dot | dot -Tsvg > graph.svg

Output Formats

The CLI supports multiple output formats:

• table (default for lists): Human-readable formatted tables
• json: Pretty-printed JSON with indentation
• json-compact: Single-line JSON for scripting
• yaml: YAML format (requires yaml feature)

Socket Discovery

The CLI automatically discovers running AimDB instances by scanning:

• /tmp directory
• /var/run/aimdb directory

Socket files must have a .sock extension.

You can override auto-discovery by specifying --socket <PATH> for any command.

Error Handling

The CLI provides clear, actionable error messages:

Error: Connection failed: /tmp/aimdb.sock
  Reason: connection timeout
  Hint: Check if AimDB instance is running

Error: Permission denied: record.set
  Record 'server::Temperature' is not writable
  Hint: Check 'writable' column in 'aimdb record list'

Examples

Health Check Workflow

# Discover instances
aimdb instance list

# Check connectivity
aimdb instance ping

# List all records
aimdb record list

# Get specific values
aimdb record get server::Temperature
aimdb record get server::SystemStatus

Debugging Workflow

# Find writable records
aimdb record list --writable

# Watch live updates
aimdb watch server::Temperature --count 10

# Update configuration
aimdb record set server::Config '{"log_level":"debug"}'

# Verify change
aimdb record get server::Config

Monitoring Integration

# Export metrics as JSON
aimdb record list --format json > records.json

# Check specific value in script
TEMP=$(aimdb record get server::Temperature | jq '.celsius')
if (( $(echo "$TEMP > 80" | bc -l) )); then
    echo "Warning: High temperature!"
fi

# Continuous monitoring
watch -n 1 'aimdb record get server::Temperature | jq ".celsius"'

Graph Analysis Workflow

# View all nodes and their origins
aimdb graph nodes

# See data flow edges
aimdb graph edges

# Check spawn order
aimdb graph order

# Generate visual graph
aimdb graph dot > aimdb-graph.dot
dot -Tpng aimdb-graph.dot -o aimdb-graph.png
open aimdb-graph.png

# Export as JSON for further analysis
aimdb graph nodes --format json | jq '.[] | select(.origin == "transform")'

Protocol

The CLI uses the AimX v1 remote access protocol over Unix domain sockets with NDJSON message format.

See docs/design/008-M3-remote-access.md for the full protocol specification.

Development

Run tests:

cargo test -p aimdb-cli

Run with logging:

RUST_LOG=debug cargo run -p aimdb-cli -- record list

License

See LICENSE file.