swanadiva
48c858df0f
- Task 13: Full documentation (README, INSTALLATION, USAGE, ARCHITECTURE) - Task 14: Release prep (CHANGELOG, RELEASE_CHECKLIST) - Update PROJECT_STATE.md to reflect 100% completion
152 lines
3.1 KiB
Markdown
152 lines
3.1 KiB
Markdown
# 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
|