socktop-webterm/docs/src/usage/connection-profiles.md

# Connection Profiles

Connection profiles allow you to save frequently used agent connections for quick access.

## What are Connection Profiles?

Instead of typing the full WebSocket URL every time:

```bash
socktop ws://production-server.example.com:3000
```

You can save it as a profile and use:

```bash
socktop -P production
```

## Profile Configuration File

Profiles are stored in `~/.config/socktop/profiles.json` (or `$XDG_CONFIG_HOME/socktop/profiles.json`).

### Basic Profile Format

```json
{
  "profiles": {
    "production": {
      "url": "ws://production-server:3000/ws"
    },
    "dev": {
      "url": "ws://dev-server:3000/ws"
    },
    "rpi": {
      "url": "ws://192.168.1.100:3000/ws"
    }
  },
  "version": 0
}
```

### Profile with Authentication

```json
{
  "profiles": {
    "secure-server": {
      "url": "wss://secure.example.com:3000/ws?token=your-secret-token-here"
    }
  },
  "version": 0
}
```

**Note:** Tokens are passed as query parameters in the URL.

### Profile with TLS Configuration

```json
{
  "profiles": {
    "tls-server": {
      "url": "wss://tls-server.example.com:8443/ws",
      "tls_ca": "/path/to/cert.pem"
    }
  },
  "version": 0
}
```

### Profile with All Options

```json
{
  "profiles": {
    "full-config": {
      "url": "wss://example.com:8443/ws?token=secret-token",
      "tls_ca": "/etc/socktop/cert.pem",
      "metrics_interval_ms": 750,
      "processes_interval_ms": 3000
    }
  },
  "version": 0
}
```

**Note:** Custom intervals are optional. Values below 100ms (metrics) or 200ms (processes) are clamped.

## Creating Profiles

### Method 1: Manual Creation

Create or edit the profiles file:

```bash
mkdir -p ~/.config/socktop
nano ~/.config/socktop/profiles.json
```

Add your profiles:

```json
{
  "profiles": {
    "homelab": {
      "url": "ws://192.168.1.50:3000/ws"
    },
    "cloud-server": {
      "url": "wss://cloud.example.com:8443/ws?token=abc123xyz",
      "tls_ca": "/home/user/.config/socktop/cloud-cert.pem"
    }
  },
  "version": 0
}
```

### Method 2: Automatic Profile Creation

When you specify a new `--profile/-P` name with a URL (and optional `--tls-ca`), it's saved automatically:

```bash
# First connection creates and saves the profile
socktop --profile prod ws://prod-host:3000/ws

# With TLS pinning
socktop --profile prod-tls --tls-ca /path/to/cert.pem wss://prod-host:8443/ws

# With custom intervals
socktop --profile fast --metrics-interval-ms 250 --processes-interval-ms 1000 ws://host:3000/ws
```

To overwrite an existing profile without prompt, use `--save`:

```bash
socktop --profile prod --save ws://new-host:3000/ws
```

## Using Profiles

### Basic Usage

```bash
# Use a saved profile
socktop -P production
socktop --profile homelab
```