# Bast.sh — full documentation > Browse SSH hosts, manage keys, and connect from the terminal. The fast way into the servers you use every day. Agent skill: https://bast.sh/bast.skill.md (install: curl -fsSL https://bast.sh/install-skill | sh) Docs index: https://bast.sh/llms.txt --- # Introduction (https://bast.sh/docs) Bast is a terminal app for browsing SSH hosts, managing keys, and connecting fast. Run `bast` and you get a full-screen interface with hosts on one tab and keys on the other. Pick a server, press Enter, and Bast hands off to your system `ssh` binary. No custom protocol, no cloud sync, no hidden database. Bast reads the SSH configuration you already have, adds presentation metadata on top (groups, tags, favorites, notes), and keeps OpenSSH as the source of truth. {"name":"DemoScreenshot","children":"","attributes":{"src":"/intro.png","alt":"The Bast host picker with hosts and keys tabs","width":{"type":"mdxJsxAttributeValueExpression","value":"1600","data":{"estree":{"type":"Program","start":572,"end":576,"body":[{"type":"ExpressionStatement","expression":{"type":"Literal","start":572,"end":576,"loc":{"start":{"line":13,"column":9,"offset":572},"end":{"line":13,"column":13,"offset":576}},"value":1600,"raw":"1600","range":[572,576]},"start":572,"end":576,"loc":{"start":{"line":13,"column":9,"offset":572},"end":{"line":13,"column":13,"offset":576}},"range":[572,576]}],"sourceType":"module","comments":[],"loc":{"start":{"line":13,"column":9,"offset":572},"end":{"line":13,"column":13,"offset":576}},"range":[572,576]}}},"height":{"type":"mdxJsxAttributeValueExpression","value":"640","data":{"estree":{"type":"Program","start":588,"end":591,"body":[{"type":"ExpressionStatement","expression":{"type":"Literal","start":588,"end":591,"loc":{"start":{"line":14,"column":10,"offset":588},"end":{"line":14,"column":13,"offset":591}},"value":640,"raw":"640","range":[588,591]},"start":588,"end":591,"loc":{"start":{"line":14,"column":10,"offset":588},"end":{"line":14,"column":13,"offset":591}},"range":[588,591]}],"sourceType":"module","comments":[],"loc":{"start":{"line":14,"column":10,"offset":588},"end":{"line":14,"column":13,"offset":591}},"range":[588,591]}}}}} ## What you can do [#what-you-can-do] * Browse and search every host in your SSH config, including `Include` files * Add, edit, favorite, and hide hosts with groups, tags, colors, and notes * Generate, import, export, and install SSH keys from the same interface * Connect with one keypress, or jump straight in from the shell with `bast ` * Automate everything through the CLI with optional JSON output ## Requirements [#requirements] * macOS or Linux * OpenSSH: `ssh`, `ssh-keygen`, `ssh-add` * A Nerd Font is recommended for some glyphs, but Bast works without one ## Quick start [#quick-start] | Command | What it does | | ----------------------- | ------------------------------------------------- | | `bast` | Open the host picker | | `bast update` | Update Bast when installed via the bast.sh script | | `bast ` | Connect directly to a host label | | `bast "Production web"` | Labels with spaces work | | `bast hosts list` | List hosts without opening the TUI | | `bast keys list` | List SSH keys without opening the TUI | Press `?` inside the TUI for the full keyboard reference. ## AI agents [#ai-agents] Using Bast with Cursor, Claude Code, or Codex? Install the [agent skill](/docs/reference/agents) or point your agent at [llms.txt](https://bast.sh/llms.txt). --- Full docs index: https://bast.sh/llms.txt --- # Command line (https://bast.sh/docs/features/cli) Everything in the TUI is also available from the shell. That matters for scripts, automation, and tools that need stable output. ## Host commands [#host-commands] ```bash bast hosts list --sort group bast hosts show production_web bast hosts add "Production web" --hostname prod.example.com --user deploy --group Work/Production --tag web bast hosts edit production_web --notes "Primary application server" bast hosts favorite production_web bast hosts hide old_server bast hosts known-host remove production_web bast hosts delete production_web ``` Host edits are patches: fields you omit stay unchanged. Flags like `--clear-group`, `--clear-notes`, and `--clear-identity` remove values on purpose. Run `bast hosts --help` for the full option list per command. ## Key commands [#key-commands] ```bash bast keys list bast keys generate work --algorithm ed25519 bast keys import work --private ~/.ssh/id_ed25519 bast keys comment work --comment "Work laptop" bast keys public work bast keys install work --host production_web bast keys export work --directory ~/Desktop --yes bast keys delete work --yes ``` Run `bast keys --help` for command-specific usage. ## JSON mode [#json-mode] Pass `--json` anywhere in the command for machine-readable output. It disables prompts, so pair it with flags like `--yes` for destructive actions: ```bash bast hosts list --json bast --json hosts show Production_web bast keys generate automation --no-passphrase --json ``` Success looks like `{"ok":true,"data":...}`. Errors go to stderr with a non-zero exit code. Commands that need an interactive SSH session or passphrase entry reject `--json` with `interactive_required`. ## Prompts and confirmations [#prompts-and-confirmations] Commands prompt for missing input and sensitive confirmations when attached to a terminal. Pass `--yes` to explicitly approve deletion, known-host removal, or private-key export in unattended use. Pass `--no-input` to never prompt (fields must be provided via flags). --- Full docs index: https://bast.sh/llms.txt --- # Connections (https://bast.sh/docs/features/connections) Select a host and press Enter to connect. Bast clears the terminal, shows a short connection banner, launches `ssh` with that host's config, and returns you to the picker when the session ends. ## Direct connect from the shell [#direct-connect-from-the-shell] You can skip the TUI entirely: ```bash bast production_web bast "Production web" bast connect production_web ``` Labels with spaces work when quoted. Bast resolves them to the correct SSH alias under the hood. ## Native OpenSSH [#native-openssh] Bast always launches your system's `ssh` binary. There is no proprietary runtime or custom transport. Whatever works in your terminal with plain `ssh` will work through Bast. ## During a session [#during-a-session] Typing `exit` closes Bast entirely when the SSH session ends. If a session gets stuck, press Enter then `~.` to force-close SSH and land back in the picker. That is the standard OpenSSH escape sequence. ## Connection tracking [#connection-tracking] Each successful connection updates last-used time and connection count in Bast metadata. That feeds into smart sort so your frequent servers stay at the top. --- Full docs index: https://bast.sh/llms.txt --- # Host management (https://bast.sh/docs/features/host-management) Press `a` to add a host or `e` to edit the selected one. Bast walks you through a form for every connection and metadata field. ## Connection fields [#connection-fields] | Field | Purpose | | ---------- | --------------------------------------------------------------- | | Label | Display name shown in the list (spaces become SSH-safe aliases) | | Hostname | Server hostname or IP address | | User | Remote username (blank uses your SSH default) | | Port | Port number (blank defaults to 22) | | Identity | Key file, password auth, or ssh-agent defaults | | Proxy jump | Route the connection through a jump host | | SSH flags | Extra OpenSSH options, separated by semicolons or newlines | ## Metadata fields [#metadata-fields] **Groups** use slash paths like `Work/Production`. You can nest up to five levels. Press Space on a group header to collapse or expand it. **Tags** are comma-separated labels included in search. **Environment** is a free-form field (for example `production` or `staging`). **Color** tints the label in the list so you can spot servers at a glance. Use a hex value. **Notes** are short text included in the detail panel and search results. ## Actions [#actions] | Key | Action | | --- | ---------------------------------------------- | | `f` | Favorite the selected host | | `h` | Hide a host you rarely need | | `.` | Toggle whether hidden hosts appear in the list | | `d` | Delete a Bast-managed host | | `K` | Remove a host from your known-hosts file | Favoriting and hiding are presentation-only changes stored in Bast metadata. Deleting removes the host block from Bast's managed config. ## External hosts [#external-hosts] Hosts defined outside Bast's managed config can still be edited for metadata (group, tags, notes, and so on). Bast will not change their connection settings or delete them. Removing a known-host entry (`K`) helps when a server fingerprint changes and SSH refuses to connect. --- Full docs index: https://bast.sh/llms.txt --- # Host picker (https://bast.sh/docs/features/host-picker) The host list shows every entry Bast discovers in your SSH config, including hosts pulled in through `Include` files. Each row shows a label, destination, and any metadata you have set. {"name":"DemoScreenshot","children":"","attributes":{"src":"/hosts.png","alt":"Searching and sorting the host list","width":{"type":"mdxJsxAttributeValueExpression","value":"1600","data":{"estree":{"type":"Program","start":280,"end":284,"body":[{"type":"ExpressionStatement","expression":{"type":"Literal","start":280,"end":284,"loc":{"start":{"line":11,"column":9,"offset":280},"end":{"line":11,"column":13,"offset":284}},"value":1600,"raw":"1600","range":[280,284]},"start":280,"end":284,"loc":{"start":{"line":11,"column":9,"offset":280},"end":{"line":11,"column":13,"offset":284}},"range":[280,284]}],"sourceType":"module","comments":[],"loc":{"start":{"line":11,"column":9,"offset":280},"end":{"line":11,"column":13,"offset":284}},"range":[280,284]}}},"height":{"type":"mdxJsxAttributeValueExpression","value":"500","data":{"estree":{"type":"Program","start":296,"end":299,"body":[{"type":"ExpressionStatement","expression":{"type":"Literal","start":296,"end":299,"loc":{"start":{"line":12,"column":10,"offset":296},"end":{"line":12,"column":13,"offset":299}},"value":500,"raw":"500","range":[296,299]},"start":296,"end":299,"loc":{"start":{"line":12,"column":10,"offset":296},"end":{"line":12,"column":13,"offset":299}},"range":[296,299]}],"sourceType":"module","comments":[],"loc":{"start":{"line":12,"column":10,"offset":296},"end":{"line":12,"column":13,"offset":299}},"range":[296,299]}}}}} ## Search [#search] Press `/` to search across labels, hostnames, groups, tags, environments, and notes. The list filters as you type. ## Sort modes [#sort-modes] Press `s` to cycle through sort modes: * **Smart** (default): favorites and recently used hosts float to the top * **Label**: alphabetical by display name * **Recent**: ordered by last connection time * **Group**: grouped by folder path, then smart order within each group Bast tracks when you last connected and how often, so servers you use every day stay easy to reach. ## Reload [#reload] Press `r` any time to reload your config from disk. That is useful when you edit `~/.ssh/config` in another editor while Bast is open. ## Host details [#host-details] Select a host to see the detail panel on the right: hostname, user, port, identity files, authentication mode, proxy jump, group, tags, environment, notes, and connection history. --- Full docs index: https://bast.sh/llms.txt --- # Key selector (https://bast.sh/docs/features/key-selector) When you add or edit a host, the identity field is a picker, not just a text box. Bast offers detected keys, `ssh-agent` defaults, password-only auth, and a custom path if you need something else. ## Options [#options] * **Detected keys**: every key Bast knows about, with name and fingerprint * **Agent defaults**: let OpenSSH try keys from `ssh-agent` in its usual order * **Password only**: disable public-key auth for hosts that require a password * **Custom path**: point at any identity file on disk This keeps host setup practical. Pick the key you mean instead of remembering file paths, or switch a host to password auth without hand-editing config syntax. The same picker appears when editing an existing host, so you can change identity files without touching `~/.ssh/config` by hand. --- Full docs index: https://bast.sh/llms.txt --- # Key management (https://bast.sh/docs/features/keys) Switch to the keys tab with `2`. Bast lists keys it finds on disk, keys in `ssh-agent`, and which hosts reference each key. {"name":"DemoScreenshot","children":"","attributes":{"src":"/keys.png","alt":"The keys tab with generate, import, and export actions","width":{"type":"mdxJsxAttributeValueExpression","value":"1600","data":{"estree":{"type":"Program","start":236,"end":240,"body":[{"type":"ExpressionStatement","expression":{"type":"Literal","start":236,"end":240,"loc":{"start":{"line":11,"column":9,"offset":236},"end":{"line":11,"column":13,"offset":240}},"value":1600,"raw":"1600","range":[236,240]},"start":236,"end":240,"loc":{"start":{"line":11,"column":9,"offset":236},"end":{"line":11,"column":13,"offset":240}},"range":[236,240]}],"sourceType":"module","comments":[],"loc":{"start":{"line":11,"column":9,"offset":236},"end":{"line":11,"column":13,"offset":240}},"range":[236,240]}}},"height":{"type":"mdxJsxAttributeValueExpression","value":"500","data":{"estree":{"type":"Program","start":252,"end":255,"body":[{"type":"ExpressionStatement","expression":{"type":"Literal","start":252,"end":255,"loc":{"start":{"line":12,"column":10,"offset":252},"end":{"line":12,"column":13,"offset":255}},"value":500,"raw":"500","range":[252,255]},"start":252,"end":255,"loc":{"start":{"line":12,"column":10,"offset":252},"end":{"line":12,"column":13,"offset":255}},"range":[252,255]}],"sourceType":"module","comments":[],"loc":{"start":{"line":12,"column":10,"offset":252},"end":{"line":12,"column":13,"offset":255}},"range":[252,255]}}}}} ## Actions [#actions] | Key | Action | | --- | -------------------------------------------------------- | | `a` | Generate a new ed25519 or RSA keypair | | `i` | Import an existing private key from a file or pasted PEM | | `e` | Edit the comment on a public key | | `u` | Push a public key to a remote `~/.ssh/authorized_keys` | | `x` | Export key files to a folder you choose | | `p` | Change a key passphrase via `ssh-keygen` | | `c` | Copy the public key to your clipboard | | `d` | Delete a Bast-managed keypair | ## Generate [#generate] Create a new key in Bast's managed keys directory (`~/.ssh/bast/keys`). Choose ed25519 or RSA and optionally set a passphrase. ## Import [#import] Bring in an existing private key from a file path or pasted PEM text. Bast can derive the public key if you do not provide one. It verifies keypairs on import so mismatched public and private keys are caught early. Import from stdin without putting key material in shell history: ```bash bast keys import work --private - < id_ed25519 ``` ## Add to server [#add-to-server] Push a public key to a remote server's `authorized_keys`. Bast may prompt for a password if the server requires it. This uses your system `ssh` to copy the key. ## Export [#export] Copy key files to a directory you choose. You confirm by typing `EXPORT` because private keys are sensitive. Pass `--yes` on the CLI to skip the confirmation in scripts. ## Storage [#storage] Generated and imported keys live in `~/.ssh/bast/keys`. Private keys are written at mode `0600`. Never paste real private keys into issues or bug reports. --- Full docs index: https://bast.sh/llms.txt --- # Keyboard shortcuts (https://bast.sh/docs/features/shortcuts) Press `?` inside Bast for the in-app reference. Press `v` for version info, credits, and update hints. ## Navigation [#navigation] | Key | Action | | ---------------------- | ----------------------- | | `↑` / `↓` or `j` / `k` | Move selection | | `1` | Switch to hosts tab | | `2` | Switch to keys tab | | `/` | Search | | `r` | Reload config from disk | | `?` | Toggle help | | `v` | About and version info | | `q` | Quit | ## Hosts [#hosts] | Key | Action | | ------- | ------------------------------- | | `Enter` | Connect to selected host | | `a` | Add a host | | `e` | Edit selected host | | `d` | Delete selected host | | `f` | Toggle favorite | | `h` | Hide or show selected host | | `.` | Toggle hidden hosts in the list | | `Space` | Collapse or expand group | | `s` | Cycle sort mode | | `K` | Remove known-host entry | ## Keys [#keys] | Key | Action | | --- | -------------------------- | | `a` | Generate a key | | `i` | Import a key | | `e` | Edit public key comment | | `d` | Delete selected key | | `u` | Add public key to a server | | `x` | Export key files | | `p` | Change passphrase | | `c` | Copy public key | ## During SSH [#during-ssh] | Action | Result | | ----------------- | -------------------------------------------------------- | | `exit` | Close SSH session and quit Bast | | `Enter` then `~.` | Force-close a stuck SSH session and return to the picker | --- Full docs index: https://bast.sh/llms.txt --- # SSH config (https://bast.sh/docs/features/ssh-config) Bast treats your SSH config as the source of truth. It does not replace OpenSSH or maintain a separate host database. ## First run [#first-run] On first use, Bast prepends a single line to your main SSH config: ``` Include ~/.ssh/bast/config ``` New hosts you create through Bast are written to that managed file. Everything else stays where it already lives. ## Discovery [#discovery] Bast discovers hosts from your main config and every file it includes. Externally managed blocks keep their original source path. Bast-managed blocks are marked so you know which ones it owns. ## Labels and aliases [#labels-and-aliases] Display labels with spaces (like "Production web") map to safe OpenSSH alias names automatically. You can connect with either the label or the alias from the shell: ```bash bast "Production web" bast Production_web ``` ## What Bast stores separately [#what-bast-stores-separately] Presentation metadata (groups, tags, colors, notes, favorites, recency) lives in `bast/state.json` under your OS user config directory. Connection settings live in SSH config files where they belong. Back up `~/.ssh` before testing unreleased builds against a production config. --- Full docs index: https://bast.sh/llms.txt --- # AI agents (https://bast.sh/docs/reference/agents) Bast ships resources for AI coding agents: an installable skill, machine-readable docs, and per-page shortcuts to open ChatGPT, Claude, or Cursor with context. ## Agent skill [#agent-skill] The Bast skill teaches agents how to use the CLI correctly — `--json` automation, patch semantics for host edits, file paths, and safety rules (never paste private keys). It uses the standard `SKILL.md` format and works in **Cursor**, **Claude Code**, and **Codex**. ### Install all agents [#install-all-agents] ```bash curl -fsSL https://bast.sh/install-skill | sh ``` This writes the skill to: | Agent | Path | | ----------- | -------------------------------- | | Cursor | `~/.cursor/skills/bast/SKILL.md` | | Claude Code | `~/.claude/skills/bast/SKILL.md` | | Codex | `~/.codex/skills/bast/SKILL.md` | Restart or start a new agent session after installing. ### Project-local skill [#project-local-skill] Commit the skill with your repo so teammates and CI agents pick it up: ```bash curl -fsSL https://bast.sh/install-skill | BAST_SKILL_SCOPE=project sh ``` That installs to `.cursor/skills/bast/`, `.claude/skills/bast/`, and `.codex/skills/bast/` in the current directory. ### One agent [#one-agent] ```bash # Cursor mkdir -p ~/.cursor/skills/bast curl -fsSL https://bast.sh/bast.skill.md -o ~/.cursor/skills/bast/SKILL.md # Claude Code mkdir -p ~/.claude/skills/bast curl -fsSL https://bast.sh/bast.skill.md -o ~/.claude/skills/bast/SKILL.md # Codex mkdir -p ~/.codex/skills/bast curl -fsSL https://bast.sh/bast.skill.md -o ~/.codex/skills/bast/SKILL.md ``` You can also [download the skill file](https://bast.sh/bast.skill.md) and copy it to the path above. ## llms.txt [#llmstxt] Agents can fetch curated documentation without scraping the site: | URL | Purpose | | ---------------------------------------------- | ----------------------------------- | | [llms.txt](https://bast.sh/llms.txt) | Index of all docs with descriptions | | [llms-full.txt](https://bast.sh/llms-full.txt) | Full docs in one file | Each doc page also exposes processed Markdown (use **Copy Markdown** or **Open** on any docs page) for pasting into a chat or loading into context. ## Ask AI from the docs [#ask-ai-from-the-docs] Every docs page includes **Copy Markdown** and an **Open** menu to start a conversation in ChatGPT, Claude, or Cursor with the current page URL as context. On the [homepage](https://bast.sh), the footer has the same shortcuts plus the skill installer. ## What agents should know [#what-agents-should-know] Brief version of what the skill covers — useful even without installing it: * Bast wraps **OpenSSH**, not a custom SSH protocol. Connection settings live in `~/.ssh/config`; metadata (groups, tags, notes) lives in `~/.config/bast/state.json`. * Use **`--json --no-input`** for scripts. Add **`--yes`** for deletes and exports. * Host and key edits are **patches**: only flags you pass change. Use `--clear-*` flags to remove values. * Prefer `bast hosts` / `bast keys` subcommands over the TUI in non-interactive environments. See [Command line](/docs/features/cli) and [Files and storage](/docs/reference/files) for the full reference. --- Full docs index: https://bast.sh/llms.txt --- # Files and storage (https://bast.sh/docs/reference/files) Bast keeps things in predictable places. Nothing is stored in the cloud. ## Managed SSH config [#managed-ssh-config] ``` ~/.ssh/bast/config ``` Host blocks you create through Bast are written here. Your main `~/.ssh/config` gets one `Include` line pointing at this file. ## Managed keys [#managed-keys] ``` ~/.ssh/bast/keys/ ``` Generated and imported keys live here. Private keys are written at mode `0600`. ## Metadata [#metadata] ``` bast/state.json ``` Lives under your OS user config directory (for example `~/.config/bast/state.json` on Linux). Stores presentation metadata: groups, tags, colors, notes, favorites, last-used times, and connection counts. ## What stays in OpenSSH [#what-stays-in-openssh] Connection settings (hostname, user, port, identity files, proxy jump) live in SSH config files. Bast does not duplicate them in its metadata store. ## Backups [#backups] Back up `~/.ssh` before testing unreleased builds against a production config. Never paste real private keys into issues or bug reports. --- Full docs index: https://bast.sh/llms.txt --- # Installation (https://bast.sh/docs/reference/install) Three ways to get Bast on macOS or Linux. ## Installer script (recommended) [#installer-script-recommended] Downloads the latest build for your architecture, verifies the SHA-256 checksum, and installs to `~/.local/bin` by default. Run the same command again to update. It skips the download when you are already on the latest version. ```bash curl -fsSL https://bast.sh/install | sh ``` Set `BAST_INSTALL_DIR` to install somewhere else. Make sure the install directory is on your `PATH`, then run `bast`. ## Homebrew [#homebrew] ```bash brew tap ellipse-software/tap brew install bast ``` ## From source [#from-source] Requires Go 1.26+: ```bash git clone https://github.com/ellipse-software/bast.git cd bast go build -trimpath -o bast . ``` ## Installer requirements [#installer-requirements] The bast.sh script needs `curl`, `tar`, and `shasum` or `sha256sum`. ## After install [#after-install] Run `bast` to open the host picker. Run `bast update` to update copies installed via the script (see [Updates](/docs/reference/updates)). --- Full docs index: https://bast.sh/llms.txt --- # Telemetry (https://bast.sh/docs/reference/telemetry) Bast sends optional anonymous telemetry to help improve the tool. This includes version, platform, and usage events. No hostnames, keys, or SSH config contents are collected. The bast.sh website and installer use the same policy. ## Opt out [#opt-out] Set this environment variable before running Bast: ```bash export BAST_NO_TELEMETRY=1 ``` Add it to your shell profile to make it permanent. --- Full docs index: https://bast.sh/llms.txt --- # Updates (https://bast.sh/docs/reference/updates) Tagged builds check GitHub for a newer stable release in the background when you launch Bast. If one exists, a reminder appears in the footer without slowing startup. Network failures are ignored quietly. ## Update suggestions [#update-suggestions] The reminder depends on how you installed Bast: | Install method | Suggested action | | -------------- | -------------------- | | bast.sh script | `bast update` | | Homebrew | `brew upgrade bast` | | Source build | Link back to bast.sh | Press `v` in the TUI to see version info and the update suggestion. ## bast update [#bast-update] ```bash bast update ``` This only runs when the bast.sh installer receipt is present beside the executable. It will not overwrite Homebrew-managed or source-built copies. The script downloads the latest release, verifies the checksum, and replaces the binary in place. ## Check manually [#check-manually] Visit [github.com/ellipse-software/bast/releases](https://github.com/ellipse-software/bast/releases) for release notes and download links. --- Full docs index: https://bast.sh/llms.txt