# Hoody CLI

**Page:** foundation/cli

[Download Raw Markdown](./foundation/cli.md)

---

# 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](/foundation/networking/ssh/) |

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

```bash
# 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

```bash
# 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.

```bash
# 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
```


`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](/foundation/hoody-api/realms/) |
| `-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](/foundation/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

```bash
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
# 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.

```bash
# 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](/getting-started/quickstart/): sign in and run commands on your first container.
- [Authentication](/foundation/hoody-api/authentication/): session logins compared with long-lived auth tokens.
- [Realms](/foundation/hoody-api/realms/): scope the CLI to one realm with `--realm`.
- [Proxy permissions](/foundation/proxy/permissions/): protect a container and pass credentials with the `--kit-*` flags.