# General Usage

## Starting socktop

### Demo Mode

Try socktop without any setup:

```bash
# Launch demo mode
socktop --demo
```

Starts a temporary local agent on port 3231, connects to it, and monitors your local system. The agent stops when you quit (you'll see "Stopped demo agent on port 3231").

### Interactive Mode

Run `socktop` with no arguments to see an interactive profile menu (if you have saved profiles):

```
Select profile:
  1. prod
  2. dev-server
  3. demo
Enter number (or blank to abort):
```

Select a number to connect, or choose `demo` (always available). Press Enter on blank to abort.

### Monitor Remote System

Connect to a remote agent by specifying the WebSocket URL:

```bash
socktop ws://hostname:3000/ws
socktop ws://192.168.1.100:3000/ws
socktop wss://secure-host:8443/ws  # With TLS
```

### Using Connection Profiles

For frequently monitored systems, use profiles:

```bash
# Use a saved profile
socktop -P production-server
socktop -P rpi-cluster-01

# List available profiles
socktop --list-profiles
```

See [Connection Profiles](./connection-profiles.md).

## Keyboard and Mouse

### Keyboard

- Quit: `q` or `Esc`

### Mouse (Processes pane)

- Click "CPU %" to sort by CPU descending
- Click "Mem" to sort by memory descending
- Mouse wheel: scroll
- Drag scrollbar: scroll
- Arrow/PageUp/PageDown/Home/End: scroll

### Filtering Processes

Press `/` to enter filter mode:

```
Filter: pyth_
```

This will show only processes matching "pyth" (case-insensitive). Press `ESC` to clear filter.

## Command Line Options

### Client Options

```bash
socktop [OPTIONS] [URL]

OPTIONS:
  -P, --profile <PROFILE>              Use a connection profile
  -t, --token <TOKEN>                  Authentication token
  --tls-ca <FILE>                      CA certificate for TLS verification
  --verify-hostname                    Enable strict hostname verification for TLS
  --metrics-interval-ms <MS>           Fast metrics polling interval (default: 500)
  --processes-interval-ms <MS>         Process list polling interval (default: 2000)
  --list-profiles                      List available connection profiles
  -h, --help                           Show help information
  -V, --version                        Show version information

ARGUMENTS:
  [URL]                     WebSocket URL (e.g., ws://host:3000)
```

### Examples

```bash
# Connect with custom intervals
socktop ws://server:3000 --metrics-interval-ms 750 --processes-interval-ms 3000

# Connect with authentication token
socktop ws://server:3000 -t mySecretToken

# Connect with TLS and custom CA
socktop wss://server:3000 --tls-ca /path/to/ca.pem

# Connect with TLS and hostname verification
socktop wss://server:3000 --tls-ca /path/to/ca.pem --verify-hostname
```
