CLI Connection Management

CLI Responsibilities

The CLI has three jobs: store an API credential, run resource commands against the FastHook API, and optionally keep a CLI destination connected to a local HTTP receiver. Treat these as separate workflows so automation does not blur route configuration with local development state.

• Configuration: login, logout, default team id, and default CLI destination id.
• Resource commands: sources, destinations, connections, transformations, requests, events, attempts, metrics, project-secrets, and auth.
• Raw API fallback: fasthook api METHOD /path for routes that do not need a dedicated wrapper.
• Tunnel runtime: fasthook tunnel connects one CLI destination to a localhost-style HTTP target.
• Incident operations: pause or unpause one branch, inspect failed events, retry one event, then create or cancel a bulk operation.

Install And Authenticate

Install the released Windows executable or build fasthook-cli from source. The examples use fasthook; if you run the executable from the current directory on Windows, use .\fasthook.exe instead.

Log in with the Project Secrets API Key, not the FastHook delivery signing secret. When the key can access more than one team, set a team id so every command sends x-team-id.

• fasthook login stores the API key in ~/.fasthook/config.json by default.
• fasthook config can store a default team and CLI destination id.
• The CLI masks the stored key when you print config.
• FASTHOOK_CONFIG can move the config file for CI or per-project terminals.
• FASTHOOK_API_KEY, FASTHOOK_TEAM_ID, FASTHOOK_DESTINATION_ID, and FASTHOOK_LOCAL_URL can override stored values.

# Windows executable
Invoke-WebRequest `
  -Uri "https://github.com/alencmanis/fasthook-cli/releases/latest/download/fasthook.exe" `
  -OutFile ".\fasthook.exe"

.\fasthook.exe --help

# Source build
git clone https://github.com/alencmanis/fasthook-cli.git
cd fasthook-cli
npm install
npm run build
npx . --help

# Authentication
fasthook login --api-key fhp_xxx
fasthook config --team tm_xxx
fasthook config --destination des_local_cli
fasthook auth me
fasthook config

Command Map

The current CLI maps resource actions directly to FastHook API routes. List and read commands pass non-reserved flags as query parameters. Write commands accept JSON through --json or --json-file and print the API response as formatted JSON.

Bulk operation commands use a sub-action. For example, fasthook events bulk-operations create maps to POST /events/bulk_operations, and fasthook events bulk-operations cancel bch_xxx maps to POST /events/bulk_operations/:id/cancel.

• sources update, destinations update, connections update, and transformations update use PUT on /:id.
• connections pause and unpause use PUT action endpoints.
• sources, destinations, and connections disable or enable use action endpoints.
• connections latest-input calls GET /connections/:id/latest-input.
• fasthook api accepts paths with or without the /v1 prefix because the CLI base URL already includes /v1.

fasthook sources <list|get|create|upsert|update|delete|enable|disable>
fasthook destinations <list|get|create|upsert|update|delete|enable|disable>
fasthook connections <list|get|create|upsert|update|delete|pause|unpause|enable|disable|latest-input>
fasthook transformations <list|get|create|upsert|update|delete|run|executions|execution>
fasthook requests <list|count|get|retry|events|ignored-events|bulk-operations>
fasthook events <list|count|get|retry|bulk-operations>
fasthook attempts <list|get>
fasthook metrics <requests|events>
fasthook project-secrets <get|update|rotate>
fasthook auth <me|logout>
fasthook api <method> <path> [--json '{...}' | --json-file file.json]

Manage Routes From JSON

For repeatable setup, keep one JSON file per resource type and run them in dependency order. Upsert the source first, then the destination, then the connection with the returned source_id and destination_id.

Store the returned ids in deploy output or environment files. Connection ids are opaque; demo data includes web_* style ids, and scripts should not assume a single prefix.

• source.json owns name, type, source auth, custom response, allowed methods, and disabled state.
• destination.json owns type HTTP or CLI, URL or path, HTTP method, auth, rate limit, and disabled state.
• connection.json owns source_id, destination_id, name, paused_at, disabled_at, and rules.
• FastHook normalizes connection rules in backend order: deduplicate, transform, filter, delay, retry.
• Use latest-input after test traffic to confirm the route source has usable input for transformation and debugging.

fasthook sources upsert --json-file source.json
fasthook destinations upsert --json-file destination.json
fasthook connections upsert --json-file connection.json

fasthook connections list --source_id src_xxx --limit 20
fasthook connections get web_xxx
fasthook connections latest-input web_xxx

Update Semantics

Use the wrapper command when the JSON file is the shape you intend to send to that API route. The CLI resource update commands currently use PUT /resource/:id. When you want a focused PATCH, use the raw api fallback explicitly.

This matters for destinations and connections because partial config edits and full replacement have different operational risk. In CI, prefer files that represent the complete desired state, then inspect the response that FastHook returns.

• Use pause for temporary receiver maintenance when held events should be released later.
• Use disable when future accepted requests should stop creating this branch.
• Use delete only when the route configuration should be removed.
• Inspect the returned paused_at, disabled_at, source_id, destination_id, and rules after every update.
• Prefer json-file in CI so complex rule arrays are reviewed in source control.

# Full update through the wrapper.
fasthook connections update web_xxx --json-file connection.json

# Focused API patch when only one field should change.
fasthook api PATCH /connections/web_xxx --json '{ "paused_at": "2026-05-29T18:00:00.000Z" }'

# Restore normal delivery.
fasthook connections unpause web_xxx

# Destination PATCH for partial config changes.
fasthook api PATCH /destinations/des_xxx --json-file destination-patch.json

Inspect A Connection From CLI

CLI inspection should follow the same evidence ladder as the dashboard: request, event, attempt, then metrics. The CLI does not hide API casing, so use accepted or rejected for request status and uppercase values such as FAILED or HOLD for event status.

• Use requests list to prove provider ingress and source auth result.
• Use requests events to see the delivery branches created by one request.
• Use requests ignored-events when events_count is zero or a branch was filtered or deduplicated.
• Use attempts list to read receiver response_status, body, trigger, requested_url, and latency.
• Use metrics events to identify the time window before creating retry filters.

fasthook requests list --source_id src_xxx --status accepted --include data --limit 20
fasthook requests events req_xxx
fasthook requests ignored-events req_xxx

fasthook events list --connection_id web_xxx --status FAILED --limit 20
fasthook attempts list --event_id evt_xxx --order_by created_at --dir desc --limit 100

fasthook metrics events \
  --from 2026-05-29T10:00:00Z \
  --to 2026-05-29T10:30:00Z \
  --granularity 1m \
  --connection_id web_xxx \
  --measures[] failed_count

Local CLI Destination Branches

A CLI destination is still a FastHook destination. It has a destination id, type CLI, method, optional path, rate limit, disabled state, and normal event/attempt evidence. The only runtime-only part is the local target selected by fasthook tunnel.

Use this page for connection management; use the CLI & Tunneling doc when you need full tunnel setup, local receiver verification, path joining, reconnect behavior, and troubleshooting.

• Do not put localhost in the destination config.
• Set destination path only when the local app expects a route.
• Keep local developer branches paused or disabled when no tunnel is connected.
• Retrying an event while the tunnel is connected can send old traffic into the local app.
• The event attempt still records the local response returned through the tunnel.

# Create the CLI destination from dashboard or API.
fasthook destinations create --json '{
  "name": "local-billing-api",
  "type": "CLI",
  "config": {
    "path": "/webhooks/orders",
    "http_method": "POST",
    "rate_limit": 20,
    "rate_limit_period": "minute"
  }
}'

# Connect a source to the CLI destination.
fasthook connections upsert --json-file local-connection.json

# Runtime-only localhost target.
fasthook tunnel --destination des_local_cli --to http://localhost:8080

Incident Runbooks

During incidents, use the CLI to narrow before changing state. Start with metrics and failed event lists, inspect one event's attempts, pause only the affected connection if the receiver is unhealthy, then test a single retry before bulk recovery.

Bulk retry JSON should be copied from the same proven filters used for metrics and list commands. Include from, to, status, source_id, connection_id, destination_id, and optional q.

• Pause holds delivery for one connection branch while the receiver is unhealthy.
• Event retry targets one existing destination branch.
• Request retry replays the inbound request through current routing and can create new branches.
• Bulk operations expose total_count, queued_count, done_count, failed_count, status, and cancelable.
• Cancel bulk work when the filter is too broad or the receiver starts failing again.

fasthook metrics events --from 2026-05-29T10:00:00Z --to 2026-05-29T10:30:00Z --granularity 1m --connection_id web_xxx --measures[] failed_count
fasthook events list --connection_id web_xxx --status FAILED --limit 20
fasthook attempts list --event_id evt_xxx --order_by created_at --dir desc

fasthook connections pause web_xxx
fasthook events retry evt_xxx

fasthook events bulk-operations create --json-file event-bulk-retry.json
fasthook events bulk-operations list --bucket ongoing --limit 20
fasthook events bulk-operations cancel bch_xxx

Automation Checklist

• The terminal or CI job sets FASTHOOK_API_KEY and FASTHOOK_TEAM_ID, or uses a dedicated FASTHOOK_CONFIG path.
• Project API keys are stored in secret storage and never printed in logs.
• Route JSON files are environment-specific and do not contain provider production secrets in staging files.
• Scripts store returned source, destination, and connection ids.
• Wrapper update commands are treated as PUT-style updates; focused PATCH uses fasthook api PATCH.
• Request status filters use accepted or rejected.
• Event status filters use uppercase delivery statuses.
• Bulk retry JSON is built from a tested list query and includes a cancel path.
• Local CLI destination branches are paused or disabled when no developer is running a tunnel.

Next

• CLI and tunneling
• Test webhooks locally
• Connections guide
• API automation