# The Hookdeck CLI

The Hookdeck CLI supports the following functionality:

* Forward webhook events to a local web server
* Quickly replay and inspect data of events forwarded to your local web server
* Use in combination with the [Hookdeck Console](https://console.hookdeck.com) as a free alternative to ngrok
* Use with the [Hookdeck Event Gateway](/platform) to support your local development workflows and to manage Hookdeck projects in CI/CD for testing
* Manage connections (sources, destinations, and rules) directly from the CLI

## Why use the CLI

With the CLI, you can develop, test, and troubleshoot your integration with Hookdeck – all without interfering with your production setup. It functions as a free replacement for ngrok and other tunnel solutions when working with event-driven application events such as webhooks.

## Getting started with the CLI

1. [Install the CLI](/docs/cli#installation):
  
  
2. Run the `hookdeck` command in your shell to ensure the CLI is installed.
3. Optionally, log in using `hookdeck login`. Otherwise, a temporary guest account is created for you when running commands.
4. Start a session to forward your webhooks to a local HTTP server using:
  `hookdeck listen <port> <source-name?> <connection-query?> [--path? /path] [--output? mode]`
  
  Where:
  
  * `<port>` defines the localhost port to listen on. Webhooks will be forwarded to `http://localhost:$PORT/$DESTINATION_PATH`.
  * `<source-name>` defines a specific source to listen on, if any. By default, the CLI will start listening on all eligible connections for that source.
  * `<connection-query>` defines which connection to listen for on the specified source. Valid inputs are the name of the connection, or the path of the associated destination.
  * `[--path]` optionally specifies the path (`$DESTINATION_PATH`) events will be forwarded to.
  * `[--output]` optionally controls output verbosity: `interactive` (default with keyboard shortcuts), `compact` (simple logs), or `quiet` (fatal errors only).

Interactive mode (default) uses a full-screen TUI with an alternative screen buffer, preserving your terminal history when you exit. The interface includes a collapsible connection header, scrollable event list (up to 1000 events), status bar with shortcuts, and detailed event inspection. You can navigate events with arrow keys, retry requests, open events in the dashboard, and view full request/response data. Use `--output compact` for simple logging or `--output quiet` for minimal output.

Events sent to your CLI are available on your [CLI Events page](https://dashboard.hookdeck.com/events/cli), where they can be viewed, filtered, or bookmarked for future use. You can also retry CLI events to replay them locally.

## Installation

Hookdeck CLI is available for macOS, Windows, Linux, and Docker.

### NPM & Yarn

Install Hookdeck CLI on any platform using NPM or Yarn

```bash
$ npm install hookdeck-cli -g

```

```bash
$ yarn global add hookdeck-cli

```

### macOS

Install Hookdeck CLI on macOS using [Homebrew](https://brew.sh/)

```bash
$ brew install hookdeck/hookdeck/hookdeck

```

### Windows

Install Hookdeck CLI on Windows using the [Scoop](https://scoop.sh/) package manager

```bash
$ scoop bucket add hookdeck https://github.com/hookdeck/scoop-hookdeck-cli.git
$ scoop install hookdeck

```

### Linux

Install Hookdeck CLI on Linux without a package manager by downloading the [latest release's tar.gz file](https://github.com/hookdeck/hookdeck-cli/releases/latest):

```bash
# Unzip the file:
$ tar -xvf hookdeck_X.X.X_linux_x86_64.tar.gz
# Run the executable:
$ ./hookdeck

```

### Docker

Install Hookdeck CLI on Docker by pulling the [`hookdeck/hookdeck-cli`](https://hub.docker.com/r/hookdeck/hookdeck-cli) image:

```bash
$ docker run --rm -it hookdeck/hookdeck-cli version
$ hookdeck version x.y.z (beta)

```

## Global Flags

Hookdeck CLI supports a number of global flags that can be appended to any command.

```bash
$ hookdeck {command} <arguments> [flags]

```

### Color

Enable or disable color output.

| Setting | Description |
| --- | --- |
| on | Enable color output |
| off | Disable color output |
| auto | Use the default output color based on global settings |

```bash
--color <setting>

```

### Config

Set the file path for the CLI's configuration file.

Default path: `$HOME/.config/hookdeck/config.toml`

```bash
--config <config_filepath>

```

### Device Name

Run the command on behalf of another device.

```bash
--device-name <name>

```

### Help

Get documentation for a given command, including any supported flags and arguments.

```bash
-h
--help

```

### Log Level

Set the level of detail for log messages.

Default level: `info`

| Level | Description |
| --- | --- |
| debug | Useful for development purposes |
| info | Shows standard logs |
| warn | Shows any warnings detected |
| error | Shows everything, including errors |

```bash
--log-level <level>

```

### Project Name

Define a project name for the CLI's current configuration. Enables multiple configurations across Hookdeck accounts, stored within one configuration file.

Any command can be run in the context of a project.

Default project: `default`

```bash
-p <name>
--project-name <name>

```

### Version

Print the version of Hookdeck CLI. This flag should be run without any other flags or arguments set.

```bash
-v
--version

```

## Commands

| Command | Description |
| --- | --- |
| [`login`](#login) | Connect the CLI to your Hookdeck account |
| [`logout`](#logout) | Clear your credentials |
| [`listen`](/docs/cli/listen.md) | Forward webhooks to a local server or external domain |
| [`ci`](#ci) | Authenticate and forward events in CI environments |
| [`project`](/docs/cli/project.md) | Switch between projects |
| [`connection`](/docs/cli/connection.md) | Manage Hookdeck Gateway connections between sources and destinations |
| [`source`](/docs/cli/source.md) | Manage webhook and event sources |
| [`destination`](/docs/cli/destination.md) | Manage destinations (HTTP, CLI, etc.) |
| [`transformation`](/docs/cli/transformation.md) | Manage transformation code and executions |
| [`request`](/docs/cli/request.md) | List, get, retry requests; view events and ignored events |
| [`event`](/docs/cli/event.md) | List, get, retry, cancel, or mute events |
| [`attempt`](/docs/cli/attempt.md) | List and get delivery attempts |
| [`metrics`](/docs/cli/metrics.md) | Query event, request, attempt, queue, and transformation metrics |
| [`version`](#version) | Print CLI version |
| [`whoami`](#whoami) | Print current username and project |
| [`completion`](#completion) | Configure shell auto-completion |

## Login

Login to your Hookdeck account to setup the CLI

Usage:

```bash
hookdeck login [flags]

```

Flags:

| Flag | Type | Description |
| --- | --- | --- |
| `-i, --interactive` | `bool` | Run interactive configuration mode if you cannot open a browser |

```bash
$ hookdeck login
$ hookdeck login -i  # interactive mode (no browser)

```

If you do not log in, a temporary guest account is created when you run commands.

## Logout

Logout of your Hookdeck account to setup the CLI

Usage:

```bash
hookdeck logout [flags]

```

Flags:

| Flag | Type | Description |
| --- | --- | --- |
| `-a, --all` | `bool` | Clear credentials for all projects you are currently logged into. |

```bash
$ hookdeck logout
$ hookdeck logout -a  # clear all projects

```

## Version

Print the CLI version and check whether a new version is available.

Usage:

```bash
hookdeck version

```

```bash
$ hookdeck version

```

## Whoami

Show the logged-in user

Usage:

```bash
hookdeck whoami

```

```bash
$ hookdeck whoami

```

## Completion

Generate bash and zsh completion scripts. This command runs on install when using Homebrew or Scoop. You can optionally run it when using binaries directly or without a package manager.

Usage:

```bash
hookdeck completion [flags]

```

Flags:

| Flag | Type | Description |
| --- | --- | --- |
| `--shell` | `string` | The shell to generate completion commands for. Supports "bash" or "zsh" |

```bash
$ hookdeck completion --shell zsh
$ hookdeck completion --shell bash

```

## CI

If you want to use Hookdeck in CI for tests or any other purposes, you can use your HOOKDECK_API_KEY to authenticate and start forwarding events.

Usage:

```bash
hookdeck ci [flags]

```

Flags:

| Flag | Type | Description |
| --- | --- | --- |
| `--api-key` | `string` | Your Hookdeck Project API key. The CLI reads from HOOKDECK_API_KEY if not provided. |
| `--name` | `string` | Name of the CI run (ex: GITHUB_REF) for identification in the dashboard |

```bash
$ hookdeck ci --api-key $HOOKDECK_API_KEY
Done! The Hookdeck CLI is configured in project MyProject

$ hookdeck listen 3000 shopify orders

●── HOOKDECK CLI ──●

Listening on 1 source • 1 connection • [i] Collapse

Shopify Source
│  Requests to → https://hkdk.events/src_DAjaFWyyZXsFdZrTOKpuHnOH
└─ Forwards to → http://localhost:3000/webhooks/shopify/orders (Orders Service)

💡 View dashboard to inspect, retry & bookmark events: https://dashboard.hookdeck.com/events/cli?team_id=...

Events • [↑↓] Navigate ──────────────────────────────────────────────────────────

> 2025-10-12 14:42:55 [200] POST http://localhost:3000/webhooks/shopify/orders (34ms) → https://dashboard.hookdeck.com/events/evt_...

───────────────────────────────────────────────────────────────────────────────
> ✓ Last event succeeded with status 200 | [r] Retry • [o] Open in dashboard • [d] Show data

```