> For the complete documentation index, see [llms.txt](https://docs.gotempest.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gotempest.app/cli/tempest-cli.md). # Tempest CLI — Connections, Files & Collaboration Use Tempest from the terminal: connect to saved servers, transfer files, monitor SSH hosts, host or join encrypted collaboration sessions, and enable shell completion. The `tempest` command brings Tempest to your terminal. Use it to connect over SSH, Telnet or RCON, browse saved servers, transfer files, monitor a host, share a live shell, or run the MCP server for an AI client. On the same computer, the CLI and desktop app share accounts and the encrypted vault. Servers saved in the app are available to the CLI after sign-in and vault unlock. ## Install and check the command On macOS with Homebrew: ```bash brew install tempest-term/tempest/tempest-cli tempest --version ``` For other platforms, get the CLI from the [Tempest download page](https://gotempest.app/download) and put the `tempest` executable on your `PATH`. If you already have the executable and want a symlink, run it by its full path with `install-cli`. The default destination is `~/.local/bin/tempest`; make sure `~/.local/bin` is on your `PATH`. ```bash /path/to/tempest install-cli ``` The commands below describe the current CLI. Use your installed version's help to check available features: ```bash tempest --help tempest ssh --help tempest collab --help tempest fs cp --help ``` ## Sign in and unlock saved servers ```bash tempest login tempest unlock tempest ssh list ``` `login` prints a device code and a browser address. Complete sign-in in your browser; the command also works on a headless machine. `unlock` prompts for the vault password, which is separate from account sign-in. If the desktop app has already signed in and unlocked the same account, the CLI can reuse that state. To manage several accounts: ```bash tempest account list tempest account list --refresh tempest account add tempest account use you@example.com tempest --account you@example.com ssh list ``` `--account ` selects an account for one command; `TEMPEST_ACCOUNT` is the environment-variable equivalent. Adding a second account and switching accounts require Pro. Account changes also affect the desktop app on this computer. In particular, `account logout` signs the account out in the app too, but retains personal data as a local vault; it is not a local wipe. Use `account remove` to discard that account's local registration and files. Data already synced stays on the server. See [Accounts & Multiple Accounts](/accounts-vaults-and-privacy/accounts-and-vaults.md). `tempest account list --refresh` waits for fresh server account information and entitlements before listing. Without that flag, cached vault credentials can make an account available before its background refresh completes. A failed forced refresh is reported instead of silently treating cached values as fresh. For a self-hosted server, set the endpoint before signing in: ```bash tempest config set endpoint https://tempest.example.com tempest config show tempest login ``` `config unset endpoint` removes the saved override. The self-hosted server must have its OAuth applications configured; see [Docker Compose deployment](/self-hosting-and-web-mode/self-host-tempest-server-docker-compose.md). ## Connect over SSH Connect directly with a host, or use an ID from `tempest ssh list`: ```bash tempest ssh alice@server.example.com tempest ssh alice@server.example.com:2222 -i ~/.ssh/id_ed25519 tempest ssh --saved SERVER_ID tempest tui ``` `tui` opens an interactive picker for saved SSH, Telnet and RCON servers. Create or edit saved servers in the Tempest app; the CLI currently lists and connects to them, without an `ssh add` command. | Option | Purpose | | ----------------------------- | --------------------------------------------------------------------------------------------------- | | `-s, --saved ` | Connect using a saved SSH server; use this instead of a positional target. | | `-l, --login-name ` | Override the login username. | | `-p, --port ` | Override the port. | | `-i, --identity ` | Use an OpenSSH-format private key. Otherwise, SSH agent authentication is preferred when available. | | `--password` / `--passphrase` | Prompt for the secret. A value of `-` reads it from stdin. | | `--auto-reconnect` | Retry a dropped connection with backoff. | | `-X, --x11` | Forward X11 to the local display. | | `--mosh` | Start over SSH, then carry the terminal over mosh/UDP. | | `--mosh-server ` | Specify the remote mosh server command; implies `--mosh`. | | `--timeout ` | Set the connection timeout; default 30 seconds. | Use a prompt or SSH agent for secrets so they do not end up in shell history. X11, auto-reconnect and other advanced features follow your account's feature entitlements. ## Remote development with VS Code The **Tempest Remote** extension uses the CLI to open saved SSH servers through Microsoft Remote - SSH. Install the extension locally, then select **Tempest: Connect to Server** from VS Code's remote indicator or Command Palette. Check that your CLI includes both `control` and `pipe`: ```bash tempest remote --help ``` The extension invokes `tempest remote control --protocol 1`. Control handles authentication and establishes the tunnel; OpenSSH runs `tempest remote pipe --host --session ` as its generated ProxyCommand to attach and transfer SSH data. Update the CLI and extension together. The last pipe's disconnection starts a three-second reconnect grace, then control releases the tunnel and exits. Setup without an attach expires after 120 seconds. On Unix, proxy termination signals are forwarded to control for the corresponding pipe. Remote development requires a verified `portForwarding` entitlement and a vault policy that permits TCP forwarding. See [Tempest Remote — VS Code setup and troubleshooting](/integrations/tempest-remote-vscode.md). ## Monitor an SSH host ```bash tempest ssh monitor --saved SERVER_ID tempest ssh monitor alice@server.example.com --once --json ``` The monitor uses the same collectors as the desktop monitor: load, CPU, memory, filesystems, processes, listening sockets and Docker containers. `--once` takes one sample; `--json` provides machine-readable output. Monitoring requires the monitoring entitlement. Check `tempest ssh monitor --help` for authentication and sudo options. ## Transfer and browse files `tempest fs` (also `tempest filemanager`) supports local paths and `file://`, `sftp://`, `s3://`, `webdav://` and `ftp://` URLs. ```bash tempest fs ls -l sftp://alice@server.example.com/var/log tempest fs cp ./report.txt sftp://alice@server.example.com/tmp/report.txt tempest fs cp --saved SERVER_ID /var/log/app.log ./app.log tempest fs mkdir --parents sftp://alice@server.example.com/tmp/reports tempest fs tui sftp://alice@server.example.com/var/log ``` With `--saved`, remote-looking paths are resolved against the saved SSH host. Use `./` or `~/` to make a local path explicit, as in the copy example above. `fs tui` opens a dual-pane file manager. `fs rm` and `fs mv` remove and move files; add `--recursive` where needed for directories. Authentication options depend on the storage backend. Run `tempest fs cp --help` for private keys, S3 credentials, WebDAV/FTP credentials and endpoint overrides. ## Collaborate from the terminal CLI collaboration connects to the same encrypted rooms as the app's [Handoff sessions](/collaboration-and-handoff/handoff-live-collaboration.md). Everyone sees the host's live terminal; input is sent to the host when the participant has write permission. The shell continues to run on the host machine. Sign in to the same Tempest server and unlock the selected account's vault before hosting or joining. Hosting requires the collaboration entitlement (Pro); joining an accessible room does not require the hosting entitlement. ### Join a session from your other device 1. In the desktop app, enable **Settings → General → Collaboration → Auto-share with my other devices**, or share the terminal you want to join. 2. On the CLI machine, sign in to the same account and unlock the vault. 3. List rooms, then join one: ```bash tempest collab list tempest collab join ROOM_ID ``` The list shows the room ID, your role, whether you can write, and the title. A unique prefix of the room ID also works. To watch without sending keyboard input, even if you have write permission: ```bash tempest collab join ROOM_ID --read-only ``` ### Host a local shell ```bash tempest collab host --title "Incident investigation" ``` This starts a **new local shell** and prints its room ID and a join command. Open Handoff on another device signed in to the same account, or run `tempest collab list` and `tempest collab join ROOM_ID` there. The host process must stay running and connected. By default the command uses `$SHELL`, falling back to `/bin/sh`. To choose a shell executable: ```bash tempest collab host --command /bin/bash --title "Shared Bash session" ``` `--command` selects the shell executable; it is not an arbitrary command line with arguments. Once inside the shared shell, you can run SSH, a build, a diagnostic command or another terminal program. This shares the local shell's screen, including the programs you launch in it; it does not attach to an existing shell. When the hosted shell exits normally, the CLI attempts to end the room. If a host was terminated abruptly or a stale room remains, end it from a second terminal: ```bash tempest collab end ROOM_ID ``` This ends the collaboration room; use the host shell to stop any programs running there. ### Invites and current CLI limits The CLI currently exposes `list`, `join`, `host` and `end`. It does not create email invites or invite links, manage participant permissions, or accept an invite URL as the join target. Use the app for those actions. For a room shared from another account, the CLI may report that it must be joined from the Tempest app because an additional room password/key is required. Use the app's Handoff workflow for that case. A room ID identifies a session; it does not grant access by itself. ## Shell completion `tempest completions ` prints a completion script for Bash, Zsh, Fish, PowerShell or Elvish. It completes subcommands, aliases, options and fixed argument choices from the CLI definition. It does not query your accounts, saved-server IDs or room IDs. Homebrew installs Bash, Zsh and Fish completion files with the CLI version that includes this feature. For other installation methods, use the steps below. If `completions` is absent from `tempest --help`, upgrade to a version that provides it. ### Zsh ```zsh mkdir -p ~/.zsh/completions tempest completions zsh > ~/.zsh/completions/_tempest ``` Add this to `~/.zshrc` **before** an existing `compinit` call: ```zsh fpath=(~/.zsh/completions $fpath) ``` If your configuration does not already initialize completion, also add `autoload -Uz compinit; compinit`. Restart the shell. ### Bash Add this to `~/.bashrc`: ```bash source <(tempest completions bash) ``` Load that file or start a new Bash session. If your login shell only reads `~/.bash_profile`, make sure it sources `~/.bashrc`. ### Fish ```fish mkdir -p ~/.config/fish/completions tempest completions fish > ~/.config/fish/completions/tempest.fish ``` ### PowerShell Add this to your PowerShell `$PROFILE`: ```powershell tempest completions powershell | Out-String | Invoke-Expression ``` ### Elvish ```elvish mkdir -p ~/.config/elvish/lib tempest completions elvish > ~/.config/elvish/lib/tempest.elv ``` Add `use tempest` to `~/.config/elvish/rc.elv`. Regenerate saved scripts after upgrading the CLI. Bash and PowerShell examples above generate them when the shell starts. ## Other commands at a glance | Command | What it does | | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `tempest telnet HOST:PORT` | Open an interactive Telnet session; `telnet list` and `telnet --saved ID` use saved entries. | | `tempest rcon HOST:PORT` | Open a Source-engine RCON REPL; `rcon list` and `rcon --saved ID` use saved entries. | | `tempest serial list` | List saved serial ports; serial connections are not yet available in the CLI. | | `tempest localshell list` / `tempest localshell ID` | List or launch a saved local-shell command. | | `tempest history --help` | Browse, compare, copy or restore encrypted vault document revisions (Pro). This is different from Drive run history. | | `tempest mcp` | Start the MCP server over stdio for an AI client. | | `tempest mcp --http 127.0.0.1:53079` | Start streamable HTTP MCP at the explicit address; the default HTTP mode trusts local processes. | | `tempest config show` | Show effective endpoint and OAuth client configuration. | | `tempest install-cli --uninstall` | Remove the CLI symlink installed by `install-cli`. | For document revision browsing and restore examples, see [Vault History](/accounts-vaults-and-privacy/vault-history.md). For MCP client setup, see [Use Tempest in AI Agents (Desktop or CLI)](/ai-and-automation/install-tempest-mcp-server-in-ai-clients.md). ## Troubleshooting * **Command not found:** check the executable's directory is on `PATH`, and reopen the terminal after installation. * **Vault locked:** run `tempest unlock` for the selected account, or unlock it in the desktop app on the same machine. * **Saved server missing:** check `tempest account list`, select the intended account and confirm the server is saved in its vault. * **No active collaboration sessions:** check the account and endpoint on both devices, and confirm the host is still running and sharing. * **Room prefix is ambiguous:** use a longer prefix or the full ID from `tempest collab list`. * **Unknown command or option:** check `tempest --version` and the relevant `--help`; your installed release may predate the feature. ## See also * [Handoff — Pick Up a Session Anywhere, or Share It](/collaboration-and-handoff/handoff-live-collaboration.md) * [Tempest Drive — Saved Commands & Scheduled Runs](/ai-and-automation/snippets-scheduled-runs.md) * [Mosh — Survive Flaky Connections](/connections-and-ssh/mosh-mobile-shell.md) * [Where Tempest Stores Your Credentials](/accounts-vaults-and-privacy/where-tempest-stores-credentials.md)