# vpn-switch Quick Reference

One-page command reference for common operations.

**Full documentation:** [README.md](README.md)
**Install:** [docs/INSTALL.md](docs/INSTALL.md)
**Help system:** `vpn-switch help`, `vpn-switch wireguard help`, `vpn-switch session help`

---

## Essential Commands

### Connect & Disconnect
```bash
vpn-switch start <config>            # Connect; resolves config/group/alias to its protocol
vpn-switch start                     # No arg: resume default session, else random config
vpn-switch wireguard start <config>  # Protocol-explicit start
vpn-switch openvpn start <config>    # Protocol-explicit start
vpn-switch stop                      # Stop every active VPN session
```

### Status & Information
```bash
vpn-switch status                    # Is the VPN up? Brief VPN + interface state
vpn-switch session list              # Show all active sessions
vpn-switch session show              # Show latest session details
vpn-switch session show <name|PID>   # Show specific session
vpn-switch printenv                  # Show effective configuration
vpn-switch version                   # DB SHA + source SHA (drift detection)
vpn-switch validate                  # Health check: install, DB, sessions, perms
vpn-switch inspect                   # Full descriptive state dump
```

---

## Config Management

### Import & List
```bash
vpn-switch wireguard import <path>   # Import WireGuard config
vpn-switch openvpn import <path>     # Import OpenVPN config
vpn-switch wireguard list            # List all WireGuard configs
vpn-switch openvpn list              # List all OpenVPN configs
vpn-switch wireguard info <group>    # Show group details with expiry info
```

### Organize (Groups & Aliases)
```bash
vpn-switch wireguard add streaming              # Create group (category)
vpn-switch wireguard add streaming wg-CH-12.conf ch-fast  # Link config into group, with alias
vpn-switch wireguard link ch wg-CH-12.conf      # Alias <name> -> config
vpn-switch link wg wireguard                    # Alias <name> -> protocol directory
```

### Maintenance
```bash
vpn-switch wireguard validate        # Check for broken symlinks
vpn-switch wireguard clean           # Generate commands to remove broken links
vpn-switch wireguard remove <name>   # Remove config (with safety checks)
```

---

## Session Management

### Save & Resume
```bash
vpn-switch session save work         # Save current session as "work"
vpn-switch session save              # Save as default session
vpn-switch session start work        # Resume "work" session
vpn-switch session start             # Resume default session
vpn-switch session switch work       # Stop all active sessions, resume "work"
vpn-switch session switch work home  # Stop only "home", resume "work"
```

### Manage
```bash
vpn-switch session list              # Show all active sessions
vpn-switch session show <name|PID>   # Show cached connect script + metadata
vpn-switch session remove <name|PID> # Remove a stopped session (refuses if active)
vpn-switch session clean             # Generate commands to clean stale sessions
```
See [docs/TUTORIAL_SESSIONS.md](docs/TUTORIAL_SESSIONS.md) for the save/resume workflow.

---

## Database Management

### Initialize, Sync, Restore
```bash
vpn-switch bootstrap /path minimal   # Create new database (minimal profile)
vpn-switch bootstrap /path all       # Create new database (all profile)
vpn-switch sync                      # Refresh DB against source templates after upgrade
vpn-switch version                   # Report db: and source: SHAs (drift detection)
vpn-switch dump                      # Export database as a restorable script
vpn-switch dump > backup.sh          # Save dump to file
vpn-switch restore backup.sh         # Replay a dump into a bootstrapped database
```
See [docs/TUTORIAL_MIGRATION.md](docs/TUTORIAL_MIGRATION.md) for the full dump/restore workflow.

### Configuration
```bash
vpn-switch printenv                  # Show all effective settings
vpn-switch setenv VAR value          # Set environment variable
vpn-switch getenv VAR                # Get environment variable
vpn-switch unsetenv VAR              # Unset environment variable
```

---

## Debugging & Diagnostics

### Logging
Logs and traces land in `$VPN_SWITCH_BASE/.log/<date>/` (default: 1 day retention).
```bash
ls -la $VPN_SWITCH_BASE/.log/$(date +%Y-%m-%d)/
cat $VPN_SWITCH_BASE/.log/$(date +%Y-%m-%d)/*.log     # external-command stderr
cat $VPN_SWITCH_BASE/.log/$(date +%Y-%m-%d)/*.trace   # execution traces

# Keep more (or disable with 0)
vpn-switch setenv VPN_SWITCH_RETENTION_DAYS_LOG 7
vpn-switch setenv VPN_SWITCH_RETENTION_DAYS_TRACE 7
```

### Cleanup
```bash
vpn-switch validate                  # Health check — start here when something is off
vpn-switch logs validate             # Check for old logs
vpn-switch logs clean                # Generate rm commands for old logs
vpn-switch logs clean | sh           # Execute cleanup (after review)
```
See [docs/TUTORIAL_TROUBLESHOOTING.md](docs/TUTORIAL_TROUBLESHOOTING.md) for `validate` walkthrough.

---

## Common Workflows

### Initial Setup
```bash
# 1. Install (system-wide; see docs/INSTALL.md)
sudo gmake install

# 2. Create per-user database (default path: ~/.vpn-switch/db)
vpn-switch bootstrap ~/.vpn-switch/db minimal

# 3. Import configs (one file per call)
vpn-switch wireguard import ~/Downloads/wg-CH-12.conf
vpn-switch openvpn import ~/Downloads/ch.ovpn
# Many files? Loop in your shell:
for f in ~/Downloads/*.conf; do vpn-switch wireguard import "$f"; done

# 4. Organize by purpose (create groups, then link configs in with aliases)
vpn-switch wireguard add streaming
vpn-switch wireguard add privacy
vpn-switch wireguard add streaming wg-DE-22.conf de-fast
vpn-switch wireguard add privacy wg-CH-12.conf ch-quiet

# 5. Verify
vpn-switch validate
```

### Daily Use
```bash
# Connect
vpn-switch start ch-quiet

# Check status
vpn-switch session list

# Disconnect
vpn-switch stop
```

### Work/Home Sessions
```bash
# At work: Connect and save
vpn-switch start de-fast
vpn-switch session save work

# At home: Connect and save
vpn-switch start ch-quiet
vpn-switch session save home

# Quick switch: stop the active session(s) and resume the target in one step
vpn-switch session switch work
vpn-switch session switch home
```

### Backup & Migration
```bash
# On old machine
vpn-switch dump > /tmp/vpn-backup.sh

# On new machine
vpn-switch bootstrap ~/.vpn-switch/db minimal
vpn-switch restore /tmp/vpn-backup.sh
vpn-switch validate                  # confirm restore
```
See [docs/TUTORIAL_MIGRATION.md](docs/TUTORIAL_MIGRATION.md) for details.

### Debugging Issues
```bash
vpn-switch validate                  # check this first
vpn-switch setenv VPN_SWITCH_RETENTION_DAYS_TRACE 7  # capture traces
vpn-switch start <config>            # reproduce
cat $VPN_SWITCH_BASE/.log/$(date +%Y-%m-%d)/*.trace  # read traces
vpn-switch session show <name|PID>   # inspect the connect script
```
For the full debugging methodology: [docs/DEBUGGING_GUIDE.md](docs/DEBUGGING_GUIDE.md)

---

## Environment Variables

### Essential
```bash
VPN_SWITCH_BASE                      # DB location (default: $HOME/.vpn-switch/db)
VPN_SWITCH_LIBDIR                    # Install location (set by installer, default: /usr/local/lib/vpn-switch)
```

### Debugging (Retention Days)
```bash
VPN_SWITCH_RETENTION_DAYS_LOG        # Log retention (default: 1 day, 0=disable)
VPN_SWITCH_RETENTION_DAYS_TRACE      # Trace retention (default: 1 day, 0=disable)
```

### Interface Names
```bash
VPN_SWITCH_INTERFACE_wireguard       # WireGuard interface (default: wg0)
VPN_SWITCH_INTERFACE_openvpn         # OpenVPN interface (default: tun0)
```

### WireGuard Keepalive
```bash
VPN_SWITCH_KEEPALIVE_wireguard       # PersistentKeepalive injected into patched
                                     # configs lacking one (default: 25, 0=disable)
```

### Profiles (chosen at bootstrap)
```bash
minimal                              # Cache only the essential variables (recommended)
all                                  # Cache the full variable set
# (a 'custom' profile also exists for hand-picked variable sets)
```

---

## Protocol-Specific Notes

### WireGuard
- `info` estimates expiry as **1 year after the config file's creation date** (typical VPN-provider lifetime); not a real-time query
- Uses `wg-quick up/down` for interface management
- DNS scripts: `/usr/local/sbin/wg-resolvconf-{up,down}`

### OpenVPN
- `import`/`patch` rewrite the config for daemon mode (adds `daemon`, `writepid`)
- Runs via `openvpn --daemon` with a PID file for background operation
- DNS scripts: `/usr/local/sbin/ovpn-resolvconf-{up,down}`

---

## Tips & Tricks

- **Default chains**: Symlinks express defaults (`default → protocol → group → config`)
- **Group resolution**: Starting a group uses its `default` symlink, or picks one at random
- **Inspect before running**: `session show` prints the exact connect script
- **Safe by default**: `clean` and `remove` emit commands for review; pipe to `sh` to run
- **Multi-protocol**: WireGuard and OpenVPN can run at the same time
- **Named sessions**: Save common setups (`session save`) and resume them (`session start`)
- **One-step switch**: `session switch <name>` stops the active session(s) and resumes `<name>`

---

## Getting Help

```bash
vpn-switch help                      # Main help
vpn-switch wireguard help            # WireGuard-specific help
vpn-switch openvpn help              # OpenVPN-specific help
vpn-switch session help              # Session management help
```

**Full documentation:** [README.md](README.md)
**Architecture:** [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)