stemedb/docs/operations/deployment/install-admin-cli.md

Installing stemedb-admin CLI

The stemedb-admin CLI tool provides cluster management capabilities for StemeDB operators. It connects to the gateway node via HTTP and provides human-friendly table output or machine-readable JSON.

Requirements

• Platform: Linux, macOS, or Windows (WSL2)
• Architecture: x86_64 or ARM64
• Network: HTTP access to gateway node (default port 18181)
• Rust (for building from source): 1.75 or later

Installation Methods

Option 1: Build from Source (Recommended)

1. Clone the repository:

   git clone https://github.com/yourusername/stemedb.git
   cd stemedb
   

2. Build the admin CLI:

   cargo build --release --bin stemedb-admin
   

   The binary will be at: target/release/stemedb-admin

3. Install to system path:

   # Linux/macOS
   sudo cp target/release/stemedb-admin /usr/local/bin/
   sudo chmod +x /usr/local/bin/stemedb-admin
   
   # Or install via cargo
   cargo install --path crates/stemedb-admin
   

4. Verify installation:

   stemedb-admin --version
   # Expected: stemedb-admin 0.1.0
   

Option 2: Install via Cargo

If you have Rust toolchain installed:

cargo install --git https://github.com/yourusername/stemedb.git stemedb-admin

Option 3: Download Pre-built Binary (Future)

Pre-built binaries will be available in GitHub Releases:

# Linux x86_64
wget https://github.com/yourusername/stemedb/releases/download/v0.1.0/stemedb-admin-linux-x86_64
chmod +x stemedb-admin-linux-x86_64
sudo mv stemedb-admin-linux-x86_64 /usr/local/bin/stemedb-admin

# macOS ARM64
wget https://github.com/yourusername/stemedb/releases/download/v0.1.0/stemedb-admin-macos-arm64
chmod +x stemedb-admin-macos-arm64
sudo mv stemedb-admin-macos-arm64 /usr/local/bin/stemedb-admin

---

Configuration

Environment Variables

The CLI respects the following environment variables:

Variable	Description	Default
STEMEDB_GATEWAY_ADDR	Gateway HTTP endpoint	http://localhost:18181
RUST_LOG	Logging level (debug, info, warn, error)	info

Example:

# Set gateway address
export STEMEDB_GATEWAY_ADDR=http://gateway.prod.example.com:18181

# Enable verbose logging
export RUST_LOG=stemedb_admin=debug

Command-line Options

All commands support:

• --gateway <URL> - Override gateway address
• --format <table|json> - Output format
• --verbose - Enable debug logging

---

Verification

Test Connection

# Test gateway connectivity
stemedb-admin cluster health

Expected output:

✓ Cluster is healthy
  Reachable nodes: 3
  Joined: true

If you see an error:

Error: Failed to connect to gateway at http://localhost:18181

Check:

1. Gateway is running: systemctl status stemedb-gateway
2. Gateway port is reachable: curl http://gateway:18181/v1/health
3. Firewall rules allow HTTP traffic on port 18181

Test Commands

# List nodes
stemedb-admin node list

# Show cluster status
stemedb-admin cluster status

# List shards
stemedb-admin shard list

# Export debug state
stemedb-admin debug export --output /tmp/cluster-state.json
cat /tmp/cluster-state.json

---

Upgrading

To upgrade to a newer version:

# Pull latest code
cd stemedb
git pull

# Rebuild
cargo build --release --bin stemedb-admin

# Replace binary
sudo cp target/release/stemedb-admin /usr/local/bin/

Or via cargo:

cargo install --git https://github.com/yourusername/stemedb.git stemedb-admin --force

---

Uninstall

# Remove binary
sudo rm /usr/local/bin/stemedb-admin

# Or via cargo
cargo uninstall stemedb-admin

---

Usage Examples

Basic Operations

# Check cluster health (exit code 0 if healthy, 1 if unhealthy)
stemedb-admin cluster health
echo $?  # 0 = healthy, 1 = unhealthy

# Show cluster overview with node table
stemedb-admin cluster status

# List all nodes with state and shard assignments
stemedb-admin node list

# Show detailed info for specific node
stemedb-admin node a3f2b1c4 info

# Show shards assigned to a node
stemedb-admin node a3f2b1c4 shards

# Show only leader shards for a node
stemedb-admin node a3f2b1c4 shards --leader

Shard Operations

# List all shards
stemedb-admin shard list

# Show detailed shard info
stemedb-admin shard 5 info

# Show replica nodes for a shard
stemedb-admin shard 5 replicas

Debug Export

# Export complete cluster state for support tickets
stemedb-admin debug export --output cluster-state.json

# Compress for sharing
gzip cluster-state.json
# Attach cluster-state.json.gz to support ticket

JSON Output for Automation

# Get node list as JSON
stemedb-admin node list --format json | jq '.[] | select(.state == "Dead")'

# Monitor cluster health in script
if stemedb-admin cluster health --format json | jq -e '.healthy'; then
  echo "Cluster OK"
else
  echo "Cluster UNHEALTHY - alerting ops team"
  # Trigger alert
fi

Remote Gateway

# Connect to production gateway
stemedb-admin --gateway https://gateway.prod.example.com:18181 cluster status

# Or set environment variable
export STEMEDB_GATEWAY_ADDR=https://gateway.prod.example.com:18181
stemedb-admin cluster status

---

Troubleshooting

"Failed to connect to gateway"

Cause: Gateway is unreachable or not running.

Fix:

1. Check gateway is running: systemctl status stemedb-gateway
2. Test connectivity: curl http://gateway:18181/v1/health
3. Verify firewall rules: sudo ufw status

"Node not found: NODE_ID"

Cause: Node ID is incorrect or node has left the cluster.

Fix:

1. List all nodes: stemedb-admin node list
2. Verify node ID (first 8 characters of UUID)
3. Check node is in Alive state (not Dead)

"Gateway returned error status: 404"

Cause: Gateway endpoint does not exist or API version mismatch.

Fix:

1. Verify gateway version matches CLI version
2. Check gateway logs: journalctl -u stemedb-gateway -n 50
3. Ensure gateway is fully initialized (may take 10-30 seconds on startup)

Permission Denied

Cause: CLI binary is not executable or requires elevated privileges.

Fix:

# Make executable
chmod +x /usr/local/bin/stemedb-admin

# Or run with sudo if accessing privileged resources
sudo stemedb-admin cluster status

---

Next Steps

• Node Lifecycle Operations - Add, remove, replace nodes
• Three-Node Cluster Setup - Deploy production cluster
• Monitoring & Observability - Set up metrics and alerts

---

Getting Help

# Show all commands
stemedb-admin --help

# Show help for specific command
stemedb-admin cluster --help
stemedb-admin node --help
stemedb-admin shard --help
stemedb-admin debug --help

For issues or feature requests, open a GitHub issue: https://github.com/yourusername/stemedb/issues