npm package: @hallpass/cli
Description: CLI for Hallpass — profile management, key generation, attestations, delegations, message signing and verification.
Latest version: 0.5.1

# Hallpass CLI

Agent-first CLI for the [Hallpass](https://hallpass.org) 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

```bash
npm install -g @hallpass/cli
```

## Quick start

```bash
# 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:

```bash
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:

```bash
# 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:

```bash
# 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
# 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:

```bash
# 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](https://justin.poehnelt.com/posts/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