Skip to content

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

Hoody.com

Lookup tables for the Hoody CLI. Every command group documents its own flags in hoody <command> --help.

ItemRule
RuntimeNode.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.jsWith a proxy configured, requests stop with PROXY_UNSUPPORTED and are not sent, except to hosts in NO_PROXY
Engine warningOn 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=trueInstalls with it need Node.js 22.19 or later
Command or flagEffect
hoody loginInteractive: pick password, browser, or token, then answer the prompts. Saves the session to ~/.hoody/config.json (mode 0600)
--webSign in through your browser (GitHub, Google, or an existing session)
--email <address> -pPrompt 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-tokenhoody login and hoody signup: print only the access token to stdout
--no-savehoody login and hoody signup: authenticate without writing anything to the config file
--password-stdinhoody 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 signupCreate an account
hoody auth accesstoken getPrint 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 setupFinish 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
Terminal window
# 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.

Target computer, first match wins:

  1. --computer <id> or -c <id>, anywhere on the command line
  2. HOODY_COMPUTER (or HOODY_COMPUTER_ID)
  3. The saved default for the active profile
Terminal window
# 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
RuleDetail
Computer idsThe 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 defaulthoody 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 computerSaving 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

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.

GroupCommands that look up a name
hoody computersget, update, delete, stats, start, stop, restart, pause, resume, copy, sync
hoody daemon programsget, update, delete, enable, disable, start, stop, status, logs get, logs stream, sandbox get
hoody daemon ephemeralprogramsstatus, stop, logs get
hoody curl jobs, hoody curl schedulesjobs: get, delete, cancel, result get; schedules: get, update, delete
hoody poolsget, update, delete, members invite, members remove, members role set (the pool argument)
hoody wallet payments methodsget, update, delete, default set
hoody serversrent (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.

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.

CommandEffect
hoody hubOpen 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 --demoOpen 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 welcomeSigned 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 setupStart 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 subcommandsWork 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 whenIt printsExit
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-ffiThat 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 address2
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 known2
The input or output is not an interactive terminalThat the terminal Hub needs an interactive terminal2
No one is signed in, or the sign-in expiredRun hoody login, then hoody hub again2
A realm name matches no realm, or more than oneThe realm names, or the ids of the matches to pass instead1
--realm is given with --demoThat the sample account has its own realms2
The API does not answerThe API address and did not answer; try again1

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 <name>
  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.

CommandWrites to
config set, config get, config clearThe 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 setTakes --for-profile, and otherwise follows the active profile; creates the profile when it is missing
hoody --profile staging loginThe session is saved to that profile only

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.

FormatOutput
tableTable; the default in a pipe. Typed on a terminal, it replaces the terminal layout
wideThe table with extra columns
jsonJSON, for jq and scripts
yamlYAML
rawText 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
ndjsonOne JSON object per line; the default for streams
prettyFormatted stream output
CaseBehaviour
--httpPrints 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-curlPrints the same request as a curl line. Put back any redacted value or withheld body before you run it
Writes and promptsNeither flag sends anything that writes, and no confirmation is asked
TokenNever 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 pagesThe preview says how the next pages are read
A name in place of an idStill looked up first, with a GET that is sent
A command that cannot show its requestsSuch as hoody shell: refuses both flags and exits 2 before it does anything
FlagWorks onEffect
--watch [interval]List commandsRedraws the list in place every interval (default 2s; for example 500ms, 1m) until Ctrl+C. Needs an interactive terminal
stream commandshoody daemon programs logs stream, hoody exec logs stream, hoody proxy logs stream, hoody agent logs streamKeep printing new entries as they arrive. A read such as hoody daemon programs logs get prints once and has no -f or --follow
--until-doneCommands that start an operation which finishes later, such as hoody computers copyWaits 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

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 --helpTakesExample
<key=value>, a mapOne 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 objectsOne 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 @-.

Terminal window
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 @-
RuleDetail
One form per flagA 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 sourceA 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 inputRead only for an explicit @-, and only one flag of a command can read it
Invalid documentsA 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 flagOn 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 flagsA 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 nullA 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

Settings live in ~/.hoody/config.json. --config <path> points one command at a different file.

CommandEffect
hoody config path getPrint the path of the file in use
hoody config getPrint the whole file, secrets masked
hoody config get --resolvedPrint 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 validateCheck the file and report problems
hoody config reset --yesOverwrite 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).

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 flagEffect
hoody local lock enableTurn the lock on and move the sensitive fields into ~/.hoody/lock.json
hoody local lock statusShow the lock’s state, how many profiles it protects, and file permissions
hoody local lock password setChange the lock password; every protected field is encrypted again under the new one
hoody local lock disableTurn the lock off. Without --write-plaintext it forgets all tokens; with it, it writes them back in plain text
hoody local lock doctorRun 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.

FlagEffect
-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, --passwordCredentials for automatic login; put them before the command name
-y, --yesSkip confirmation prompts on destructive actions
-q, --quietHide status and progress messages; response data still prints to stdout
-v, --verboseShow the HTTP requests
--non-interactiveFail 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-colorDisable colored output
--http, --http-curlPrint the request instead of sending it; see request previews
--mask-urlsShorten ids in the terminal layout, for sharing your screen; see masked ids
--kit-auth, --kit-user, --kit-token, --kit-token-headerCredentials for computers protected by proxy permissions

Run hoody --help for the rest.

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.

--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.

RuleDetail
What is maskedA 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 showsIts first and last 4 characters, such as 65f2…9a1c (... where the terminal cannot show …)
Not maskedOutput 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

A flag beats its environment variable, and the environment variable beats the config file.

VariableEquivalent
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_HEADERThe --kit-* flags
HOODY_KIT_PASSWORDThe kit password for --kit-auth password
HOODY_AGENT_MODE=1The output layout of earlier releases on a terminal too; see output formats
HOODY_MASK_URLS=1--mask-urls
HOODY_NO_UPDATE_CHECK=1Turn off the update check
NO_COLOR--no-color
HTTPS_PROXY, HTTP_PROXY, ALL_PROXY--proxy
CommandShows
hoodyWhere commands act, and every command on one page
hoody --helpEvery command group and the global flags
hoody <command> --helpFlags 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
SymptomCauseWhat to do
A kit command says no computer is selectedNo -c, no HOODY_COMPUTER, no saved defaultPass -c <id>, export HOODY_COMPUTER, or save a default with hoody config set computer <id>
A command reaches the wrong computer or accountA profile, environment variable or saved default you did not expectRun 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 valueThe name matched no computer, or more than onePass 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 existsCreate it by writing with --for-profile <name>, which creates a missing profile
No authentication credentials foundNo token and no saved sessionSign 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 waitCheck the computer’s status before retrying