# Hoody CLI reference **Page:** foundation/cli/reference [Download Raw Markdown](./foundation/cli/reference.md) --- # Hoody CLI reference Lookup tables for the [Hoody CLI](/foundation/cli/). Every command group documents its own flags in `hoody --help`. ## Requirements | Item | Rule | |---|---| | Runtime | 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 and needs no Node.js | | Proxy settings | `--proxy`, `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY`, or the config `proxy` key need Node.js 22.19 or later, Bun, or the standalone binary | | Proxy on older Node.js | With a proxy configured, requests stop with `PROXY_UNSUPPORTED` and are not sent, except to hosts in `NO_PROXY` | | Engine warning | On Node.js 20.19 to 22.18, npm prints an engine warning for `undici`, which is not loaded there (Node.js's built-in `fetch` is used instead) | | `engine-strict=true` | Installs with it need Node.js 22.19 or later | ## Sign-in options | Command or flag | Effect | |---|---| | `hoody login` | Interactive: pick password, browser, or token, then answer the prompts. Saves the session to `~/.hoody/config.json` (mode `0600`) | | `--web` | Sign in through your browser (GitHub, Google, or an existing session) | | `--email
-p` | Prompt for the password without echoing it | | `--token `, `--realm ` | Sign in with an existing auth token, optionally scoped to one realm (a realm id, or `global`) | | `--print-token` | `hoody login` and `hoody signup`: print only the access token to stdout | | `--no-save` | `hoody login` and `hoody signup`: authenticate without writing anything to the config file | | `--password-stdin` | `hoody login` and `hoody signup`: read the account password from standard input, keeping it out of the command line and shell history | | `--non-interactive` (global) | Fail instead of showing interactive prompts. It does not suppress every confirmation: a destructive command may still read its answer from standard input | | `hoody signup` | Create an account | | `hoody auth accesstoken get` | Print the access token of the current session, refreshing it if it has expired; it never signs in. `export HOODY_TOKEN=$(hoody auth accesstoken get)` hands it to `curl` or a script | | `hoody setup` | Finish setting up a new account: resume email verification and claim your free server. Needs a terminal: in agent mode and in CI it exits 2 | ```bash # Sign in from a script without the password on the command line printf '%s' "$HOODY_PASSWORD" | hoody login --username "$HOODY_USERNAME" --password-stdin ``` Token order: `--token` (`-t`), then `HOODY_TOKEN` (or `HOODY_API_TOKEN`), then the saved session. For headless use, set `HOODY_TOKEN` and, if you target a non-default API, `HOODY_API_URL`. ## Where commands act Target computer, first match wins: 1. `--computer ` or `-c `, anywhere on the command line 2. `HOODY_COMPUTER` (or `HOODY_COMPUTER_ID`) 3. The saved default for the active profile ```bash # Save a default; commands without -c now use it hoody config set computer "$COMPUTER_ID" # Same setting, through the curated defaults command hoody local defaults set computer "$COMPUTER_ID" # Show computer, realm, output, noColor and quiet, each with where its value comes from hoody local defaults get # Forget the default hoody config clear computer ``` | Rule | Detail | |---|---| | Computer ids | The saved default takes the 24-character hex id from `hoody computers list`. `hoody config set computer`, `hoody use` and the `hoody computers` commands listed [below](#names-in-place-of-ids) look up a computer name and use the matching id. `hoody agent` and `hoody hub` check a name they are given but do not use it: the Hub does not open on that computer. Those `hoody computers` commands also look up a name given with `-c` or in `HOODY_COMPUTER` when you omit their id argument. Other Kit commands also resolve a computer name given with `-c` or `HOODY_COMPUTER`; the name must match exactly one computer | | Login default | `hoody login` can save your account's default computer for you; run `hoody use` or `hoody local defaults get` if commands without `-c` reach a computer you did not expect | | Realm and computer | Saving a realm with `hoody use` clears a saved computer that is not in that realm. When an environment variable still overrides what you saved, `hoody use` says so | | Realm names | `--realm` accepts a realm's name as well as its id when you type it. For other commands a name in `HOODY_REALM` or in a saved realm is not looked up; `hoody hub` looks up a name from `--realm`, `HOODY_REALM`, `HOODY_REALM_ID` or the profile. `hoody login --realm` takes only a realm id, or `global` for all realms | ### Names in place of ids The commands below take a name in place of the id argument: `hoody computers get ember` looks the name up before it sends the request. A value shaped like an id is sent as given, and a name that matches nothing, or more than one row, exits 1. | Group | Commands that look up a name | |---|---| | `hoody computers` | `get`, `update`, `delete`, `stats`, `start`, `stop`, `restart`, `pause`, `resume`, `copy`, `sync` | | `hoody daemon programs` | `get`, `update`, `delete`, `enable`, `disable`, `start`, `stop`, `status`, `logs get`, `logs stream`, `sandbox get` | | `hoody daemon ephemeralprograms` | `status`, `stop`, `logs get` | | `hoody curl jobs`, `hoody curl schedules` | jobs: `get`, `delete`, `cancel`, `result get`; schedules: `get`, `update`, `delete` | | `hoody pools` | `get`, `update`, `delete`, `members invite`, `members remove`, `members role set` (the pool argument) | | `hoody wallet payments methods` | `get`, `update`, `delete`, `default set` | | `hoody servers` | `rent` (a server from `hoody servers marketplace list`) | `hoody agent ` and `hoody hub -c ` check a computer name before the Hub opens, and `hoody agent prompt` and `hoody agent login` look up a name given with `-c` or in `HOODY_COMPUTER`. Kit commands also resolve a computer name supplied with `-c` or `HOODY_COMPUTER`. Other resource arguments require ids unless listed above: `hoody projects get` takes the project id. Some command help, including `hoody computers get --help`, says when an argument takes a name. ## Hub and agent commands The [Hub in your terminal](/foundation/cli/#open-the-hub-in-your-terminal) comes with the standalone `hoody` binary or the npm package with Node 26 or later, on Linux (x86-64 and arm64), and with the `hoody` command inside every computer. | Command | Effect | |---|---| | `hoody hub` | Open the Hub full screen in this terminal, with the CLI's saved session or an auth token from `--token` or `HOODY_TOKEN`. Leaving it keeps you signed in | | `hoody hub --realm ` | Start in a realm: its id, its name, or `global`. `--realm` is the global flag; `hoody agent` and `hoody welcome` pass it on to the Hub, with `--profile`, `--config`, `--base-url`, `--proxy` and `--token` | | `hoody hub --demo` | Open a sample account held in memory. It needs no sign-in and sends nothing; `--realm` does not apply to it | | `hoody agent [computer]` | Open the Hub, the same as `hoody hub`. A computer given as the argument or with `-c` is checked first: an id passes, a name must match exactly one computer, else it is refused (exit 1). A computer as the argument and a different one with `-c` is refused (exit 2). The Hub does not open on that computer. Every option you type, `--token` and `--proxy` included, applies to the Hub | | `hoody welcome` | Signed in to an account with a computer: open the Hub. With no computer: offer **Get my free computer** (nothing is created until you press it), **See all commands** and **Quit** | | Last step of `hoody login`, `hoody signup`, `hoody setup` | `Start now?` opens the Hub on Enter; `n` leaves it for later. Without a terminal this step is skipped: `login` just signs in, `signup` asks you to verify by email and then run `hoody login`, and `setup` exits 2. A `--no-save` sign-in cannot open the Hub | | `hoody agent prompt`, `hoody agent login`, `hoody agent sessions` and the other `hoody agent` subcommands | Work with a computer's agent from a terminal or a script; `hoody agent --help` lists them | The realm `hoody hub` starts in, first match wins. The line printed before the Hub appears names the realm and which rule chose it. 1. `--realm` 2. `HOODY_REALM`, then `HOODY_REALM_ID` 3. The realm saved in the active profile (`hoody use`) 4. The realm the last `hoody hub` ended in, while the account still has it 5. The realm with the most computers, provided at least one computer exists 6. All realms An auth token limited to realms opens only one of them, and asking for another realm exits 2. | `hoody hub` stops before drawing when | It prints | Exit | |---|---|---| | The npm CLI is running on Linux x86-64 or arm64 under Bun, Node.js older than 26, or a Node.js that does not know `--experimental-ffi` | That the terminal Hub needs Node.js 26 or later or the standalone binary, and, when the platform is known, the command that installs the binary and the web Hub's address | 2 | | This `hoody` has no terminal Hub (other platforms, or a build without it) | That the terminal Hub is not available on this platform, and the web Hub's address when known | 2 | | The input or output is not an interactive terminal | That the terminal Hub needs an interactive terminal | 2 | | No one is signed in, or the sign-in expired | Run `hoody login`, then `hoody hub` again | 2 | | A realm name matches no realm, or more than one | The realm names, or the ids of the matches to pass instead | 1 | | `--realm` is given with `--demo` | That the sample account has its own realms | 2 | | The API does not answer | The API address and `did not answer; try again` | 1 | ## Profiles A profile is a named set of settings inside the same config file: its own token, base URL, default computer, realm, and output format. The active profile is the first of these that is set: 1. `--profile ` 2. `HOODY_PROFILE` 3. The `defaultProfile` key in the config file 4. `default`, which uses `profiles.default` over the top-level keys when that profile exists, and the top-level keys otherwise A profile's keys override the top-level keys. Ordinary settings a profile does not set are inherited from the top level. Refresh tokens and expiry fields stay with the level that holds the access token; they are not inherited on their own. | Command | Writes to | |---|---| | `config set`, `config get`, `config clear` | The top level of the file unless the command names a profile: `HOODY_PROFILE` and `defaultProfile` do not steer them | | `hoody --profile staging config set ...` | The `staging` profile, which must already exist | | `config set --for-profile ` | That profile; creates the profile when it is missing | | `local defaults set` | Takes `--for-profile`, and otherwise follows the active profile; creates the profile when it is missing | | `hoody --profile staging login` | The session is saved to that profile only | ## Output formats On a terminal, a command prints one line on stderr that names where it acted (the realm, and the computer for kit commands) and what it printed, such as `6 computers`. Its data follows on stdout in a fixed layout: a list as a table fitted to the terminal width, one item as label and value rows, and a write that returns nothing of its own as one `✓` line naming what it changed. A command that reports progress instead of data, such as `hoody share`, writes everything to stderr. Errors go to stderr, as before. `--no-color` and `NO_COLOR` remove the colour, not the layout. The output of earlier releases, byte for byte with exit codes, is kept in a pipe or a redirect, when `CI` is `1`, `true`, `yes` or `on` (any case) or `TERM=dumb`, in agent mode (`HOODY_AGENT_MODE=1`), and with `-o json`, `-o yaml`, `-o ndjson` or `-o raw`. To get that layout on a terminal, type `-o table`, `-o wide` or `-o json`, or set `HOODY_AGENT_MODE=1`. A saved `table` or `wide` does not replace the terminal layout; only one typed on the command line does. | Format | Output | |---|---| | `table` | Table; the default in a pipe. Typed on a terminal, it replaces the terminal layout | | `wide` | The table with extra columns | | `json` | JSON, for `jq` and scripts | | `yaml` | YAML | | `raw` | Text response data without JSON quoting, for piping: a command-specific text field takes precedence (for example, `code` for `hoody exec templates generate`), followed by a string `content`, `data`, `body` or `text` field; an object without a matching string field falls back to formatted JSON | | `ndjson` | One JSON object per line; the default for streams | | `pretty` | Formatted stream output | ## Request previews | Case | Behaviour | |---|---| | `--http` | Prints the method, the URL, the headers and the body. Secret values read `[redacted]`, headers you configured for every request are left out, and a binary or sensitive body shows only its size. With `-o json`, prints `{ "method", "url", "headers", "body" }` | | `--http-curl` | Prints the same request as a `curl` line. Put back any redacted value or withheld body before you run it | | Writes and prompts | Neither flag sends anything that writes, and no confirmation is asked | | Token | Never printed: an account token reads `Authorization: Bearer $HOODY_TOKEN`, or `$HOODY_API_TOKEN` when that variable supplied the token. Kit credentials read as their own placeholders, such as `$HOODY_KIT_TOKEN` or `$HOODY_KIT_BASIC`; any other authorization value reads `[redacted]` | | A list that spans pages | The preview says how the next pages are read | | A name in place of an id | Still looked up first, with a `GET` that is sent | | A command that cannot show its requests | Such as `hoody shell`: refuses both flags and exits 2 before it does anything | ## Live output | Flag | Works on | Effect | |---|---|---| | `--watch [interval]` | List commands | Redraws the list in place every interval (default `2s`; for example `500ms`, `1m`) until Ctrl+C. Needs an interactive terminal | | `stream` commands | `hoody daemon programs logs stream`, `hoody exec logs stream`, `hoody proxy logs stream`, `hoody agent logs stream` | Keep printing new entries as they arrive. A read such as `hoody daemon programs logs get` prints once and has no `-f` or `--follow` | | `--until-done` | Commands that start an operation which finishes later, such as `hoody computers copy` | Waits for the operation to finish; `--timeout ` stops waiting (default `10m`). Exits 0 when it is done, 1 when it failed, 124 on a timeout, 4 when not authorized and 130 when interrupted | ## Structured input A field with fixed properties gets one typed flag per property. Fields that hold a map, a list of objects or a free-form object take the shapes below, and each flag's `--help` names its shape. | Placeholder in `--help` | Takes | Example | |---|---|---| | ``, a map | One `KEY=VALUE` per occurrence, or the whole object as one JSON document | `--form a=1 --form b=two`, or `--form '{"a":"1","b":"two"}'` | | ``, a list of objects | One occurrence per item, its fields as comma-separated `KEY=VALUE` pairs, or the whole array as one JSON document | `--items key=greeting,value=hello,ttl=60 --items key=enabled,value=true` | | `` | One JSON document | `--patch '{"theme":null}'` | | `` | A JSON value, or plain text where the field takes a string | `--json '{"user":"john"}'` | A JSON document comes from one of three places, with the same types and nesting from each: inline, from a file with `@file.json`, or from standard input with `@-`. ```bash hoody auth tokens update "$TOKEN_ID" --public-storage '{"answer":42,"nested":{"a":[1,2]}}' hoody auth tokens update "$TOKEN_ID" --public-storage @storage.json cat storage.json | hoody auth tokens update "$TOKEN_ID" --public-storage @- ``` | Rule | Detail | |---|---| | One form per flag | A flag takes one document or `KEY=VALUE` entries, never both and never two documents. `hoody kv batch set --items` takes either one `--items` per item or the whole array as one document | | `@` names a source | A value that starts with `@` always names a source, so a `KEY=VALUE` key cannot start with `@`, `{` or `[`. A key such as an npm scope goes in the document form: `--dependencies '{"@types/node":"^20"}'`, not `--dependencies @types/node=^20`, which reads a file | | Standard input | Read only for an explicit `@-`, and only one flag of a command can read it | | Invalid documents | A document that is not valid JSON, or whose outer type is wrong (an array where the flag takes an object), is refused before the command's own request is sent. Lookups that run first, such as resolving a realm name given with `--realm`, may already have been sent | | Inline text on a value flag | On a `` flag, inline text is read as JSON first: `'"x"'` is the string `x`, `1735689600` a number, `true` a boolean. A value that parses must be of a type the field takes, or it is refused: `true` on a field that takes only a string is not sent as `"true"`. Only text that does not parse as JSON, such as `8000-8100` or a plain token, is sent as a string, and only where the field takes one | | Object and array flags | A document flag that takes an object or an array refuses any other type, from every source. A field that also allows null, such as `--public-storage` ("a JSON object or null"), takes `null` as well, which clears it | | Booleans that allow null | A boolean flag whose field also takes null has a third switch: `--` sends true, `--no-` false and `--unset-` null, such as `--unset-enable-proxy` on `hoody computers proxy settings update`. `--unset-` with either of the others is refused before anything is sent | ## Configuration file Settings live in `~/.hoody/config.json`. `--config ` points one command at a different file. | Command | Effect | |---|---| | `hoody config path get` | Print the path of the file in use | | `hoody config get` | Print the whole file, secrets masked | | `hoody config get --resolved` | Print the effective settings: file, active profile, and environment merged | | `hoody config get ` | Print one key (dotted paths work) | | `hoody config set ` | Set a key | | `hoody config clear ` | Remove a key | | `hoody config validate` | Check the file and report problems | | `hoody config reset --yes` | Overwrite the file with defaults. Without `--yes`, an existing file is left alone, and the command exits 1 and asks for `--yes`. With no file, it writes the defaults | Commonly set keys: `computer`, `realm`, `output`, `baseUrl`, `proxy`, `noColor`, `quiet`, `defaultProfile`. Keys are camelCase in the file; the matching flags are kebab-case (`baseUrl` and `--base-url`). ## Local lock `hoody local lock` encrypts the sensitive fields of the config file (tokens and default ids) behind a password you choose. It does not keep a saved account password: turning the lock on deletes it, and the lock stores the token only. | Command or flag | Effect | |---|---| | `hoody local lock enable` | Turn the lock on and move the sensitive fields into `~/.hoody/lock.json` | | `hoody local lock status` | Show the lock's state, how many profiles it protects, and file permissions | | `hoody local lock password set` | Change the lock password; every protected field is encrypted again under the new one | | `hoody local lock disable` | Turn the lock off. Without `--write-plaintext` it forgets all tokens; with it, it writes them back in plain text | | `hoody local lock doctor` | Run health checks on `~/.hoody/` and the lock files | | `--local-password-file `, `--local-password-fd `, `--local-password-stdin`, `--local-password ` | Give one command the lock password without a prompt. Avoid the inline `--local-password` in long-lived shells | Run `hoody local lock --help` for its other subcommands. ## Global flags | Flag | Effect | |---|---| | `-c, --computer ` | Target computer | | `-o, --output ` | Output format | | `--profile ` | Use a named profile | | `--realm ` | Scope platform requests to a [realm](/foundation/hoody-api/realms/) | | `-t, --token ` | API token; overrides a saved login | | `-u, --username`, `-p, --password` | Credentials for automatic login; put them before the command name | | `-y, --yes` | Skip confirmation prompts on destructive actions | | `-q, --quiet` | Hide status and progress messages; response data still prints to stdout | | `-v, --verbose` | Show the HTTP requests | | `--non-interactive` | Fail instead of showing interactive prompts. It does not suppress every confirmation: a destructive command may still read its answer from standard input | | `--base-url ` | API base URL (default `https://api.hoody.com`) | | `--config ` | Use another config file | | `--proxy ` | Send requests through an HTTP or HTTPS proxy | | `--no-color` | Disable colored output | | `--http`, `--http-curl` | Print the request instead of sending it; see [request previews](#request-previews) | | `--mask-urls` | Shorten ids in the terminal layout, for sharing your screen; see [masked ids](#masked-ids) | | `--kit-auth`, `--kit-user`, `--kit-token`, `--kit-token-header` | Credentials for computers protected by [proxy permissions](/foundation/proxy/permissions/) | Run `hoody --help` for the rest. ### Confirmation prompts Destructive commands ask before they act. On a terminal the question goes to stderr and names the target. In a script, pass `-y`: 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. Some destructive commands, such as `hoody notes notebooks delete` and `hoody browser cookies clear`, ask only on a terminal and run without asking in a script. ## Masked ids `--mask-urls`, or `HOODY_MASK_URLS=1`, shortens ids in what the terminal layout draws: the line naming where a command acted, lists, items, `✓` lines, streams and `✕` errors. | Rule | Detail | |---|---| | What is masked | A run of exactly 24 characters from `0-9` and `a-f` that has no other `0-9` or `a-f` character on either side (an uppercase `A-F` next to the run does not stop the match) | | How it shows | Its first and last 4 characters, such as `65f2…9a1c` (`...` where the terminal cannot show `…`) | | Not masked | Output with `-o` typed on the command line (`table`, `wide`, `json`, `yaml` and the rest); a pipe, CI or agent mode; an error in the earlier `Error [404] …` form; a command that prints one bare value or a file's contents | ## Environment variables A flag beats its environment variable, and the environment variable beats the config file. | Variable | Equivalent | |---|---| | `HOODY_TOKEN` (or `HOODY_API_TOKEN`) | `--token` | | `HOODY_API_URL` (or `HOODY_BASE_URL`, which wins when both are set) | `--base-url` | | `HOODY_COMPUTER` (or `HOODY_COMPUTER_ID`) | `--computer` | | `HOODY_REALM` (or `HOODY_REALM_ID`) | `--realm` | | `HOODY_PROFILE` | `--profile` | | `HOODY_USERNAME`, `HOODY_PASSWORD` | `-u`, `-p` for automatic login; a non-interactive password `hoody login` (no terminal, `--non-interactive` or machine output; not `--web`) also reads them when the flags are absent | | `HOODY_KIT_AUTH`, `HOODY_KIT_USER`, `HOODY_KIT_TOKEN`, `HOODY_KIT_TOKEN_HEADER` | The `--kit-*` flags | | `HOODY_KIT_PASSWORD` | The kit password for `--kit-auth password` | | `HOODY_AGENT_MODE=1` | The output layout of earlier releases on a terminal too; see [output formats](#output-formats) | | `HOODY_MASK_URLS=1` | `--mask-urls` | | `HOODY_NO_UPDATE_CHECK=1` | Turn off the update check | | `NO_COLOR` | `--no-color` | | `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY` | `--proxy` | ## Built-in help | Command | Shows | |---|---| | `hoody` | Where commands act, and every command on one page | | `hoody --help` | Every command group and the global flags | | `hoody --help` | Flags and examples for one command | | `hoody help ` | The same, spelled out | | `hoody chat ""` | An answer about Hoody, from Hoody, with no API key | ## Troubleshooting | Symptom | Cause | What to do | |---|---|---| | A kit command says no computer is selected | No `-c`, no `HOODY_COMPUTER`, no saved default | Pass `-c `, export `HOODY_COMPUTER`, or save a default with `hoody config set computer ` | | A command reaches the wrong computer or account | A profile, environment variable or saved default you did not expect | Run `hoody local defaults get` and `hoody config get --resolved`. They show the active profile and where each value comes from, including environment variables | | `config set` rejects a computer value | The name matched no computer, or more than one | Pass the 24-character hex id from `hoody computers list` | | `config set` with `--profile ` exits 2 and says the profile was not found | `--profile` writes only into a profile that already exists | Create it by writing with `--for-profile `, which creates a missing profile | | No authentication credentials found | No token and no saved session | Sign in with `hoody login`, or set `HOODY_TOKEN` | | `hoody computers stop --timeout 120` times out before the computer stops | `--timeout` gives the computer that long to shut down cleanly; it does not extend the CLI's default 30-second HTTP wait | Check the computer's status before retrying |