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**:
   ```bash
   git clone https://github.com/yourusername/stemedb.git
   cd stemedb
   ```

2. **Build the admin CLI**:
   ```bash
   cargo build --release --bin stemedb-admin
   ```

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

3. **Install to system path**:
   ```bash
   # 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**:
   ```bash
   stemedb-admin --version
   # Expected: stemedb-admin 0.1.0
   ```

### Option 2: Install via Cargo

If you have Rust toolchain installed:

```bash
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:

```bash
# 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**:
```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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:
```bash
cargo install --git https://github.com/yourusername/stemedb.git stemedb-admin --force
```

---

## Uninstall

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

# Or via cargo
cargo uninstall stemedb-admin
```

---

## Usage Examples

### Basic Operations

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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**:
```bash
# 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](../node-lifecycle.md) - Add, remove, replace nodes
- [Three-Node Cluster Setup](three-node-cluster.md) - Deploy production cluster
- [Monitoring & Observability](../monitoring/README.md) - Set up metrics and alerts

---

## Getting Help

```bash
# 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