CLI Guide

The Vaulthalla CLI is installed as vh and vaulthalla. Both invoke the same local command client. Use vh in examples unless you prefer the long command name.

How The CLI Connects

Most CLI commands connect to the local control socket:

The socket is intended for local operators. Non-root users need membership in the group and an application user mapped to their uid (vh user create|set --linux-uid; the option has that name on macOS too).

Root commands are not a replacement for application permissions. A normal operator should use their own account after First Run binds the admin uid (on macOS the installer binds the installing user).

Help And Status

1vh2vh help3vh help vault4vh help vault sync5vh version6vh status

Running a namespace without a subcommand prints help for that namespace:

1vh vault2vh user3vh role

Exit Codes

vh fails fast instead of hanging when the daemon is unavailable, and its exit status is safe to use in scripts:

1vh status >/dev/null || echo "vaulthalla is not healthy"

Lifecycle Commands

Lifecycle commands modify host services and require sudo. They run locally and don't need the daemon.

1sudo vh setup db2sudo vh setup remote-db --host <host> --port 5432 --user <user> --database <name> --password-file <path>3sudo vh setup nginx --domain vault.example.com4sudo vh setup nginx --domain vault.example.com --certbot5sudo vh setup nginx --domain vaulthalla.dev --s3-domain s3.vaulthalla.dev --certbot-dns-cloudflare /etc/vaulthalla/certbot/cloudflare.ini6sudo vh teardown nginx7sudo vh teardown db

1sudo vh setup caddy --domain vault.home.arpa --trust2sudo vh setup caddy --domain vault.example.com --email [email protected]3sudo vh setup caddy --status4sudo vh teardown caddy

For unattended lifecycle automation, use:

1VAULTHALLA_NONINTERACTIVE=1 sudo -E vh setup db

or lifecycle options such as --non-interactive or --yes where available.

Command Conventions

Vaulthalla accepts both long option forms and normalized --key=value forms:

1vh vaults --s3 --limit 52vh vaults --s3 --limit=5

Some resources accept either name or id. For scripts, prefer ids once the resource exists.

Use --json on commands that support structured output:

1vh vaults --json

Common Operator Flow

1. Check health:

1vh status

2. Create or verify users and roles:

1vh user create alice --role admin2vh group create operators --desc "Operations team"3vh permissions --type vault

3. Create an S3 API key if needed:

1vh api-key create r2-main \2  --access <access-key> \3  --secret <secret-key> \4  --provider cloudflare-r2 \5  --endpoint https://<account-id>.r2.cloudflarestorage.com

4. Create a vault:

1vh vault create docs --local --quota 50G2vh vault create archive --s3 --api-key r2-main --bucket vaulthalla-archive --sync-strategy cache

5. Inspect sync state:

1vh vault sync info archive2vh vault sync dry-run archive

6. Export recovery material before storing critical data:

1vh vault keys export all --recipient <gpg-fingerprint> --output vaulthalla-vault-keys.json.gpg2vh secret export all --recipient <gpg-fingerprint> --output vaulthalla-secrets.json.gpg

CLI Security Notes

Treat these outputs as sensitive:

• vh secret export ...
• vh vault keys export ...
• Any command output that contains provider credentials, tokens, or unencrypted key material.

vh fs get writes vault plaintext wherever you point it (or to standard output); vh fs put sends the local file's plaintext to the daemon over the control socket, where it is encrypted like a web upload.

Use GPG recipients and files for exports whenever possible. Avoid pasting unencrypted key export output into tickets, chats, terminals with logging, or shell history.

Reference

Use Command Reference for the command families and examples.