Skedly CLI

CLI tool for the Skedly webhook management platform. Intercept production webhooks and forward them to your local development server.

Installation

npm install -g skedly-cli

Requires Node.js >= 18.

Usage

Login

Authenticate with your Skedly account:

skedly login

This opens a browser for authentication via Auth0 device code flow. Credentials are stored securely at ~/.skedly/config.json.

Listen for webhooks

Forward incoming webhook events to your local server:

skedly listen --url http://localhost:3000/webhooks <webhook_secret_key>

• --url — the local URL to forward webhooks to
• <webhook_secret_key> — found in the Skedly dashboard under your webhook settings

While the CLI is running, any events received by your Skedly webhook will be forwarded to your local URL instead of the configured destination. Logs appear in real-time:

✔ Connected to webhook My Payment Webhook
  Webhook ID: a1b2c3d4-...
  Target: http://localhost:3000/webhooks

  Waiting for events... (Ctrl+C to stop)

[14:23:01] POST   → 200 (45ms)
[14:23:15] POST   → 201 (89ms)
[14:24:03] PUT    → 500 (3012ms)

Logout

Clear stored credentials:

skedly logout

Environment Variables

| Variable | Description | Default | |---|---|---| | SKEDLY_API_URL | Override the Management API URL | https://api.skedly.dev |

How It Works

1. The CLI establishes an authenticated SSE (Server-Sent Events) connection to the Skedly Management API
2. When a webhook event arrives at your Skedly endpoint, the backend detects the active tunnel and routes the event through the SSE connection to your CLI
3. The CLI forwards the event to your local URL (preserving headers, body, method, and HMAC signature)
4. The local server's response is sent back to Skedly and recorded in the event log

This means your local server receives the exact same request it would receive in production, including HMAC signatures for verification.

Auth0 Setup

The CLI uses the Device Authorization Flow to authenticate users. You can either reuse your existing Auth0 application or create a dedicated one.

Option A: Reuse Existing App (Recommended)

If you already have an Auth0 application for the Skedly web UI, you can reuse it:

1. Enable Grant Types: Go to Auth0 Dashboard → Applications → your existing app → Settings → Advanced Settings → Grant Types:

   • Enable Device Code
   • Enable Refresh Token (if not already enabled)

2. API Settings: Go to Auth0 Dashboard → APIs → your Skedly API (https://api.skedly.dev):

   • Enable Allow Offline Access (required for refresh tokens)

That's it — the CLI shares the same Client ID as the web app. No code changes needed.

Option B: Separate Native App (Self-Hosting)

If you prefer a dedicated app (or are self-hosting with a different Auth0 tenant):

1. Create Application: Go to Auth0 Dashboard → Applications → Create Application

   • Type: Native
   • Name: Skedly CLI

2. Enable Grant Types: Under the application's Settings → Advanced Settings → Grant Types:

   • Enable Device Code
   • Enable Refresh Token

3. Enable Social Connection: Under the application's Connections tab:

   • Enable the same social connections (e.g., Google) used by your Skedly web app

4. API Settings: In Auth0 Dashboard → APIs → your Skedly API:

   • Enable Allow Offline Access (for refresh tokens)

5. Configure CLI: Set the Client ID in src/utils/config.ts:

   AUTH0_CLIENT_ID: "your-native-app-client-id",

6. Rebuild: Run npm run build

Publishing to npm

# Build TypeScript
npm run build

# Login to npm
npm login

# Publish (first time)
npm publish --access public

# Publish updates (bump version first)
npm version patch  # or minor, major
npm publish

Development

# Clone the repo
git clone https://github.com/your-org/skedly-cli.git
cd skedly-cli

# Install dependencies
npm install

# Run in development mode
npm run dev -- login
npm run dev -- listen --url http://localhost:3000 <secret_key>

# Build
npm run build

# Link globally for testing
npm link
skedly --help

License

MIT