Skip to content

Beta: these docs are still being updated. The next full update is on 19 November at 8 PM UTC. Docs in beta. Full update 19 Nov, 8 PM UTC.

Hoody.com

hoody is the command-line client for your Hoody account and your computers. It ships inside the hoody-sdk npm package and speaks the same HTTP API as the SDK and curl. This page covers the tool itself; every command group documents its own flags in hoody <command> --help.

Terminal window
npm install -g hoody-sdk@1.0.1
hoody login
hoody use # where commands act: realm, computer, project, account
hoody computers list
MethodCommand
npm, globalnpm install -g hoody-sdk@1.0.1
No installnpx hoody-sdk@1.0.1 <command> (also bunx, pnpm dlx)
Standalone binary, Linux and macOScurl -fsSL https://install.hoody.com | sh
Standalone binary, Windowsiwr https://install.hoody.com/install.ps1 -UseB | iex
Nothing localssh hoody.com opens the CLI in a memory-only session; see Use the CLI over SSH

The package needs Node.js 20.19 or later (22 or later recommended: Node.js 20 is end-of-life), or Bun. The standalone binary carries its own runtime, so it needs no Node.js. It installs one command, hoody; check it with hoody --version.

Proxy settings work with Node.js 22.19 or later, Bun, or the standalone binary; see requirements.

ssh hoody.com opens the same Hoody CLI from any SSH client, with nothing installed on the device: a borrowed laptop, a server you are logged into, a phone with an SSH app.

Terminal window
# Sign in inside the CLI
ssh hoody.com
# Skip the sign-in: a scoped auth token as the SSH username
ssh "$HOODY_TOKEN@hoody.com"

Plain ssh hoody.com shows a short notice; press Enter and the CLI offers to create an account or sign in. Once you are signed in, it opens the Hub; an account with no computer yet first gets a Get my free computer button, and nothing is created until you press it. Quitting the Hub, or the menu, gives you a shell prompt with the full hoody command. With a token you land at that prompt with the token already set, and type hoody … commands yourself, hoody hub included.

The session is memory-only: nothing persists between connections, so sign in each time or pass a token. It needs an interactive terminal (add -tt when your input is not one); one-shot commands such as ssh hoody.com computers list and piped input are not supported. For scripts and CI, install the CLI and set HOODY_TOKEN.

This reaches the CLI, not a shell in your computers. A computer shell comes from its SSH host, {projectId}-{computerId}-ssh.{server}.computers.hoody.com, or the shared ssh.{server}.computers.hoody.com; both route by your public key. See SSH access.

Terminal window
# Interactive: pick password, browser, or token, then answer the prompts
hoody login
# Sign in through your browser (GitHub, Google, or an existing session)
hoody login --web
# Prompt for the password without echoing it
hoody login --email you@example.com -p
# Sign in with an existing auth token, optionally scoped to one realm
hoody login --token "$HOODY_TOKEN" --realm "$REALM_ID"
# No account yet
hoody signup
# Finish setting up a new account: resume email verification and claim your free server
hoody setup

hoody login saves the session to ~/.hoody/config.json (mode 0600). For headless use, skip the login: set HOODY_TOKEN and, if you target a non-default API, HOODY_API_URL. The token comes from the first of these that is set: --token (-t), HOODY_TOKEN (or HOODY_API_TOKEN), the saved session.

For scripts, --print-token, --password-stdin and hoody auth accesstoken get (the session’s token) are in the sign-in options. hoody logout signs this device out; see sign-out options.

Kit commands (files, terminal, exec, db, agent, and the rest) and computer-specific operations under snapshots, firewall, network and storage need a target computer. hoody storage shares list and hoody storage incoming list do not. Platform commands act in a realm when one is set. hoody use shows the current realm and computer and saves your choice in the active profile:

Terminal window
# Show the realm, computer, project and account commands act in, and where each value comes from
hoody use
# Save a realm (its id or its name) and a computer in it
hoody use "$REALM_ID" "$COMPUTER_ID"
# Save only the computer
hoody use -c "$COMPUTER_ID"
# Show a realm in a colour on this device: red, orange, green, teal, blue, purple or pink (none clears it)
hoody use "$REALM_ID" --color teal

The target computer is the first of: -c <id> anywhere on the command line, HOODY_COMPUTER (or HOODY_COMPUTER_ID), the saved default for the active profile. Each takes the 24-character hex id from hoody computers list. Kit commands also accept a computer name through -c or HOODY_COMPUTER; the name must match exactly one of your computers. hoody computers get, hoody use, hoody config set computer, hoody agent prompt and hoody agent login accept a name too. hoody agent <computer> and hoody hub -c <computer> check a name before the Hub opens, but the Hub does not open on that computer.

Saving a realm clears a saved computer that is not in that realm. hoody login can save your account’s default computer for you, so run hoody use if commands without -c reach a computer you did not expect; it also says when an environment variable overrides what you saved.

Other defaults commands, and names in place of an id: where commands act.

hoody hub opens the Hub full screen in your terminal. It is the same Hub as the one at hub.hoody.com, for your whole account: computers, files, Bots, AI, notes, scripts, vault and realms. It runs on Linux (x86-64 and arm64), in the standalone hoody binary and in the npm package with Node 26 or later.

Terminal window
# Open your account
hoody hub
# Start in the realm named work (a realm id, a name, or global)
hoody hub --realm work
# Look around with a sample account: no sign-in, nothing is sent
hoody hub --demo

It uses the CLI’s own sign-in: the session saved by hoody login, or an auth token in --token or HOODY_TOKEN. Before the Hub appears, one line names the realm it starts in and why, such as realm work, from --realm. Without --realm, it starts in the realm your settings or your last visit point to, or else the realm with the most computers (full order). It opens on the page where you left off, or on Home. Alt+R switches the realm.

Press q to leave when you are not typing in a field; the Hub asks first if work is running or something is unsaved. Ctrl+C first shows a warning or quit prompt. Press it again within two seconds, or while the quit prompt is open, to leave without further confirmation. ? lists every key and Ctrl+K opens the command palette. Leaving the Hub keeps you signed in and gives you back your shell prompt, on your own machine and over ssh hoody.com. Billing is done in the web Hub.

hoody hub needs an interactive terminal. Installed from npm under an older Node or Bun, it says it needs Node 26 or later and prints the command that installs the standalone binary; on other platforms, it says the terminal Hub is not available there and gives the web Hub’s address. The hoody command inside every computer has it too, and so does the hosted CLI that ssh hoody.com opens.

Other commands open the same Hub. hoody agent is hoody hub. A computer given as its argument or with -c is checked first: an id passes, and a name that matches no computer or several is refused. The Hub does not open on that computer. hoody welcome opens it once you are signed in to an account with a computer, and the last step of hoody login, hoody signup and hoody setup offers it: press Enter to open it, or n for later. The --profile, --config, --base-url, --realm, --proxy and --token you give these commands carry over to the Hub. A --no-save sign-in cannot open it, because the Hub uses the saved sign-in.

A profile is a named set of settings inside the same config file: its own token, base URL, default computer, realm, and output format. Use one per account or per environment. Ordinary settings a profile does not set are inherited from the top level of the file. Refresh tokens and expiry fields stay with the level that holds the access token; they are not inherited on their own.

Terminal window
# Sign in under a profile; the session is saved to that profile only
hoody --profile staging login
# Write a setting into a profile
hoody config set computer "$STAGING_COMPUTER_ID" --for-profile staging
# Run one command, or a whole shell, under a profile
hoody --profile staging computers list
export HOODY_PROFILE=staging
# Make a profile the default for every command
hoody config set defaultProfile staging
# Sign out of one profile
hoody --profile staging logout

On a terminal, output is laid out for people. In a pipe, in CI, in agent mode (HOODY_AGENT_MODE=1), with -o json and in the other cases, it stays as earlier releases printed it, byte for byte, exit codes included, so scripts that parse hoody output keep working.

Set the output format per command with -o (--output), such as -o json for jq, or save a default with hoody config set output json.

--non-interactive does not suppress every confirmation: a destructive command still asks on standard input. In a script, pass -y only when you intend to approve the action. Without it, a command that confirms waits for an answer on standard input and exits 1 when standard input closes or no answer comes within 30 seconds. A few, such as hoody notes notebooks delete, never ask in a script.

--http prints the request a command would send: the method, the URL, the headers and the body, with secret values redacted and some bodies withheld. --http-curl prints the same request as a curl line; put back any redacted value or withheld body before you run it. Neither sends anything that writes, and no confirmation is asked. The token is never printed.

Terminal window
# The request behind a list; a list that spans pages says how the next pages are read
hoody computers list --http
# A delete as a curl line, without deleting anything
hoody computers delete "$COMPUTER_ID" --http-curl

A name you type in place of an id is still looked up first, with a GET that is sent.

hoody completion <shell> prints a completion script for bash, zsh, or fish.

Terminal window
# bash
mkdir -p ~/.local/share/bash-completion/completions
hoody completion bash > ~/.local/share/bash-completion/completions/hoody
# zsh (add ~/.zsh/completions to fpath before initializing zsh completion)
mkdir -p ~/.zsh/completions
hoody completion zsh > ~/.zsh/completions/_hoody
# fish
mkdir -p ~/.config/fish/completions
hoody completion fish > ~/.config/fish/completions/hoody.fish

For zsh, add ~/.zsh/completions to fpath before initializing zsh completion.

Open a new shell to load it. For bash, run source ~/.local/share/bash-completion/completions/hoody to load it now; unless the bash-completion package already loads that directory, add the same line to ~/.bashrc. Regenerate the file after an update so it picks up new commands. After --realm and hoody use, completion offers the names of your realms.

Terminal window
hoody update

hoody update compares your version with the latest release on npm, falls back to GitHub when npm cannot be reached, and, when a newer release exists, prints the command for your install: npm i -g hoody-sdk@latest for npm, the installer for the binary. It does not replace the installed CLI. HOODY_NO_UPDATE_CHECK=1 turns the check off.

Terminal window
# 1. Optional: list and delete auth tokens you created and no longer need
# (do this first: these commands need the session that step 2 ends)
hoody auth tokens list
hoody auth tokens delete "$TOKEN_ID"
# 2. Clear the saved credentials; after a password or browser sign-in, also end every session of the account
hoody logout --all
# 3. Remove the CLI (npm install; use the matching command for pnpm, yarn, or bun)
npm uninstall -g hoody-sdk
# 4. Remove its settings, sessions, and caches
rm -rf ~/.hoody; case "${XDG_CACHE_HOME:-}" in /*) rm -rf -- "$XDG_CACHE_HOME/hoody/hub" ;; *) rm -rf -- "$HOME/.cache/hoody/hub" ;; esac
# 5. Remove the completion file, if you installed one
rm -f ~/.local/share/bash-completion/completions/hoody ~/.zsh/completions/_hoody ~/.config/fish/completions/hoody.fish

Plain hoody logout clears this device’s credentials and attempts to revoke agent sign-in keys created by the terminal Hub. Unless you use --quiet, it warns if those keys could not be revoked. The session token stays valid on the server until it expires. After a password or browser sign-in, --all ends every session of the account, so other devices signed in to it have to sign in again. After a token sign-in it ends none, so delete that token in step 1. Offline, --all still signs this device out but cannot end the other sessions: once you are back online, sign in again with your password or the browser and run hoody logout --all. Run hoody --profile <name> logout --all for each profile that holds a different account. Delete other auth tokens (hdy_...) separately in step 1.

In the Hub, under Account > Keys and tokens > API keys, open a key’s actions and choose Delete…, then Delete key. Under Account > Account > Sign-in sessions, choose End all other sessions to sign out the other devices. Sign out of the current Hub session separately.

For the standalone binary, replace step 3 by deleting the file that command -v hoody prints. If you used --config to keep settings elsewhere, delete that file too.

  • Live output: --watch redraws a list, log stream commands follow new entries, and --until-done waits for a long operation. See live output.
  • Structured input: map, object-list and JSON-document flags accept inline input, @file.json, or @- for standard input. Scalar-list flags take repeated inline values; many also accept comma-separated values. See structured input.
  • Configuration file: hoody config prints, checks, sets, clears and resets your settings. See configuration file.
  • Local lock: hoody local lock encrypts saved tokens and default ids behind a password you choose. See local lock.
  • Protected computers: the --kit-* flags carry the credentials that a computer’s proxy permissions ask for. See global flags.
  • Screen sharing: --mask-urls shortens ids on screen before you share it. See masked ids.
  • Network proxy: --proxy <url> or HTTPS_PROXY sends requests through an HTTP or HTTPS proxy. See requirements.
  • Every flag and variable: global flags such as -q, -v, --no-color and --base-url, the environment variables that set some of them, and which wins. See global flags and environment variables.
  • Hoody Agent: hoody agent prompt sends a computer’s agent a task and streams the reply, and the other hoody agent subcommands drive it from a script. Bare hoody agent opens the Hub. See Agent.
  • Help and answers: hoody alone lists every command; hoody chat "<question>" answers questions about Hoody with no API key. See built-in help.

Every flag, variable, format and fix: the Hoody CLI reference.

  • Quick Start: sign in and run commands on your first computer.
  • Authentication: session logins compared with long-lived auth tokens.
  • Realms: scope the CLI to one realm with --realm.
  • Proxy permissions: protect a computer and pass credentials with the --kit-* flags.