CLI Reference¶
Command-line interface documentation for router-hosts.
Auto-generated
This documentation is auto-generated from router-hosts --help.
Global Usage¶
router-hosts is a CLI for managing /etc/hosts entries through a gRPC server with mTLS authentication.
Usage:
router-hosts [command]
Available Commands:
completion Generate the autocompletion script for the specified shell
help Help about any command
host Manage host entries
serve Start the gRPC server
server Server health and status commands
snapshot Manage database snapshots
Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
--config string path to config file (default: auto-detected)
-f, --format string output format: table, json, csv (default: table for TTY, json for pipes)
-h, --help help for router-hosts
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output
--version version for router-hosts
Use "router-hosts [command] --help" for more information about a command.
completion¶
Generate the autocompletion script for router-hosts for the specified shell.
See each sub-command's help for details on how to use the generated script.
Usage:
router-hosts completion [command]
Available Commands:
bash Generate the autocompletion script for bash
fish Generate the autocompletion script for fish
powershell Generate the autocompletion script for powershell
zsh Generate the autocompletion script for zsh
Flags:
-h, --help help for completion
Global Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
--config string path to config file (default: auto-detected)
-f, --format string output format: table, json, csv (default: table for TTY, json for pipes)
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output
Use "router-hosts completion [command] --help" for more information about a command.
completion bash¶
Generate the autocompletion script for the bash shell.
This script depends on the 'bash-completion' package.
If it is not installed already, you can install it via your OS's package manager.
To load completions in your current shell session:
source <(router-hosts completion bash)
To load completions for every new session, execute once:
#### Linux:
router-hosts completion bash > /etc/bash_completion.d/router-hosts
#### macOS:
router-hosts completion bash > $(brew --prefix)/etc/bash_completion.d/router-hosts
You will need to start a new shell for this setup to take effect.
Usage:
router-hosts completion bash
Flags:
-h, --help help for bash
--no-descriptions disable completion descriptions
Global Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
--config string path to config file (default: auto-detected)
-f, --format string output format: table, json, csv (default: table for TTY, json for pipes)
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output
completion fish¶
Generate the autocompletion script for the fish shell.
To load completions in your current shell session:
router-hosts completion fish | source
To load completions for every new session, execute once:
router-hosts completion fish > ~/.config/fish/completions/router-hosts.fish
You will need to start a new shell for this setup to take effect.
Usage:
router-hosts completion fish [flags]
Flags:
-h, --help help for fish
--no-descriptions disable completion descriptions
Global Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
--config string path to config file (default: auto-detected)
-f, --format string output format: table, json, csv (default: table for TTY, json for pipes)
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output
completion powershell¶
Generate the autocompletion script for powershell.
To load completions in your current shell session:
router-hosts completion powershell | Out-String | Invoke-Expression
To load completions for every new session, add the output of the above command
to your powershell profile.
Usage:
router-hosts completion powershell [flags]
Flags:
-h, --help help for powershell
--no-descriptions disable completion descriptions
Global Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
--config string path to config file (default: auto-detected)
-f, --format string output format: table, json, csv (default: table for TTY, json for pipes)
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output
completion zsh¶
Generate the autocompletion script for the zsh shell.
If shell completion is not already enabled in your environment you will need
to enable it. You can execute the following once:
echo "autoload -U compinit; compinit" >> ~/.zshrc
To load completions in your current shell session:
source <(router-hosts completion zsh)
To load completions for every new session, execute once:
#### Linux:
router-hosts completion zsh > "${fpath[1]}/_router-hosts"
#### macOS:
router-hosts completion zsh > $(brew --prefix)/share/zsh/site-functions/_router-hosts
You will need to start a new shell for this setup to take effect.
Usage:
router-hosts completion zsh [flags]
Flags:
-h, --help help for zsh
--no-descriptions disable completion descriptions
Global Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
--config string path to config file (default: auto-detected)
-f, --format string output format: table, json, csv (default: table for TTY, json for pipes)
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output
host¶
Manage host entries
Usage:
router-hosts host [command]
Aliases:
host, h
Available Commands:
add Add a new host entry
delete Delete a host entry
export Export hosts to a file or stdout
get Get a host entry by ID
import Import hosts from a file
list List all host entries
search Search host entries
update Update an existing host entry
Flags:
-h, --help help for host
Global Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
--config string path to config file (default: auto-detected)
-f, --format string output format: table, json, csv (default: table for TTY, json for pipes)
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output
Use "router-hosts host [command] --help" for more information about a command.
host add¶
Add a new host entry
Usage:
router-hosts host add [flags]
Flags:
--aliases strings comma-separated aliases
--comment string optional comment
-h, --help help for add
--hostname string hostname (required)
--ip string IP address (required)
--tags strings comma-separated tags
Global Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
--config string path to config file (default: auto-detected)
-f, --format string output format: table, json, csv (default: table for TTY, json for pipes)
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output
host delete¶
Delete a host entry
Usage:
router-hosts host delete <id> [flags]
Flags:
-h, --help help for delete
Global Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
--config string path to config file (default: auto-detected)
-f, --format string output format: table, json, csv (default: table for TTY, json for pipes)
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output
host export¶
Export hosts to a file or stdout
Usage:
router-hosts host export [flags]
Flags:
--format string export format: hosts, json, csv (default "hosts")
-h, --help help for export
-o, --output string output file (default: stdout)
Global Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
--config string path to config file (default: auto-detected)
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output
host get¶
Get a host entry by ID
Usage:
router-hosts host get <id> [flags]
Flags:
-h, --help help for get
Global Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
--config string path to config file (default: auto-detected)
-f, --format string output format: table, json, csv (default: table for TTY, json for pipes)
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output
host import¶
Import host entries from a file. Supported formats: hosts (default), json, csv.
Usage:
router-hosts host import <file> [flags]
Flags:
--conflict-mode string conflict handling: skip, replace, strict (default: skip)
--force override strict mode validation
--format string import format: hosts, json, csv (default: hosts)
-h, --help help for import
Global Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
--config string path to config file (default: auto-detected)
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output
host list¶
List all host entries
Usage:
router-hosts host list [flags]
Flags:
--filter string filter expression
-h, --help help for list
--limit int32 max entries to return
--offset int32 entries to skip
Global Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
--config string path to config file (default: auto-detected)
-f, --format string output format: table, json, csv (default: table for TTY, json for pipes)
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output
host search¶
Search host entries
Usage:
router-hosts host search <query> [flags]
Flags:
-h, --help help for search
Global Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
--config string path to config file (default: auto-detected)
-f, --format string output format: table, json, csv (default: table for TTY, json for pipes)
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output
host update¶
Update an existing host entry
Usage:
router-hosts host update <id> [flags]
Flags:
--aliases strings new aliases (replaces existing)
--comment string new comment
-h, --help help for update
--hostname string new hostname
--ip string new IP address
--tags strings new tags (replaces existing)
--version string expected version for optimistic concurrency
Global Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
--config string path to config file (default: auto-detected)
-f, --format string output format: table, json, csv (default: table for TTY, json for pipes)
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output
serve¶
Start the router-hosts gRPC server with mTLS, loading configuration from a TOML file.
Usage:
router-hosts serve [flags]
Flags:
--config string path to server TOML config file (required)
-h, --help help for serve
Global Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
-f, --format string output format: table, json, csv (default: table for TTY, json for pipes)
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output
server¶
Server health and status commands
Usage:
router-hosts server [command]
Available Commands:
health Check server health
liveness Check server liveness
readiness Check server readiness
Flags:
-h, --help help for server
Global Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
--config string path to config file (default: auto-detected)
-f, --format string output format: table, json, csv (default: table for TTY, json for pipes)
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output
Use "router-hosts server [command] --help" for more information about a command.
server health¶
Check server health
Usage:
router-hosts server health [flags]
Flags:
-h, --help help for health
Global Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
--config string path to config file (default: auto-detected)
-f, --format string output format: table, json, csv (default: table for TTY, json for pipes)
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output
server liveness¶
Check server liveness
Usage:
router-hosts server liveness [flags]
Flags:
-h, --help help for liveness
Global Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
--config string path to config file (default: auto-detected)
-f, --format string output format: table, json, csv (default: table for TTY, json for pipes)
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output
server readiness¶
Check server readiness
Usage:
router-hosts server readiness [flags]
Flags:
-h, --help help for readiness
Global Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
--config string path to config file (default: auto-detected)
-f, --format string output format: table, json, csv (default: table for TTY, json for pipes)
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output
snapshot¶
Manage database snapshots
Usage:
router-hosts snapshot [command]
Aliases:
snapshot, snap, s
Available Commands:
create Create a database snapshot
delete Delete a snapshot
list List all snapshots
rollback Rollback to a snapshot
Flags:
-h, --help help for snapshot
Global Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
--config string path to config file (default: auto-detected)
-f, --format string output format: table, json, csv (default: table for TTY, json for pipes)
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output
Use "router-hosts snapshot [command] --help" for more information about a command.
snapshot create¶
Create a database snapshot
Usage:
router-hosts snapshot create [flags]
Flags:
-h, --help help for create
--name string snapshot name (auto-generated if empty)
--trigger string trigger reason (default "manual")
Global Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
--config string path to config file (default: auto-detected)
-f, --format string output format: table, json, csv (default: table for TTY, json for pipes)
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output
snapshot delete¶
Delete a snapshot
Usage:
router-hosts snapshot delete <snapshot-id> [flags]
Flags:
-h, --help help for delete
Global Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
--config string path to config file (default: auto-detected)
-f, --format string output format: table, json, csv (default: table for TTY, json for pipes)
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output
snapshot list¶
List all snapshots
Usage:
router-hosts snapshot list [flags]
Flags:
-h, --help help for list
--limit uint32 max snapshots to return
--offset uint32 snapshots to skip
Global Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
--config string path to config file (default: auto-detected)
-f, --format string output format: table, json, csv (default: table for TTY, json for pipes)
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output
snapshot rollback¶
Rollback to a snapshot
Usage:
router-hosts snapshot rollback <snapshot-id> [flags]
Flags:
-h, --help help for rollback
Global Flags:
--ca string path to CA certificate for server verification
--cert string path to client TLS certificate
--config string path to config file (default: auto-detected)
-f, --format string output format: table, json, csv (default: table for TTY, json for pipes)
--key string path to client TLS private key
-q, --quiet suppress non-essential output
--server string gRPC server address (host:port)
-v, --verbose enable verbose output