CLI reference

This page lists every hookspot command with its flags. The environment variables, the configuration file and the errors follow them.

Global flags

Every command accepts these flags.

Flag	Default	Description
--cli-key KEY	none	Use this CLI key instead of HOOKSPOT_CLI_KEY or the saved key. Your shell history keeps it, so prefer the variable.
--config PATH	none	Use this configuration file.
--project PROJECT_UID	none	Listen to this project for one run. Only listen reads it.
-h, --help		Print help for the command.

hookspot -v or hookspot --version prints the CLI’s version.

hookspot login

Log in through the browser, and save a CLI key and the project you pick.

hookspot login

Flag	Default	Description
-i, --interactive	false	Ask for a CLI key instead of opening the browser. A key piped on stdin needs it too.

hookspot login -i

Enter your hookspot CLI key (Account settings > CLI key):
✓ Logged in as you@example.com

The CLI hides the key as you type it. With --cli-key or HOOKSPOT_CLI_KEY set, login saves that key without a prompt or the browser. Log in walks through the browser login.

hookspot logout

Delete the saved CLI key. The saved project stays.

hookspot logout

✓ Logged out

If HOOKSPOT_CLI_KEY is set, the CLI says that this key still works until you unset it.

hookspot project list

Print every project you can open, with its UID.

hookspot project list

╭─ Projects ──────────────────────────────────────────────────────────────── 1 ─╮
│ UID                              ORGANIZATION        PROJECT                  │
├───────────────────────────────────────────────────────────────────────────────┤
│ proj_TgGWpwkrXkmA06kUc8LY1PaoCq  Documentation demo  Default project  active  │
╰───────────────────────────────────────────────────────────────────────────────╯

hookspot project use

Save the project that listen uses.

hookspot project use [ORGANIZATION [PROJECT]]

Flag	Default	Description
--local	false	Save the project for the current directory only, in .hookspot/config.toml.

hookspot project use "Documentation demo" "Default project"

✓ Active project set to Documentation demo | Default project

With no argument, the CLI saves your only project, or lets you pick one from a list. One argument is a project UID or an organization name. Two arguments are an organization and a project name. Names ignore case.

hookspot listen

Receive the project’s webhooks, show them, and forward them to your app.

hookspot listen [SOURCE...]

Flag	Default	Description
--forward-to URL	none	Your app’s address, such as http://localhost:3000 or 3000. Without it, the CLI only shows each webhook.
--stream	false	Print a stream instead of the full-screen view.
--show-sensitive-headers	false	Show the values of authorization, cookie and API key headers on screen, in curl commands and in fixtures.
--max-body-lines N	12	Body lines to show per request. 0 shows every line.
--max-headers N	20	Headers to show per request. 0 shows every header.
--max-value-chars N	160	Characters to show per value or body line. 0 shows them all.

The limits and the hidden headers change only what the CLI shows. Your app always gets the whole request. Listen and forward shows each view.

hookspot version

Print the CLI’s version, and a notice when a newer release is out.

hookspot version

Flag	Default	Description
--json	false	Print the build details as JSON, without checking for a newer release.

hookspot completion

Print a completion script for bash, zsh, fish or powershell.

hookspot completion fish > ~/.config/fish/completions/hookspot.fish

hookspot completion zsh --help shows where your shell loads the script from. The other shells have the same help.

Environment variables

Variable	Description
HOOKSPOT_CLI_KEY	CLI key. It replaces the saved key, and --cli-key replaces it.
HOOKSPOT_CONFIG_FILE	Path of the configuration file. --config replaces it.
HOOKSPOT_ORGANIZATION_SLUG	Organization slug, the first part of a project’s address in the app. Set it with HOOKSPOT_PROJECT_SLUG.
HOOKSPOT_PROJECT_SLUG	Project slug, the second part of that address. Together, the two choose the project for listen, and --project replaces them.
NO_COLOR	1 or true turns colour off.

Configuration file

hookspot login and hookspot project use save the CLI key and the project in the configuration file. The file holds the key in plain text, so the CLI refuses it when anyone else can read or change it.

Each command reads and saves one file, the first of these that applies:

1. The file in --config.
2. The file in HOOKSPOT_CONFIG_FILE.
3. .hookspot/config.toml in the current directory, which hookspot project use --local creates.
4. ~/.config/hookspot/config.toml.

Caution

hookspot project use --local copies your saved CLI key into the new file. Add .hookspot/ to .gitignore before you run it in a repository.

Errors

The CLI prints each error in a box when it runs in a terminal, with a hint when it has one:

hookspot listen

╭─ ✗ Error ─────────────────────────────────────╮
│ not logged in                                 │
│                                               │
│ Run 'hookspot login' or set HOOKSPOT_CLI_KEY. │
╰───────────────────────────────────────────────╯

After an error, the CLI exits with status 1. Stopping it with Ctrl-C exits with 0.

Error	What to do
not logged in	Run hookspot login, or set HOOKSPOT_CLI_KEY.
authentication failed: the Hookspot CLI key was rejected	Run hookspot login again, or copy the key again from Account settings.
login attempt expired	Run hookspot login again, and approve the login within 10 minutes.
no active project	Run hookspot project use, or pass --project.
resolve project: … 404 Not Found	The project is gone, or you lost access to it. Run hookspot project use.
no sources with routes in and the project’s name	Create a route in the app, or resume a paused route or path. Then run hookspot listen again.
source "Orders" is not present in project …	Name the source exactly as the app does. The CLI suggests the name when only the case differs.
none of the named sources has a route	Create a route for the source, or name another source.
invalid --forward-to value	Pass an http:// or https:// address without a user name, query or fragment.
rendering limits must be zero or greater	Pass 0 or a positive number to the --max- flags.
could not connect to Hookspot after 10 attempts	Check your network, then run hookspot listen again.
load configuration: config file permissions 644 are not private	Run chmod 600 on the configuration file.
load configuration: selected config file does not exist	Fix the path in --config or HOOKSPOT_CONFIG_FILE.
resolve listen configuration: HOOKSPOT_ORGANIZATION_SLUG and HOOKSPOT_PROJECT_SLUG must both be set and nonempty	Set both variables, or neither.
load configuration: --local cannot be combined with --config or HOOKSPOT_CONFIG_FILE	Leave out --config and HOOKSPOT_CONFIG_FILE when you pass --local.