Vaulthalla Logo

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:

1/run/vaulthalla/cli.sock

The socket is intended for local operators. Non-root users need membership in the vaulthalla Linux group and an application user mapped to their Linux UID.

Root commands are not a replacement for application permissions. A normal operator should use their own Linux account after First Run binds the admin UID.

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

Lifecycle Commands

Lifecycle commands modify host services and require sudo:

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 teardown nginx6sudo vh teardown db

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
  1. Create or verify users and roles:
1vh user create alice --role admin2vh group create operators --desc "Operations team"3vh permissions --type vault
  1. 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
  1. Create a vault:
1vh vault create docs --local --quota 50G2vh vault create archive --s3 --api-key r2-main --bucket vaulthalla-archive --sync-strategy cache
  1. Inspect sync state:
1vh vault sync info archive2vh vault sync dry-run archive
  1. 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.

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.