Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Hookdeck CLI는 무제한의 무료 및 영구 이벤트 URL을 제공하여 웹훅과 같은 이벤트를 로컬 웹 서버로 포워딩할 수 있게 합니다. 개발자는 이를 통해 통합 코드를 로컬 환경에서 테스트하고, 세션 간 기록 보존 기능을 활용해 이벤트를 조회하거나 재실행할 수 있습니다. 또한, AI 및 에이전트 워크플로우를 위한 Event Gateway 리소스 관리 기능도 지원합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Codex tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기Hookdeck CLI를 사용하면 무제한의 무료 및 영구적 이벤트 URL을 통해 웹훅(webhooks)과 같은 이벤트를 로컬 웹 서버로 포워딩할 수 있습니다. 이벤트 기록은 세션 간에 보존되며, 사용자 본인과 팀원들이 조회하거나 재실행하여 테스트하는 데 사용할 수 있습니다.
Hookdeck CLI는 필터링 및 팬아웃 전송(fan-out delivery)과 같은 Hookdeck의 대부분 기능과 호환됩니다. Hookdeck CLI를 사용하여 이벤트(예: 웹훅) 통합 코드를 로컬에서 개발하거나 테스트할 수 있습니다.
또한, CLI를 통해 Hookdeck Event Gateway 리소스—소스(sources), 목적지(destinations), 연결(connections), 이벤트(events), 변환(transformations)—를 관리할 수 있습니다. AI 및 에이전트 워크플로우의 경우, Event Gateway MCP 서버(hookdeck gateway mcp)는 이러한 기능을 MCP 호환 클라이언트(예: Cursor, Claude)에서 도구로 노출합니다.
다른 접근 방식과 철학을 사용하지만, ngrok 및 대체 HTTP 터널 솔루션의 대안입니다.
Hookdeck for development은 완전히 무료이며, 저희는 프로덕션 제공 서비스를 통해 플랫폼 수익화를 진행합니다.
모든 명령어와 플래그에 대한 전체 참고 자료는 REFERENCE.md를 참조하십시오.
빠른 링크: 로컬 개발 (Listen) · 리소스 관리 (CLI) / 연결 관리 · AI / 에이전트 통합 (Event Gateway MCP)
Hookdeck CLI는 macOS, Windows, 그리고 Ubuntu, Debian, RedHat, CentOS와 같은 배포판에서 사용할 수 있습니다.
Hookdeck CLI는 NPM 패키지로 배포됩니다:
npm install hookdeck-cli -g
베타(pre-release) 버전을 설치하려면:
npm install hookdeck-cli@beta -g
Hookdeck CLI는 [homebrew-core]의 Homebrew를 통해 macOS에서 사용할 수 있습니다:
brew install hookdeck
새로운 안정 버전은 Homebrew의 자동 업데이트 기능(autobump)에 의해 각 릴리스 후에 자동으로 적용되므로, brew upgrade를 실행하면 해당 버전이 가져와집니다.
저희 tap에서 베타(사전 출시) 버전을 설치하려면 다음 명령어를 사용하세요:
brew install hookdeck/hookdeck/hookdeck-beta
[!NOTE]
Homebrew 5.2.0 / 6.0.0에서HOMEBREW_REQUIRE_TAP_TRUST가 기본값이 될 때, 타사 tap의 베타 포뮬러를 설치하려면 명시적인 신뢰 단계(explicit trust step)가 필요합니다:
brew trust --formula hookdeck/hookdeck/hookdeck-beta
안정 버전인 `hookdeck` 포뮬러는 homebrew-core에 위치하므로 영향을 받지 않습니다.
Hookdeck CLI는 Scoop 패키지 관리자를 통해 Windows에서 사용할 수 있습니다:
scoop bucket add hookdeck https://github.com/hookdeck/scoop-hookdeck-cli.git
scoop install hookdeck
베타(사전 출시) 버전을 설치하려면:
scoop install hookdeck-beta
패키지 관리자 없이 Linux에 Hookdeck CLI를 설치하는 방법은 다음과 같습니다:
tar -xvf hookdeck_X.X.X_linux_amd64.tar.gz./hookdeck베타(사전 출시) 버전의 경우, GitHub 릴리스 페이지에서 .deb 또는 .rpm 패키지를 다운로드하세요 (반드시 “Pre-release”로 표시된 릴리스를 확인하십시오).
CLI는 또한 Docker 이미지로도 사용할 수 있습니다: hookdeck/hookdeck-cli.
docker run --rm -it hookdeck/hookdeck-cli version
hookdeck version x.y.z (beta)
특정 버전(베타 릴리스 포함)을 사용하려면, 버전 태그를 지정하세요:
docker run --rm -it hookdeck/hookdeck-cli:v1.2.3-beta.1 version
참고: 베타 릴리스는 latest 태그를 업데이트하지 않습니다. 안정 버전만 latest를 업데이트합니다.
CLI를 사용하여 Hookdeck 계정에 로그인하고 자격 증명을 영구적으로 저장하려면, ~/.config/hookdeck 디렉토리를 바인드 마운트할 수 있습니다:
docker run --rm -it -v $HOME/.config/hookdeck:/root/.config/hookdeck hookdeck/hookdeck-cli login
그런 다음 모든 소스에서 수신 대기(listen)를 할 수 있습니다. 그렇지 않으면 해당 포트가 컨테이너 내부의 localhost에서 접근할 수 없으므로, 호스트 머신의 포트에 도달하려면 반드시 host.docker.internal을 사용해야 합니다.
docker run --rm -it -v $HOME/.config/hookdeck:/root/.config/hookdeck hookdeck/hookdeck-cli listen http://host.docker.internal:1234
CLI를 설치하면 hookdeck 명령에 접근할 수 있습니다.
hookdeck [command]
# 상세한 CLI 명령어 정보는 `--help`를 실행하세요.
...
Hookdeck 계정으로 로그인합니다. 일반적으로 인증을 위해 브라우저 창이 열립니다.
hookdeck login
브라우저가 없는 환경(예: TTY 전용 터미널)에 있는 경우, --interactive (또는 -i) 플래그를 사용하여 API 키를 붙여넣어 로그인할 수 있습니다:
hookdeck login --interactive
Hookdeck 제품의 CLI 클라이언트 키로 인증하려면(키가 이미 계정 및 프로젝트와 연결된 경우 브라우저 단계 없음):
hookdeck login --cli-key <key>
CLI는 API를 통해 키를 검증하고, 기존에 게스트 콘솔 프로필이 있는 경우 이를 덮어쓰면서 설정을 작성합니다. 예를 들어, Hookdeck은 Event Gateway 온보딩 중이나 CLI를 콘솔 목적지로 승인할 때 이 명령을 표시할 수 있습니다.
게스트 샌드박스 업그레이드(콘솔 데이터 유지)에는
--cli-key가 없는hookdeck login이 필요하며, 제품 복사/붙여넣기 키는 안 됩니다. 로그인하지 않으면hookdeck listen과 같은 명령을 실행할 때 임시 게스트 계정이 생성됩니다.
이벤트를 HTTP 서버로 전달하기 위한 세션을 시작합니다.
hookdeck listen <port-or-URL> <source-alias?> <connection-query?> [flags]
Flags:
...
기본적으로 listen 명령어는 hookdeck login으로 저장된 자격 증명(credentials)을 사용합니다. 로그인 절차 없이 단일 호출(single invocation)을 인증해야 하는 경우 — 예를 들어 CI 환경이거나 계정을 전환할 때 — 키를 직접 전달하면 됩니다:
# 사용자 범위 CLI 키 (hookdeck login으로 생성; 모든 프로젝트에 접근 가능)
$ hookdeck listen 3000 stripe --cli-key <your-cli-key>
...
보유한 키가 CLI가 수행할 수 있는 작업을 결정합니다. 지원되는 키 공급 방식은 다음과 같습니다: CLI 키를 위한 hookdeck login, 기존 키를 붙여넣기 위한 hookdeck login --cli-key, 그리고 프로젝트 API 키를 위한 hookdeck ci --api-key입니다:
| 키 유형 | 출처 | 도달 범위(Reach) | project list / project use |
|---|---|---|---|
| CLI 키 | hookdeck login, 또는 hookdeck login --cli-key | 사용자가 속한 모든 조직의 모든 프로젝트 | 예시 (yes) |
| ... |
오직 CLI 키만이 프로젝트를 나열하거나 전환할 수 있습니다. 다른 키들은 질문이 제기된 수준보다 낮은 범위에 국한되기 때문에, hookdeck project list는 '이 자격 증명은 단일 프로젝트에 한정되어 있다'고 답변하며, 계정 전체 접근을 위해서는 hookdeck login이 필요합니다.
hookdeck ci --api-key는 프로젝트 API 키를 구체적으로 사용합니다. 이 명령어는 해당 키를 프로젝트 범위의 CLI 키로 교환하기 때문에, 이렇게 생성된 키로는 프로젝트 목록을 나열할 수 없습니다. 조직(organization) API 키는 hookdeck ci와 다른 모든 CLI 로그인 경로에서 거부되므로, CLI 인증에 전혀 사용할 수 없습니다. 대신 REST API에 직접 사용해야 합니다.
각 키가 어떻게 저장되는지에 대한 자세한 내용은 자격 증명 유형 (Credential Types)을 참조하십시오.
이벤트 게이트웨이(Event Gateway)는 주어진 source(예: Shopify, GitHub)로부터 수신된 이벤트를 connection을 통해 destination으로 라우팅합니다. hookdeck listen은 독립형 명령어로, 인증된 제품 — Hookdeck Console 또는 Event Gateway 중 어느 것과 함께 작동하든 상관없이 — 특정 연결(connection)에 대한 이벤트를 받아 지정된 포트 또는 유효한 URL의 로컬호스트(localhost)로 전달하는 역할을 합니다.
각 source에는 이벤트를 수신하는 데 사용할 이벤트 URL이 할당됩니다. 새 계정으로 시작할 경우, CLI가 첫 번째 source를 생성하도록 요청합니다. 각 CLI 프로세스는 한 번에 하나의 source만 수신할 수 있습니다.
port-or-URL매개변수는 필수이며, 유효한 포트 또는 제공된 URL을 입력하면 이벤트는 http://localhost:$PORT/$DESTINATION_PATH로 전달됩니다.
기본 인터랙티브 모드는 대체 화면 버퍼를 사용하는 전체 화면 TUI(Terminal User Interface)를 사용하므로, 종료 시 터미널 기록이 보존됩니다. 이 인터페이스는 다음을 포함합니다:
i를 사용하여 연결 세부 정보를 확장/축소할 수 있습니다.인터랙티브 모드에서는 다음 키보드 단축키를 사용할 수 있습니다:
↑ / ↓ 또는 k / j: 이벤트 간 탐색(다른 이벤트 선택)i: 연결 정보 토글(연결 세부 정보 확장/축소)r: 선택한 이벤트 재시도 (Retry)o: 선택한 이벤트를 Hookdeck 대시보드에서 열기d: 선택한 이벤트의 상세 요청/응답 정보를 표시합니다(닫으려면 d 또는 ESC를 누르세요).
↑ / ↓로 스크롤하고, 페이지 탐색은 PgUp / PgDown을 사용합니다.C, 요청 헤더에는 H, 또는 요청 본문에는 B를 누릅니다. 화면 밖 콘텐츠도 포함됩니다.q: 애플리케이션 종료(터미널 상태가 복원됨)Ctrl+C: 애플리케이션을 종료합니다.선택된 이벤트는 줄 시작 부분의 > 문자로 표시됩니다. 모든 작업(재시도(retry), 열기(open), 세부 정보(details))은 최신 이벤트뿐만 아니라 현재 선택된 이벤트에 대해 작동합니다. 이러한 단축키는 화면 하단의 상태 표시줄에 표시됩니다.
참고: 클립보드로 복사하는 기능은 macOS와 Windows에서는 별도의 설정 없이 작동합니다. Linux 및 기타 BSD/Unix 시스템에서는
xclip또는xsel중 하나가 설치되어야 합니다. 이들 중 어느 것도 없으면 복사 단축키에서 오류가 보고됩니다.
두 번째 매개변수인 source-alias는 리스닝할 특정 소스를 선택하는 데 사용됩니다. 기본적으로, CLI는 해당 소스의 모든 적격 연결에서 수신을 시작합니다.
$ hookdeck listen 3000 shopify
●── HOOKDECK CLI ──●
...
source-alias는 쉼표로 구분된 소스 이름 목록(예: stripe,shopify,twilio) 또는 모든 소스를 듣기 위한 '*' (따옴표 사용)일 수 있습니다.
$ hookdeck listen 3000 '*'
●── HOOKDECK CLI ──●
...
세 번째 매개변수인 connection-query는 리스닝할 CLI 목적지를 가진 특정 연결을 지정합니다. 기본적으로, CLI 목적지 유형을 가진 첫 번째 연결이 사용됩니다. 지정된 이름의 연결이 존재하지 않으면, 전달된 값으로 새 연결이 생성됩니다. 연결 쿼리는 connection 이름, alias, 및 path 값을 기준으로 확인됩니다.
$ hookdeck listen 3000 shopify orders
●── HOOKDECK CLI ──●
...