Hoody CLI

hoody is the command-line client for your Hoody account and your containers. 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: installing it, signing in, the defaults it remembers, and removing it. Every command group documents its own flags in hoody <command> --help.

Install

The CLI needs Node.js 20.3 or later (22 or later recommended: Node.js 20 is end-of-life), or Bun. Proxy settings (--proxy, HTTPS_PROXY / HTTP_PROXY / ALL_PROXY, or the config proxy key) need Node.js 22.19 or later, or the standalone binary: on older Node.js, with a proxy configured, requests stop with PROXY_UNSUPPORTED and are not sent, except to hosts in NO_PROXY. On Node.js 20.3 to 22.18, npm prints an engine warning for undici, which is not loaded there (Node.js’s built-in fetch is used instead); installs with engine-strict=true need Node.js 22.19 or later.

Method	Command
npm, global	npm install -g hoody-sdk
No install	npx hoody-sdk <command> (also bunx, pnpm dlx)
Standalone binary, Linux and macOS	curl -fsSL https://install.hoody.com | sh
Standalone binary, Windows	iwr https://install.hoody.com/install.ps1 -UseB | iex
Nothing local	ssh hoody.com opens the CLI in a memory-only session; see SSH access

The package installs one command, hoody. The standalone binary carries its own runtime, so it needs no Node.js. Check the install with hoody --version.

Sign in

# 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 hdy_... --realm $REALM_ID

# No account yet
hoody signup

hoody login saves the session to ~/.hoody/config.json (mode 0600). Two flags matter for scripts: --print-token prints only the access token to stdout, and --no-save authenticates without writing anything to the config file. --non-interactive (a global flag) makes any command fail instead of prompting.

For headless use, skip the login entirely: set HOODY_TOKEN and, if you target a non-default API, HOODY_API_URL. The token the CLI uses comes from the first of these that is set: --token (-t), HOODY_TOKEN, the saved session.

Default container

Kit commands (files, terminal, exec, db, agent, and the rest) and per-container commands (snapshots, firewall, network, storage) need a target container. The CLI resolves it in this order:

1. --container <id> or -c <id>, placed before the subcommand
2. HOODY_CONTAINER (or HOODY_CONTAINER_ID)
3. The saved default for the active profile

# Save a default; commands without -c now use it
hoody config set container $CONTAINER_ID

# Same setting, through the curated defaults command
hoody local defaults set container $CONTAINER_ID

# Show container, realm, output, noColor and quiet, each with where its value comes from
hoody local defaults get

# Forget the default
hoody config clear container

A container id is the 24-character hex id from hoody containers list; a container name does not work. hoody config set container refuses any other value, and the API refuses one passed with -c or HOODY_CONTAINER. hoody login can save your account’s default container for you, so run hoody local defaults get if commands without -c reach a container you did not expect.

Profiles

A profile is a named set of settings inside the same config file: its own token, base URL, default container, realm, and output format. Use one per account or per environment.

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 the top-level keys of the file

A profile’s keys override the top-level keys, and anything it does not set is inherited from the top level.

# 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 container $STAGING_CONTAINER_ID --for-profile staging

# Run one command, or a whole shell, under a profile
hoody --profile staging containers 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

Caution

config set, config get and config clear address 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 ... writes into the staging profile, which must already exist, and --for-profile <name> does the same; config set --for-profile <name> creates the profile when it is missing. local defaults set also takes --for-profile, and otherwise follows the active profile.

Output formats

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

Format	Output
table	Human-readable table; the default for requests
wide	The table with extra columns
json	JSON, for jq and scripts
yaml	YAML
raw	The response body unformatted, for piping
ndjson	One JSON object per line; the default for streams
pretty	Formatted stream output

Configuration file

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

Command	Effect
hoody config path	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 it only asks for it)

Commonly set keys: container, 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 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. Run hoody local lock --help for its subcommands.

Global flags

Flag	Effect
-c, --container <id>	Target container
-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
-y, --yes	Skip confirmation prompts on destructive actions
-q, --quiet	Print errors only
-v, --verbose	Show the HTTP requests
--non-interactive	Fail instead of prompting
--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
--kit-auth, --kit-user, --kit-token, --kit-token-header	Credentials for containers protected by proxy permissions

Run hoody --help for the rest.

Environment variables

Variable	Equivalent
HOODY_TOKEN (or HOODY_API_TOKEN)	--token
HOODY_API_URL (or HOODY_BASE_URL)	--base-url
HOODY_CONTAINER (or HOODY_CONTAINER_ID)	--container
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_NO_UPDATE_CHECK=1	Turn off the update check
NO_COLOR	--no-color
HTTPS_PROXY, HTTP_PROXY, ALL_PROXY	--proxy

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

Update

hoody update

hoody update checks whether a newer release exists and prints the command that installs it. It does not replace the installed CLI. For an npm install, that command is npm install -g hoody-sdk; for the standalone binary, rerun the install script. HOODY_NO_UPDATE_CHECK=1 turns the check off.

Shell completion

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

# bash
hoody completion bash > ~/.local/share/bash-completion/completions/hoody

# zsh (the directory must be on your $fpath)
hoody completion zsh > ~/.zsh/completions/_hoody

# fish
hoody completion fish > ~/.config/fish/completions/hoody.fish

Open a new shell to load it. Regenerate the file after an update so it picks up new commands.

Uninstall

Removing the package does not remove ~/.hoody, and that directory holds a working access token and refresh token. End the session first, then delete the files.

# 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. End every session of the account, on every device, and clear the saved credentials
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

# 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 only clears the credentials on this device; the session token stays valid on the server until it expires. --all ends every session of the account, so other devices signed in to the same account have to sign in again. Run hoody --profile <name> logout --all for each profile that holds a different account. hoody logout does not delete auth tokens (hdy_...), which is why step 2 exists.

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.

Built-in help

Command	Shows
hoody	Status dashboard and a guided start
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

• A kit command says no container is selected: pass -c <id>, export HOODY_CONTAINER, or save a default with hoody config set container <id>.
• A command reaches the wrong container or account: 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 container value: the CLI accepts only the 24-character hex id, not the container name.
• A setting written with --profile does not apply to that profile: --profile selects the profile for reading; write into a profile with --for-profile <name>.
• No authentication credentials found: sign in with hoody login, or set HOODY_TOKEN.

What’s Next

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