WebhookStash CLI - Usage Examples

This document shows real-world usage examples of the enhanced WebhookStash CLI with interactive mode.

First-Time Setup (Interactive Mode)

Scenario: Developer using WebhookStash for the first time

$ webhookstash connect --port 3000

What happens:

╦ ╦┌─┐┌┐ ┬ ┬┌─┐┌─┐┬┌─╔═╗┌┬┐┌─┐┌─┐┬ ┬
║║║├┤ ├┴┐├─┤│ ││ │├┴┐╚═╗ │ ├─┤└─┐├─┤
╚╩╝└─┘└─┘┴ ┴└─┘└─┘┴ ┴╚═╝ ┴ ┴ ┴└─┘┴ ┴

It looks like this is your first time using webhookstash CLI.
Opening a browser so you can log in and choose a project...

Opening browser to authenticate...
If your browser doesn't open automatically, visit:
http://localhost:8080/cli/auth?device_code=abc123

Waiting for authentication...
✓ Successfully configured project: My Production App

Project: My Production App
Target: http://localhost:3000
Server: ws://localhost:8080

Connecting to WebhookStash...
✓ Connected to WebhookStash
✓ Forwarding webhooks to http://localhost:3000
Waiting for webhooks... (Press Ctrl+C to stop)

[15:04:05] stripe.payment_intent.succeeded → 200 OK (45ms)

Subsequent Runs (Auto-Connect)

Scenario: Developer returning after initial setup

$ webhookstash connect

What happens:

╦ ╦┌─┐┌┐ ┬ ┬┌─┐┌─┐┬┌─╔═╗┌┬┐┌─┐┌─┐┬ ┬
║║║├┤ ├┴┐├─┤│ ││ │├┴┐╚═╗ │ ├─┤└─┐├─┤
╚╩╝└─┘└─┘┴ ┴└─┘└─┘┴ ┴╚═╝ ┴ ┴ ┴└─┘┴ ┴

Project: My Production App
Target: http://localhost:3000    # Uses last port automatically
Server: ws://localhost:8080

Connecting to WebhookStash...
✓ Connected to WebhookStash
✓ Forwarding webhooks to http://localhost:3000
Waiting for webhooks... (Press Ctrl+C to stop)

Note: No browser popup, connects immediately using saved credentials.

Checking Status

Scenario: Developer wants to see what's configured

$ webhookstash

Output:

╦ ╦┌─┐┌┐ ┬ ┬┌─┐┌─┐┬┌─╔═╗┌┬┐┌─┐┌─┐┬ ┬
║║║├┤ ├┴┐├─┤│ ││ │├┴┐╚═╗ │ ├─┤└─┐├─┤
╚╩╝└─┘└─┘┴ ┴└─┘└─┘┴ ┴╚═╝ ┴ ┴ ┴└─┘┴ ┴

Connected to: My Production App

Common commands:
  webhookstash connect [--port 3000]    Connect your local dev server
  webhookstash projects                 List and switch projects
  webhookstash logout                   Clear local credentials

Run 'webhookstash --help' for more information.

Managing Multiple Projects

Scenario: Developer working on multiple environments

List projects

$ webhookstash projects

Output:

Your projects:

● My Production App (default)
    ID: proj_abc123
    Token: tok_****789

  Staging Environment
    ID: proj_def456
    Token: tok_****123

  Development Project
    ID: proj_xyz999
    Token: tok_****000

Switch to staging

$ webhookstash projects switch proj_def456
✓ Switched to project: Staging Environment

Connect to staging (now uses new default)

$ webhookstash connect

Connects to "Staging Environment" automatically.

Or connect to a specific project without switching default

$ webhookstash connect --project proj_xyz999

CI/CD Usage (Explicit Mode)

Scenario: GitHub Actions workflow

name: Integration Tests

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Install WebhookStash CLI
        run: go install github.com/aivaras/webhookstash-cli/cmd/webhookstash@latest

      - name: Start webhook tunnel
        run: |
          webhookstash connect \
            --project ${{ secrets.WEBHOOKSTASH_PROJECT_ID }} \
            --token ${{ secrets.WEBHOOKSTASH_TOKEN }} \
            --port 3000 \
            --no-browser &
        env:
          WEBHOOKSTASH_API_BASE_URL: https://api.webhookstash.com

      - name: Run tests
        run: npm test

Key points:

--no-browser flag prevents browser popup in headless environment
Fails fast if credentials are missing
Perfect for CI/CD pipelines

Docker Usage

Scenario: Running in Docker container

Dockerfile

FROM golang:1.21-alpine

# Install WebhookStash CLI
RUN go install github.com/aivaras/webhookstash-cli/cmd/webhookstash@latest

# Your app
COPY . /app
WORKDIR /app

CMD ["sh", "-c", "webhookstash connect --project $PROJECT_ID --token $TOKEN --port 3000 --no-browser & npm start"]

docker-compose.yml

version: '3.8'

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - PROJECT_ID=proj_abc123
      - TOKEN=tok_xyz789
      - WEBHOOKSTASH_API_BASE_URL=https://api.webhookstash.com

Environment-Specific Usage

Scenario: Different environments (local, staging, production)

Local development

# Uses local WebhookStash backend
export WEBHOOKSTASH_API_BASE_URL=http://localhost:8080
webhookstash connect --port 3000

Staging

# Points to staging backend
export WEBHOOKSTASH_API_BASE_URL=https://staging.webhookstash.com
webhookstash connect --port 3000

Production

# Points to production backend
export WEBHOOKSTASH_API_BASE_URL=https://api.webhookstash.com
webhookstash connect --port 3000

Logging Out / Resetting

Scenario: Developer wants to clear credentials and start fresh

$ webhookstash logout
Logging out from project: My Production App
✓ Successfully logged out

Run 'webhookstash connect' to log in again.

Next webhookstash connect will trigger browser auth again.

Error Scenarios

No browser, no config, explicit mode

$ webhookstash connect --no-browser
Error: no project configured and --no-browser is set. Provide --project and --token, or remove --no-browser

Missing token in explicit mode

$ webhookstash connect --project proj_123 --no-browser
Error: project proj_123 not found in config. Remove --no-browser to authenticate, or provide --token

Correct explicit mode

$ webhookstash connect --project proj_123 --token tok_456 --port 3000 --no-browser
# ✓ Works! Connects without config or browser

Advanced: Custom Port Per Project

Scenario: Different ports for different projects

# Production app runs on 3000
webhookstash connect --project proj_production --port 3000

# Staging app runs on 4000
webhookstash connect --project proj_staging --port 4000

# Development app runs on 5000
webhookstash connect --project proj_development --port 5000

The CLI remembers the last used port, but you can always override it.

Verbose Mode for Debugging

Scenario: Need to debug why webhooks are failing

$ webhookstash connect --port 3000 -v

Output includes response bodies:

[15:04:05] stripe.payment_intent.succeeded → 200 OK (45ms)
  Response: {"status":"success","id":"evt_123"}

[15:04:12] github.push → 500 Internal Server Error (120ms)
  Response: {"error":"Database connection failed"}

Migration from Legacy Usage

Before (still works!)

webhookstash connect --project proj_123 --token tok_456 --port 3000

After (new interactive way)

# First time: browser opens, you authenticate
webhookstash connect --port 3000

# Subsequent times: just connect
webhookstash connect

Both approaches work! Choose what fits your workflow.

Tips & Tricks

Quickly switch projects

# Connect to a different project temporarily (doesn't change default)
webhookstash connect --project proj_staging

# Change default permanently
webhookstash projects switch proj_staging

Remember your port

The CLI remembers your last used port:

# First run
webhookstash connect --port 8080

# Next run - uses 8080 automatically
webhookstash connect

Environment variables for team consistency

Share a .envrc file with your team:

# .envrc
export WEBHOOKSTASH_API_BASE_URL=https://staging.webhookstash.com

Everyone uses:

source .envrc
webhookstash connect

Quick status check

webhookstash  # No arguments shows status

Summary

The new interactive CLI makes local development frictionless while preserving the scriptable explicit mode for automation. Choose the mode that fits your use case:

Local dev: Use interactive mode (webhookstash connect)
CI/CD: Use explicit mode with --no-browser
Scripts: Use --project, --token, and --no-browser flags

Backward compatible with all existing workflows!

FilesExpand file tree

USAGE.md

Latest commit

History