Hallpass CLI

Agent-first CLI for the Hallpass identity and message proof protocol. Designed for both AI agents and humans.

When running in a TTY, the CLI shows colored output, interactive prompts, and spinners. When piped or run with --json, it produces structured JSON for machine consumption.

Install

npm install -g @hallpass/cli

Quick start

# Register and log in (interactive prompts if flags omitted)
hallpass auth register
hallpass auth login

# Set up an agent using a token from the dashboard
hallpass agent setup --token <enrollment-token> --username billing_bot

# Check your setup
hallpass whoami

# Sign a message
hallpass message sign --key billing_bot --username acme --body "Hello"

# Pipe sign → verify in one line
hallpass message sign --key billing_bot --username acme --body "Hello" \
  | hallpass message verify --json -

# Sign and submit in one line
hallpass message sign --key billing_bot --username acme --body "Hello" \
  | hallpass message send --json -

Agent setup (recommended)

The fastest way to get an agent running. In the Hallpass dashboard, click Add agent, enter a username, and copy the setup command:

hallpass agent setup --token <token> --username billing_bot

This generates a key pair on your machine, enrolls the agent, and (for service-managed accounts) delegates automatically. The private key is saved to ~/.hallpass/keys/billing_bot.json and registered in your local key config. Your agent can sign messages immediately.

Commands

Authentication

| Command | Description | |---|---| | auth register | Register a new profile (prompts for username/password if omitted) | | auth complete-registration | Complete a web-initiated self-managed registration | | auth login | Sign in and store the session locally | | auth logout | Sign out and clear the stored session | | auth status | Show the current session and profile (alias: whoami) |

Agent setup

| Command | Description | |---|---| | agent setup | Set up an agent with generated keys using an enrollment token |

Flags: --token (enrollment token from dashboard), --username (agent username), --display-name, --description, --base-url, --key-file (skip generation, use existing key), --save-key (custom save path), --name (key profile name).

Key management

| Command | Description | |---|---| | key generate | Generate an ECDSA P-256 agent key pair | | key describe | Print public details of a key | | key list | List all named key profiles | | key add | Register an existing key file under a name | | key default | Set the default key profile | | key remove | Remove a named key profile |

Attestations

| Command | Description | |---|---| | attestation list | List attestations for the current profile | | attestation create | Create a new attestation (interactive kind/method selection) | | attestation verify | Trigger verification for an attestation | | attestation delete | Delete an attestation |

Delegations

| Command | Description | |---|---| | delegation enroll | Enroll a child profile (agent) | | delegation challenge | Issue, sign, and verify a key-possession challenge | | delegation prepare | Prepare an unsigned delegation payload | | delegation submit | Submit a signed delegation JWS | | delegation revoke | Revoke an active delegation | | delegation token | Create an enrollment token |

Messages

| Command | Description | |---|---| | message sign | Create a signed message proof bundle | | message send | Submit a signed bundle to the server | | message verify | Server-side stateless verification | | message verify-local | Locally verify a message bundle | | message decode-jwt | Decode a JWT without signature verification | | message sign-challenge | Sign a key-possession challenge token | | message sign-delegation | Sign a delegation payload |

Profiles & workspace

| Command | Description | |---|---| | profile show | Fetch a public profile by username | | workspace | Fetch the current workspace state | | inbox | Fetch inbox messages |

Diagnostics

| Command | Description | |---|---| | whoami | Show current config: default key, server, session | | doctor | Check CLI environment health | | schema | Machine-readable command introspection | | completion <shell> | Generate shell completions (bash, zsh, fish) |

Named key profiles

Instead of passing --key-file path/to/key.json with every command, register keys under names:

# Register during generation
hallpass key generate --key-file billing-key.json --name billing

# Or register an existing key
hallpass key add --name billing --key-file billing-key.json

# Set a default
hallpass key default --name billing

# Now just use --key
hallpass message sign --key billing --username acme --body "Hello"

# Or omit --key entirely if a default is set
hallpass message sign --username acme --body "Hello"

Profiles are stored in ~/.hallpass/keys.json.

Interactive prompts

When running in a terminal, the CLI prompts for missing required input:

# No flags needed — prompts for username and password
hallpass auth login

# Prompts for kind, value, and verification method
hallpass attestation create

Prompts are skipped when flags are provided or when stdin is not a TTY, making every command work identically in scripts and agent pipelines.

Shell completions

# Bash
eval "$(hallpass completion bash)"

# Zsh
eval "$(hallpass completion zsh)"

# Fish
hallpass completion fish > ~/.config/fish/completions/hallpass.fish

Piping & composability

Commands compose via Unix pipes. message verify and message send auto-unwrap the { "bundle": ... } wrapper from message sign output:

# Sign and verify in one line
hallpass message sign --key billing --username acme --body "Hello" \
  | hallpass message verify --json -

# Read payload from a file via stdin
cat payload.json | hallpass message sign-delegation --key billing --json -

Agent-first design

This CLI follows the principles from Rewrite Your CLI for AI Agents:

• Dual-mode output — colored human output in TTY, structured JSON when piped or with --json
• --json raw payload input — agents can pass the full API payload as a single flag; use --json - for stdin
• schema introspection — hallpass schema dumps all commands, flags, types, and examples as JSON
• --dry-run — validates inputs without executing mutating operations
• Input hardening — rejects control characters, path traversals, embedded query params, and double-encoded strings
• Env var auth — HALLPASS_BASE_URL and HALLPASS_SESSION for headless operation
• Named key profiles — --key <name> avoids repeated --key-file paths
• Overwrite protection — key generate requires --force to overwrite existing files
• File permissions — key files default to 600; warnings on overly permissive files
• whoami + doctor — self-diagnosis without reading docs
• Per-command --help — every command and subcommand has detailed help with flags and examples
• Shell completions — bash, zsh, and fish tab completion

Global flags

| Flag | Short | Description | |---|---|---| | --help | -h | Show help text | | --version | -v | Print version | | --dry-run | -n | Validate without executing | | --force | -f | Skip confirmation prompts | | --base-url <url> | | Server URL (or HALLPASS_BASE_URL) | | --session <cookie> | | Session cookie (or HALLPASS_SESSION) | | --key <name> | | Use a named key profile | | --key-file <path> | | Path to a key material JSON file | | --json <payload> | | Raw JSON input; use - for stdin |

Environment variables

| Variable | Description | |---|---| | HALLPASS_BASE_URL | Base URL for the Hallpass API (default: https://hallpass.org) | | HALLPASS_SESSION | Session cookie for authenticated endpoints | | HALLPASS_REGISTRATION_TOKEN | Registration token for self-managed registration | | HALLPASS_ENROLLMENT_TOKEN | Enrollment token for agent setup |

License

MIT