# Usage Guide

## Host Management

### Add a Host

Interactive mode:
```bash
hostkeeper add
```

With flags:
```bash
hostkeeper add myserver --host 192.168.1.10 --user admin --password mypass
hostkeeper add myserver --host 10.0.0.1 --port 2222 --user root --key ~/.ssh/id_rsa
hostkeeper add webserver --host example.com --user deploy --password secret --group production --tags web,frontend
```

Flags:
- `--host` — hostname or IP address
- `--port` — SSH port (default: 22)
- `--user` — SSH username
- `--password` — SSH password
- `--key` — path to SSH private key
- `--auth-type` — authentication type (password, key, both)
- `--group` — host group for categorization
- `--tags` — comma-separated tags
- `--notes` — notes about the host

### List Hosts

```bash
hostkeeper list
hostkeeper ls  # alias
```

Filter by group or tag:
```bash
hostkeeper list --group production
hostkeeper list --tag web
```

Output formats:
```bash
hostkeeper list --format table  # default
hostkeeper list --format json
```

Sort options:
```bash
hostkeeper list --sort name      # default
hostkeeper list --sort hostname
hostkeeper list --sort group
```

### Connect to a Host

Connect using system SSH (default, full interactive terminal):
```bash
hostkeeper connect myserver
```

Connect with Go SSH client (direct mode, no interactive shell):
```bash
hostkeeper connect myserver --direct
```

Custom timeout:
```bash
hostkeeper connect myserver --timeout 60
```

### Edit a Host

Interactive mode:
```bash
hostkeeper edit myserver
```

With flags (only update what you specify):
```bash
hostkeeper edit myserver --host 10.0.0.1 --port 2222
hostkeeper edit myserver --user root --name myserver-renamed
hostkeeper edit myserver --group staging --tags backend
```

### Delete a Host

With confirmation prompt:
```bash
hostkeeper delete myserver
hostkeeper rm myserver  # alias
```

Skip confirmation:
```bash
hostkeeper delete myserver --force
```

## Data Management

### Export

Export all hosts, keys, and snippets to a JSON file:
```bash
hostkeeper export backup
hostkeeper export backup.json
```

### Import

Import from a previously exported JSON file:
```bash
hostkeeper import backup.json  # merge (default)
hostkeeper import backup.json --strategy replace
hostkeeper import backup.json --dry-run  # preview only
```

Merge strategies:
- `merge` — keep existing data, add new items (default)
- `replace` — replace all existing data with imported data

## TUI Interface

Launch the interactive terminal UI:
```bash
hostkeeper tui
```

Navigation:
- `↑`/`k` — move up
- `↓`/`j` — move down
- `Enter` — select host
- `q` — quit

## Shell Completion

Generate shell completion scripts:
```bash
hostkeeper completion bash > /etc/bash_completion.d/hostkeeper
hostkeeper completion zsh > /usr/local/share/zsh/site-functions/_hostkeeper
hostkeeper completion fish > ~/.config/fish/completions/hostkeeper.fish
hostkeeper completion powershell > hostkeeper.ps1
```

## Global Flags

- `--config` — path to custom config file
- `-v`/`--verbose` — verbose output (-v for info, -vv for debug)
- `--debug` — enable debug mode
- `--help` — display help