In a terminal, missing add fields are prompted interactively: fleetsh add hk1. In scripts and with --json, supply the required flags explicitly. See interactive setup.

Getting started

Start by adding one host and checking its SSH login. See installation and PATH if the command is not on your PATH.

Run with npx or npm

Use Node.js 22 or newer:

npx fleetsh add hk1 --host hk1.example.com --user ubuntu --auth key --key ~/.ssh/id_ed25519
npx fleetsh ssh hk1
npx fleetsh alive
npx fleetsh stats

Or install globally with npm install -g fleetsh and replace the npx fleetsh prefix with fleetsh in every example. Both use the same inventory and OS credential store as the direct binary.

The launcher automatically follows GitHub Releases, preferring stable releases and using previews only while no stable release exists. Place launcher options before the command: npx fleetsh --release bundled version selects the original binary; --release v0.1.0-alpha.1 selects an exact Go version. Run npx fleetsh --launcher-help or read version selection, caching and PATH.

Help and offline guides

The binary includes English command help with examples and English offline guides. Help and guides work before init, without an inventory, network connection or credential store. Online editions remain separate; English is the default.

fleetsh --help
fleetsh help exec
fleetsh add --help
fleetsh docs
fleetsh docs passwords
fleetsh docs groups
fleetsh docs patching

Use fleetsh docs TOPIC to open a guide. Guides print plain text; --json applies to supported inventory and batch-result commands, not documentation. Reading help never executes its examples or opens the printed documentation links.

Missing/extra positional arguments and invalid flags print an error plus the command help (syntax, examples and flags) to stderr, with exit code 2. For example, npx fleetsh exec and npx fleetsh exec whoami show help because exec requires both a host/group selector and one quoted command: npx fleetsh exec '@all' "whoami". Help links use the directly served HTTPS documentation address, avoiding the HTTP redirect inherited by the default GitHub Pages URL.

Add your first host

add automatically creates a missing inventory and parent directories when the host is saved. init is optional for an empty commented example. Existing invalid or unreadable files are reported, not replaced. Invalid host options or cancelled password input do not create an inventory file. Other commands suggest add or init when the inventory is missing; use the same --config PATH on every command. If an alias already exists, use edit HOST to change it.

The inventory is stored locally for your OS user: %APPDATA%\fleetsh\config.toml on Windows, ~/Library/Application Support/fleetsh/config.toml on macOS, and $XDG_CONFIG_HOME/fleetsh/config.toml or ~/.config/fleetsh/config.toml on Linux. See storage locations, custom inventories and backup.

fleetsh add hk1 --host hk1.example.com --user ubuntu --auth key --key ~/.ssh/id_ed25519 --groups asia,web
fleetsh add sg1 --host sg1.example.com --user ubuntu --auth password --groups asia
fleetsh ls
fleetsh ls '@asia' --json
fleetsh show hk1
fleetsh edit hk1 --port 2222

Required host arguments and options

HOST in fleetsh add HOST is a local alias, not the address. Required values:

For new hosts, --auth is optional and defaults to password; --port defaults to 22. Omitting --auth prompts twice and saves the password in the OS credential store. Use --auth agent only with a running SSH agent and a loaded key, or --auth key --key PATH for a private key. Existing hosts keep their saved authentication mode. If an older host reports SSH agent unavailable, switch it to password login with fleetsh edit HOST --auth password, then retry fleetsh ssh HOST. Use the same --config PATH on both commands for a custom inventory. Password authentication prompts privately; no password option is required. When adding a host, missing or empty required options are listed with command help before inventory loading or credential prompts. Invalid host options also show help. edit HOST preserves omitted fields and checks the resulting values: changing --connection to ssh or --auth to key may require --user or --key. Console-only hosts may omit --user. Use fleetsh add --help or fleetsh edit --help.

The password prompt is hidden. Credential values are stored in the OS credential store; inventory stores only reference names. Key passphrases can use the same --credential field; without a reference they are prompted privately.

Adding a password-authenticated host now prompts twice and saves the password automatically. The generated reference has a fleetsh-ssh- prefix; the inventory holds only its name. Use fleetsh edit sg1 --save-password to update the password without managing references. See password storage and changing groups.

Every command accepts --config PATH. Paths beginning with ~/ are expanded. The inventory file is validated strictly; unknown fields and plaintext password fields are rejected. edit rewrites TOML and does not preserve comments.

Establish host identity

fleetsh ssh hk1 --connect-timeout 60s
fleetsh hostkey show hk1

First connections display a SHA256 fingerprint and require an interactive y. Verify it through an independent source before trusting. This prompt shares the connection deadline; allow time with --connect-timeout. Changed host keys are always rejected. Unattended commands reject unknown keys.

After independently verifying a legitimate key rotation:

fleetsh hostkey reset hk1
fleetsh ssh hk1 --connect-timeout 60s

The dedicated known_hosts file sits next to the selected inventory file. SSH interactive sessions use PTY/raw terminal mode when stdin is a terminal, and forward terminal size changes. Port forwards use fleetsh forward with named profiles; OpenSSH argument passthrough remains deferred.

One-command remote monitoring

fleetsh alive
fleetsh stats
fleetsh alive '@web' --timeout 10s
fleetsh stats '@web' --parallel 5 --timeout 15s
fleetsh monitor hk1
fleetsh stats --json

alive checks authenticated SSH execution, rather than ICMP. stats (alias monitor) prints one Linux snapshot: whoami, one-second CPU busy percentage, memory and swap usage in MiB/percent, and df -h -P with free disk space. Both default to @all and accept selectors, tags, parallelism and timeout flags. Console-only assets are skipped. JSON uses the standard batch report, with each snapshot in its host’s stdout field.

No agent installation or sudo is required. Linux /proc, awk, sleep, whoami and df must be available. Memory is total minus available; swap disabled is shown as zero. CPU reflects host counters, not container quotas. Each invocation takes one snapshot. --sudo can change the reported user. Run fleetsh docs monitoring for the offline guide.

Port-forward profiles are started with fleetsh forward HOST [NAME]; see local, remote and dynamic configuration.

Execute

Quote group selectors in PowerShell: “fleetsh ls ‘@asia’”. The quotes prevent PowerShell from interpreting the @ prefix as variable splatting. Quoted selectors also work in Bash and Zsh.

fleetsh exec hk1 "uptime"
fleetsh exec '@asia' "df -h" --parallel 10
fleetsh exec hk1,sg1 "uptime" --serial --json
fleetsh exec all "docker ps" --tag web --timeout 60s
fleetsh exec hk1 "apt-get update" --sudo

--sudo uses passwordless sudo -n unless the host has sudo_credential. A referenced sudo password is sent over channel stdin, never inserted in the command. Commands receive no interactive stdin; use ssh for interactive programs.

Output is grouped per host and bounded to 4 MiB per stdout/stderr stream. JSON contains results and summary, with host, exit status, timing, error category, truncation and skipping fields. Console-only assets are explicitly skipped.

Exit codes: 0 all executable targets succeeded; 1 a command failed or execution was canceled/timed out; 2 local usage/configuration/credential preparation error; 3 connection/authentication/proxy/host-key failure, including connection timeout. A command failure takes precedence in mixed remote failures. Interactive shell nonzero remote exit status returns 1; transport failure returns 3.

Edit a host or correct a saved password

In a terminal, edit HOST opens a menu; scripts and --json require a change option. show HOST prints current settings. See everyday operations for guided setup, diagnostics, monitoring, saved commands and file transfers. If you saved a password incorrectly, enter the correct server password twice:

npx fleetsh edit hk1 --save-password
npx fleetsh ssh hk1
npx fleetsh docs password

This updates the locally saved copy only. See password recovery. Keep the spaces in npx fleetsh docs password; fleetshdocs is a different npm package.

Update and reboot Linux VPSs

fleetsh update '@asia' --dry-run --sudo
fleetsh update '@asia' --sudo
fleetsh update hk1 --dist --sudo --yes
fleetsh reboot '@asia' --dry-run --sudo
fleetsh reboot '@asia' --parallel 2 --sudo --wait-timeout 5m

Update dry runs connect to identify the OS but never dispatch package updates. Supported IDs: Debian, Ubuntu, RHEL, Rocky, AlmaLinux, Fedora, CentOS, Arch and Manjaro. An unsupported OS or failed preflight prevents updates on every target. Reboot dry runs do not connect.

Actual updates and reboots show selected aliases and require confirmation; use --yes for explicit automation approval. Reboot concurrency defaults to 2. A reboot succeeds only after a changed Linux boot ID and successful uptime probe. No commands are automatically retried.

For a complete maintenance workflow, see Patch every VPS.