Hoody CLI reference
Section titled “Hoody CLI reference”Lookup tables for the Hoody CLI. Every command group documents its own flags in hoody <command> --help.
Requirements
Section titled “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
Section titled “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 <address> -p | Prompt for the password without echoing it |
--token <token>, --realm <id> | 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 |
# Sign in from a script without the password on the command lineprintf '%s' "$HOODY_PASSWORD" | hoody login --username "$HOODY_USERNAME" --password-stdinToken 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
Section titled “Where commands act”Target computer, first match wins:
--computer <id>or-c <id>, anywhere on the command lineHOODY_COMPUTER(orHOODY_COMPUTER_ID)- The saved default for the active profile
# Save a default; commands without -c now use ithoody config set computer "$COMPUTER_ID"
# Same setting, through the curated defaults commandhoody local defaults set computer "$COMPUTER_ID"
# Show computer, realm, output, noColor and quiet, each with where its value comes fromhoody local defaults get
# Forget the defaulthoody 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 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
Section titled “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 <computer> and hoody hub -c <computer> 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
Section titled “Hub and agent commands”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 <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.
--realmHOODY_REALM, thenHOODY_REALM_ID- The realm saved in the active profile (
hoody use) - The realm the last
hoody hubended in, while the account still has it - The realm with the most computers, provided at least one computer exists
- 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
Section titled “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:
--profile <name>HOODY_PROFILE- The
defaultProfilekey in the config file default, which usesprofiles.defaultover 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 <name> | 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
Section titled “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
Section titled “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
Section titled “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 <duration> 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
Section titled “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 |
|---|---|---|
<key=value>, 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"}' |
<key=value>, 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 |
<json|@file.json|@-> | One JSON document | --patch '{"theme":null}' |
<value|json|@file.json|@-> | 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 @-.
hoody auth tokens update "$TOKEN_ID" --public-storage '{"answer":42,"nested":{"a":[1,2]}}'hoody auth tokens update "$TOKEN_ID" --public-storage @storage.jsoncat 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 <value|json|@file.json|@-> 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: --<flag> sends true, --no-<flag> false and --unset-<flag> null, such as --unset-enable-proxy on hoody computers proxy settings update. --unset-<flag> with either of the others is refused before anything is sent |
Configuration file
Section titled “Configuration file”Settings live in ~/.hoody/config.json. --config <path> 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 <key> | Print one key (dotted paths work) |
hoody config set <key> <value> | Set a key |
hoody config clear <key> | 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
Section titled “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 <path>, --local-password-fd <n>, --local-password-stdin, --local-password <value> | 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
Section titled “Global flags”| Flag | Effect |
|---|---|
-c, --computer <id> | Target computer |
-o, --output <format> | Output format |
--profile <name> | Use a named profile |
--realm <id> | Scope platform requests to a realm |
-t, --token <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 <url> | API base URL (default https://api.hoody.com) |
--config <path> | Use another config file |
--proxy <url> | 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 |
--mask-urls | Shorten ids in the terminal layout, for sharing your screen; see masked ids |
--kit-auth, --kit-user, --kit-token, --kit-token-header | Credentials for computers protected by proxy permissions |
Run hoody --help for the rest.
Confirmation prompts
Section titled “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
Section titled “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
Section titled “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 |
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
Section titled “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 <command> --help | Flags and examples for one command |
hoody help <command> | The same, spelled out |
hoody chat "<question>" | An answer about Hoody, from Hoody, with no API key |
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause | What to do |
|---|---|---|
| A kit command says no computer is selected | No -c, no HOODY_COMPUTER, no saved default | Pass -c <id>, export HOODY_COMPUTER, or save a default with hoody config set computer <id> |
| 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 <name> 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 <name>, 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 |