Installing the CLI
Hellhound requires Node.js 18 or higher.
Supported platforms:
- ✓ macOS (Intel and Apple Silicon)
- ✓ Linux (x86_64, ARM64)
- ✓ Windows (via WSL recommended)
Native Windows (cmd.exe, PowerShell) is supported but heartbeat monitoring for --pid attach mode requires Linux or macOS. All other features work on Windows.
Global flags
These flags work with every command.
| Flag | Default | Description |
|---|---|---|
| --help | — | Show help for any command |
| --version | — | Print version and exit |
hellhound init
Link the CLI to your Hellhound account. Creates your account if it does not exist, or links to an existing account. Saves your API key to ~/.hellhound/config.json.
Run this once per machine.
Example output:
What it does:
- Prompts for your email address
- Prompts for your API key (find your key at hellhound.dev/account)
- Verifies the key is valid
- Saves config to ~/.hellhound/config.json
If you already have a config file, running hellhound init again will show your current configuration without overwriting it. To switch to a different account or API key, delete ~/.hellhound/config.json and run init again.
hellhound watch
Monitor a task automation — one that runs and exits. Wraps your existing command. Your automation code is unchanged.
Use watch for:
- ✓ Scheduled scripts that run and complete
- ✓ Cron jobs
- ✓ One-off automations triggered by events
- ✓ Pipelines with a defined start and end
Use hellhound attach instead for long-running agents.
Required flags:
| Flag | Description |
|---|---|
| --name <name> required | Unique name for this automation (e.g. "lead-pipeline") |
| --run <cmd> required | The command to run (wrap in quotes if it has spaces) |
Optional flags:
| Flag | Default | Description |
|---|---|---|
| --timeout <secs> | none | Kill agent after N seconds if still running |
Example output:
How it works:
- hellhound watch starts your command as a child process
- All stdout and stderr is captured and forwarded to Hellhound
- When the process exits, the run is recorded with:
- — Duration
- — Exit code
- — Output length
- Hellhound compares against your baseline
- If anomaly detected, alerts are sent
Important — replacing your existing command:
If your automation currently runs like this:
Replace it with:
In your crontab:
hellhound attach
Monitor a long-running automation — one that runs continuously and never exits on its own.
Use attach for:
- ✓ Always-on agents that listen for events
- ✓ Background workers processing queues
- ✓ WebSocket servers
- ✓ Any process that runs indefinitely
Use hellhound watch instead for task automations that run and exit.
Required flags (choose one):
| Flag | Description |
|---|---|
| --name <name> required | Unique name for this automation |
| --run <command> | Start this command and attach to it |
| OR | |
| --name <name> required | Unique name for this automation |
| --pid <pid> | Attach to already-running process with this PID |
Optional flags:
| Flag | Default | Description |
|---|---|---|
| --heartbeat <secs> | 30 | Send heartbeat every N seconds |
Heartbeat detection:
When using hellhound attach, Hellhound sends a heartbeat signal to the server every --heartbeat seconds (default: 30).
If the server stops receiving heartbeats for 2x the heartbeat interval, it marks the agent as dead and sends an alert.
This catches:
- — Process crashes that close silently
- — Frozen processes (running but not doing anything)
- — Network connectivity issues to the monitoring server
PID attach mode — platform notes:
Linux: full stdout capture via /proc/PID/fd/1
macOS: heartbeat-only mode (stdout capture requires --run flag)
For full log capture on macOS, use --run instead of --pid. The --pid flag on macOS provides heartbeat monitoring only — it confirms the process is alive but does not read its output.
Example output:
hellhound logs
View run history for a monitored automation. Shows the most recent runs with status, duration, and anomaly info.
Required flags:
| Flag | Description |
|---|---|
| --name <name> required | Name of the automation to show logs for |
Optional flags:
| Flag | Default | Description |
|---|---|---|
| --limit <n> | 20 | Number of runs to show |
Example output:
hellhound status
Show the current status of all monitored automations. Quick overview of what is running, healthy, or broken.
Example output:
hellhound alert
Manage alert configurations for your monitored automations. Subcommands: add, list, remove.
hellhound alert add
Add an alert destination for a monitored automation.
| Flag | Description |
|---|---|
| --name <name> required | Automation name to configure alerts for |
| --channel <channel> required | Alert channel: email, slack, or sms |
| --to <destination> required | Where to send alerts (see per-channel below) |
Channel options:
Email:
Slack:
Requires a Slack incoming webhook URL. Get one at: api.slack.com/apps → Incoming Webhooks
SMS (Agency plan only):
Phone number must be in E.164 format (+ followed by country code and number). International formats supported.
You can add multiple alert destinations per automation. Alerts are sent to ALL configured destinations when triggered.
hellhound alert list
List all configured alert destinations for an automation.
hellhound alert remove
Remove an alert destination by its ID.
Get the ID from hellhound alert list.
hellhound dashboard
Open the Hellhound web dashboard in your default browser.
Configuration file
The CLI stores its configuration at:
Contents:
| Field | Description |
|---|---|
| api_key | Your Hellhound API key — authenticates all requests |
| Your account email — informational only |
Reset config:
To reset your configuration (clear API key and start fresh):
Environment variables
You can override config file values using environment variables. Environment variables take precedence over the config file.
| Variable | Description |
|---|---|
| HELLHOUND_API_KEY | API key — overrides config file value |
When to use environment variables:
CI/CD pipelines:
Store your API key as a secret, not in a config file.
CLI exit codes
The hellhound CLI exits with these codes:
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error (bad flags, network error, etc.) |
| 2 | Authentication error (invalid or missing API key) |
| 3 | Agent process exited with non-zero code |
| 130 | Interrupted (Ctrl+C) |
When using hellhound watch in a cron job, be aware that exit code 3 means your monitored agent crashed — not that Hellhound itself failed. Hellhound still recorded the crash and sent your alerts before exiting with code 3.
If you want cron to not retry on agent crash, check the exit code in your cron wrapper:
Command cheat sheet
All commands in one place for quick reference.