Installing the `aimdb` executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install aimdb-cli

It will make the aimdb command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall aimdb-cli uninstalls.

Back to the crate overview.

Readme

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.

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"'

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.

Installing the aimdb executable

Installing the `aimdb` executable