CLI Reference

The Holden CLI provides tools for managing variables, secrets, and validating configuration.

Installation

npm

npm install -g @benjick/holden-cli

Docker

If you don’t want to install Node.js, you can run the CLI as a Docker container:

docker run --rm --network host benjick/holden-cli <command>

To make it feel like a native command, add a persistent alias:

echo "alias holden='docker run --rm --network host benjick/holden-cli'" >> ~/.bashrc

Then use it normally:

holden app list
holden deploy my-app

Note

--network host lets the CLI reach Holden’s internal API on localhost:6021 without any Docker network configuration.

To update the CLI to the latest version:

docker pull benjick/holden-cli

holden vars

Manage configuration values and encrypted secrets in holden.vars.yml.

---

holden vars set

holden vars set <key> [value] [flags]

Set a configuration variable or encrypted secret. Walks up the directory tree to find holden.yml, then edits the adjacent holden.vars.yml.

Flag	Description
--secret	Encrypt the value with age

If --secret is used without a value argument, prompts for hidden input.

Examples:

# Plain config value
holden vars set LOG_LEVEL debug

# Encrypted secret (value as argument)
holden vars set API_KEY --secret sk-secret-key

# Encrypted secret (hidden prompt)
holden vars set API_KEY --secret
Enter value: ****

---

holden vars get

holden vars get <key> [flags]

Read a configuration variable. Walks up the directory tree to find holden.yml, then reads from the adjacent holden.vars.yml.

Flag	Description
--show-secrets	Decrypt and display secret values

Examples:

holden vars get LOG_LEVEL
# debug

holden vars get API_KEY
# [secret]

holden vars get API_KEY --show-secrets
# sk-secret-key

---

holden config

Manage CLI configuration. Settings are stored in ~/.holden/config.yml.

---

holden config set

holden config set <key> <value>

Set a CLI configuration value.

Key	Description
server	SSH address of the Holden server
port	API port on the server (default: 6021)

Examples:

holden config set server [email protected]
holden config set port 6021

Note

After setting the server, the CLI fetches the encryption key via SSH and caches it in age_public_keys. Subsequent holden vars set --secret commands work offline.

---

holden config get

holden config get <key>

Read a CLI configuration value.

Example:

holden config get server
# [email protected]

SSH Connection

Commands that connect to the server (holden deploy, fetching encryption keys) shell out to the ssh command. This means:

• Keys: Uses your SSH agent and default keys (~/.ssh/id_rsa, id_ed25519, etc.)
• Config: Respects ~/.ssh/config (aliases, jump hosts, custom ports)
• Auth: Key-based authentication only, no password prompt

If you can run ssh user@server successfully, the CLI will work. No Holden-specific SSH configuration needed.

---

holden app

Manage app registrations on the Holden server.

---

holden app add

holden app add <id> --repo <url> [flags]

Register an app. Holden immediately clones the repo and starts reconciling.

Flag	Description
--repo <url>	Git repository URL (required)
--branch <branch>	Branch to track
--path <path>	Path to holden.yml within the repo

Examples:

# Simple app
holden app add my-app --repo https://github.com/you/my-app

# Monorepo
holden app add frontend --repo https://github.com/you/monorepo --path ./apps/frontend

---

holden app remove

holden app remove <id>

Unregister an app. Removes it from apps.yml. Does not stop running containers — they’ll be cleaned up during the next maintenance window.

---

holden app list

holden app list

List all registered apps with their repo URLs.

---

holden validate

holden validate

Validate holden.yml configuration. Walks up the directory tree to find holden.yml and validates it.

Checks include:

• YAML syntax
• Required fields present
• Valid field values (cron expressions, durations, etc.)

Exit codes:

Code	Meaning
0	Configuration is valid
1	Validation errors found

Example:

holden validate

---

holden deploy

holden deploy [app]

Trigger a reconcile cycle on the server. Requires SSH access to the Holden server.

• No argument: reconciles all apps
• With app name: reconciles that specific app

Examples:

# Deploy all apps
holden deploy

# Deploy specific app
holden deploy my-app

---

holden maintenance

holden maintenance [flags]

Trigger a maintenance cycle on the server. This runs backups, pulls updated images, cleans up stale resources, and reboots Holden via the Overseer.

Flag	Description
--skip-reboot	Skip the Holden container reboot after maintenance

Examples:

# Trigger maintenance
holden maintenance

# Trigger maintenance without rebooting
holden maintenance --skip-reboot