CLI Reference

Installation

# Run without installing
npx @humanauth/cli <command>

# Or install globally
npm install -g @humanauth/cli
humanauth <command>

Commands

humanauth pair

Create a new pairing with the HARP app by generating a QR code.

humanauth pair --name <name> [--relay <url>]

Flags:

Flag	Required	Default	Description
--name <name>	Yes	—	Human-readable name for this pairing
--relay <url>	No	https://relay.humanauth.ai	Relay service URL

Example:

humanauth pair --name "my-laptop" --relay https://relay.humanauth.ai

Output:

HARP Pairing QR Code
=====================

  Scan this QR code with the HARP app on your phone.

  [QR code displayed in terminal]

  Platform:  my-laptop
  Relay:     https://relay.humanauth.ai
  Expires:   5 minutes

  Waiting for app to complete pairing...

Pairing complete!

  pair_id:  pair_a1b2c3d4e5f6
  name:     my-laptop
  relay:    https://relay.humanauth.ai

  Pairing saved to ~/.harp/pairings/my-laptop.json

humanauth list

List all saved pairings.

humanauth list

Example output:

NAME              PAIR_ID              RELAY                    PAIRED
my-laptop         pair_a1b2c3d4e5f6   https://relay.humanauth.ai   2026-04-10
work-server       pair_x7y8z9w0v1u2   https://relay.humanauth.ai   2026-04-11

humanauth revoke

Revoke a pairing. Removes the local pairing file and notifies the relay.

humanauth revoke --name <name>

Flags:

Flag	Required	Description
--name <name>	Yes	Name of the pairing to revoke

Example:

humanauth revoke --name "work-server"

Output:

Pairing "work-server" revoked.
  Relay notified: DELETE /v1/pairs/pair_x7y8z9w0v1u2
  Local file removed: ~/.harp/pairings/work-server.json

humanauth request

Send a test authorization request through HARP. Useful for verifying that pairing and push notifications work.

humanauth request --name <name> --action <action> --description <desc> [--ttl <seconds>]

Flags:

Flag	Required	Default	Description
--name <name>	Yes	—	Name of the pairing to use
--action <action>	Yes	—	Action identifier
--description <desc>	Yes	—	Human-readable description
--ttl <seconds>	No	300	Timeout in seconds (max 600)

Example:

humanauth request \
  --name "my-laptop" \
  --action "test_approval" \
  --description "This is a test authorization request" \
  --ttl 120

Output:

Sending authorization request...

  request_id:  req_m3n4o5p6q7r8
  pair_id:     pair_a1b2c3d4e5f6
  action:      test_approval
  ttl:         120s

  Waiting for response...

Response received!

  decision:   approved
  timestamp:  2026-04-12T10:30:45Z
  signature:  verified

Environment Variables

Variable	Default	Description
HARP_PAIRINGS_DIR	~/.harp/pairings	Directory for saved pairing files

Exit Codes

Code	Meaning
0	Success
1	General error (invalid args, network error)
2	Request denied
3	Request expired (TTL elapsed)