# Remux CLI Reference

Complete command-line interface reference for managing remux daemon, policies, and operations.

## Installation

```bash
# Install as system binary
pip install -e .

# Or run as module
python -m rpipe [command]
```

## Quick Start

```bash
# Start daemon with audit logging
remux daemon start --audit-log-dir ~/.rpipe/logs

# List available policies
remux policy list

# Execute a command
remux client run example.com cat /var/log/syslog

# Check daemon status
remux daemon status

# View audit logs
remux daemon logs --follow
```

## Global Options

```bash
remux [options] [command]

Options:
  -v, --verbose          Enable verbose logging
  --version              Show version information
  -h, --help             Show help message
```

---

## Daemon Management

### remux daemon start

Start the remux daemon.

```bash
remux daemon start [options]

Options:
  --socket PATH              Unix socket path (default: ~/.rpipe/daemon.sock)
  --known-hosts PATH         SSH known_hosts file (default: auto-detect)
  --audit-log-dir PATH       Audit log directory (default: stderr only)
  --foreground               Run in foreground (don't daemonize)
```

**Examples:**
```bash
# Start with default settings
remux daemon start

# Start with custom socket and audit logging
remux daemon start \
  --socket /tmp/remux.sock \
  --audit-log-dir /var/log/remux

# Start in foreground for debugging
remux daemon start --foreground

# Start with host key verification
remux daemon start --known-hosts ~/.ssh/known_hosts
```

### remux daemon stop

Stop the running daemon.

```bash
remux daemon stop [options]

Options:
  --socket PATH       Unix socket path (default: ~/.rpipe/daemon.sock)
```

**Examples:**
```bash
# Stop with default socket
remux daemon stop

# Stop custom socket
remux daemon stop --socket /tmp/remux.sock
```

### remux daemon status

Check if daemon is running.

```bash
remux daemon status [options]

Options:
  --socket PATH       Unix socket path
```

**Examples:**
```bash
# Check default daemon
remux daemon status

# Output:
# ✓ Daemon is running
#   Socket: /home/user/.rpipe/daemon.sock
```

### remux daemon logs

View daemon audit logs.

```bash
remux daemon logs [options]

Options:
  --audit-log-dir PATH      Log directory (default: ~/.rpipe/logs)
  --follow                  Follow logs in real-time
  --level LEVEL             Filter by level (ALLOW|DENY|ERROR|WARNING)
```

**Examples:**
```bash
# View latest audit logs
remux daemon logs

# Follow logs in real-time
remux daemon logs --follow

# View only denied commands
remux daemon logs --level DENY

# View from custom directory
remux daemon logs --audit-log-dir /var/log/remux
```

---

## Policy Management

### remux policy list

List all available policies.

```bash
remux policy list [options]

Options:
  --config FILE       Custom policy configuration file
```

**Examples:**
```bash
# List built-in policies
remux policy list

# Output:
# Built-in Policies:
#   - read_only        (Read-only access to logs)
#   - write_capable    (Read + write to /tmp)
#   - restrictive      (Only safe commands)

# List with custom config
remux policy list --config policies.yaml
```

### remux policy show

Show detailed policy information.

```bash
remux policy show <name> [options]

Arguments:
  name                Policy name

Options:
  --config FILE       Policy configuration file
```

**Examples:**
```bash
# Show built-in policy
remux policy show read_only

# Output:
# Policy: read_only
# Capabilities: 5
#   - read_file: /var/log/**/*
#   - execute_binary: cat|grep|ls|tail|head|find
#   - write_stdout: (all)
#   - write_stderr: (all)

# Show custom policy
remux policy show my_policy --config policies.yaml
```

### remux policy validate

Validate a policy configuration file.

```bash
remux policy validate <file>

Arguments:
  file                Policy configuration file (YAML/JSON)
```

**Examples:**
```bash
# Validate YAML policy
remux policy validate policies.yaml

# Output:
# ✓ Policy file is valid
# Found 3 policies:
#   - read_only: 4 capabilities
#   - write_capable: 5 capabilities
#   - custom: 3 capabilities

# Invalid file shows errors
remux policy validate bad_policy.yaml
# Output:
# ✗ Policy validation failed: Invalid operation 'bad_op'
```

### remux policy create

Create a new policy configuration.

```bash
remux policy create <name> [options]

Arguments:
  name                Policy name

Options:
  --template TEMPLATE   Template (read_only|write_capable|restrictive)
  --output FILE         Output file (default: policy.yaml)
```

**Examples:**
```bash
# Create custom policy based on read_only
remux policy create my_policy --template read_only --output my_policy.yaml

# Create from scratch
remux policy create database_admin --output db_policy.yaml

# Generated file content:
# policies:
#   database_admin:
#     capabilities:
#       - operation: read_file
#         resource: /var/lib/postgresql/**/*
#       - operation: execute_binary
#         resource: psql|pg_dump
```

---

## Client Operations

### remux client run

Execute a command on remote host.

```bash
remux client run <host> <command...> [options]

Arguments:
  host                Remote host
  command             Command to execute

Options:
  --socket PATH       Daemon socket path
  --policy NAME       Policy to apply (default: read_only)
  --timeout SECONDS   Timeout in seconds (default: 60)
  --cwd PATH          Working directory on remote
```

**Examples:**
```bash
# Simple command
remux client run web1.example.com cat /var/log/syslog

# With policy
remux client run db.example.com ls -la /data --policy database_admin

# With timeout
remux client run slow.example.com find /data -type f --timeout 120

# With working directory
remux client run app.example.com pwd --cwd /var/app

# Piped command (v2)
remux client run web1.example.com cat /var/log/syslog \| grep error
```

### remux client batch

Execute multiple commands.

```bash
remux client batch <host> [options]

Arguments:
  host                Remote host

Options:
  --commands-file FILE    File with commands (one per line)
  --policy NAME          Policy to apply (default: read_only)
```

**Examples:**
```bash
# Create commands file
cat > commands.txt << 'EOF'
cat /var/log/syslog | grep error
ps aux | grep python
df -h /
EOF

# Execute batch
remux client batch web1.example.com --commands-file commands.txt

# With custom policy
remux client batch db.example.com \
  --commands-file db_checks.txt \
  --policy database_admin
```

---

## Configuration Management

### remux config show

Display current configuration.

```bash
remux config show
```

**Example Output:**
```
Remux Configuration:
  Config directory: /home/user/.rpipe
  Daemon socket: /home/user/.rpipe/daemon.sock
  SSH known_hosts: /home/user/.ssh/known_hosts
  Audit logs: /home/user/.rpipe/logs
```

### remux config init

Initialize remux configuration.

```bash
remux config init [options]

Options:
  --force             Overwrite existing configuration
```

**Examples:**
```bash
# Initialize configuration
remux config init

# Output:
# ✓ Initialized remux configuration
#   Created: /home/user/.rpipe
#   Created: /home/user/.rpipe/logs

# Force reinitialize
remux config init --force
```

---

## Status & Monitoring

### remux status info

Show system information.

```bash
remux status info
```

**Example Output:**
```
Remux v1.0.0
Secure remote command execution with capability-based access control

Components:
  - Command Parser: Safe command extraction
  - Capability Model: Fine-grained permission control
  - Audit Logger: Comprehensive event logging
  - Circuit Breaker: Connection resilience
  - Rate Limiter: Per-client quotas
  - Policy Configuration: YAML/JSON support
```

### remux status health

Perform health check.

```bash
remux status health [options]

Options:
  --socket PATH       Daemon socket path
```

**Examples:**
```bash
# Check default daemon
remux status health

# Output:
# ✓ Health check passed
#   Daemon socket: accessible

# Check custom socket
remux status health --socket /tmp/remux.sock
```

---

## Configuration Files

### Policy Configuration (YAML)

Create `~/.rpipe/policies.yaml`:

```yaml
policies:
  # Reference built-in policy
  production:
    read_only

  # Custom policy
  database_admin:
    capabilities:
      - operation: read_file
        resource: /var/lib/postgresql/**/*
      - operation: execute_binary
        resource: psql|pg_dump|psql_restore
      - operation: write_file
        resource: /var/lib/postgresql/backups/**/*
      - operation: write_stdout
        resource: null
      - operation: write_stderr
        resource: null

  # Another custom policy
  monitoring:
    capabilities:
      - operation: read_file
        resource: /var/log/**/*
      - operation: execute_binary
        resource: grep|tail|head|cat|ps|top
      - operation: write_stdout
        resource: null
```

### Daemon Configuration

Create `~/.rpipe/daemon.conf`:

```bash
# Socket configuration
SOCKET_PATH=~/.rpipe/daemon.sock

# SSH host key verification
KNOWN_HOSTS=~/.ssh/known_hosts

# Audit logging
AUDIT_LOG_DIR=~/.rpipe/logs

# Rate limiting
RATE_LIMIT_REQUESTS_PER_SECOND=10
RATE_LIMIT_MAX_BURST=100

# Connection resilience
RETRY_MAX_ATTEMPTS=3
CIRCUIT_BREAKER_FAILURE_THRESHOLD=5
```

---

## Common Workflows

### 1. Setup for Production

```bash
# Initialize configuration
remux config init

# Create policies
remux policy create production --template read_only --output policies.yaml
remux policy create admin --template write_capable --output policies.yaml

# Validate policies
remux policy validate policies.yaml

# Start daemon with audit logging
remux daemon start \
  --known-hosts ~/.ssh/known_hosts \
  --audit-log-dir /var/log/remux

# Verify daemon is running
remux daemon status
remux status health
```

### 2. Daily Operations

```bash
# Check daemon status
remux daemon status

# List available policies
remux policy list

# Execute command with read-only policy
remux client run web1.example.com cat /var/log/syslog

# Execute with custom policy
remux client run db.example.com ls -la /data --policy database_admin

# View audit logs
remux daemon logs --follow
```

### 3. Troubleshooting

```bash
# Check daemon health
remux status health

# View logs
remux daemon logs --level ERROR

# Restart daemon
remux daemon stop
sleep 1
remux daemon start --foreground  # Debug mode

# Validate policies
remux policy validate policies.yaml

# Show specific policy
remux policy show database_admin --config policies.yaml
```

### 4. Custom Policy Deployment

```bash
# Create custom policy
remux policy create my_app \
  --template read_only \
  --output app_policy.yaml

# Edit policy file
vim app_policy.yaml

# Validate
remux policy validate app_policy.yaml

# Use in commands
remux client run app.example.com cat /var/log/app.log --policy my_app
```

---

## Exit Codes

- `0`: Success
- `1`: Command failed or error occurred
- `2`: Invalid arguments

---

## Environment Variables

- `RPIPE_SOCKET`: Default daemon socket path
- `RPIPE_KNOWN_HOSTS`: SSH known_hosts file path
- `RPIPE_AUDIT_LOG_DIR`: Audit log directory
- `RPIPE_POLICY_CONFIG`: Default policy configuration file

---

## See Also

- `remux -h, --help`: Show help for any command
- `remux -v, --verbose`: Enable verbose logging
- CLAUDE_CODE_EXAMPLES.md: Claude Code usage examples
- IMPLEMENTATION_SUMMARY.md: System architecture overview
- GETTING_STARTED.md: Quick start guide
