CLI

The Hooksbase CLI is the fastest way to work with project-authenticated Public API routes from a terminal. The installed executable name is hooksbase, and it stores reusable profiles so you do not have to pass the same base URL and project API key on every command.

Install and login

npm install --global @hooksbase/cli
hooksbase --help

hooksbase auth login \
  --base-url https://api.hooksbase.com \
  --api-key swk_...

--base-url and --api-key are optional — when running in a TTY, auth login prompts for any values you omit. Profiles are stored at $XDG_CONFIG_HOME/hooksbase/config.json (falling back to ~/.config/hooksbase/config.json) with file mode 0600.

The CLI also resolves credentials and target settings from the environment, which takes precedence over the stored profile:

• HOOKSBASE_PROFILE — named profile to load
• HOOKSBASE_BASE_URL — defaults to https://api.hooksbase.com
• HOOKSBASE_API_KEY — project API key (swk_...)

Auth model

The CLI accepts both admin and write project API keys:

• it validates the key against GET /v1/project when possible
• if that returns the admin-only 403, it falls back to GET /v1/webhooks?limit=1
• write-key profiles are stored without project metadata because that surface is unavailable

Common commands

hooksbase auth profiles --validate --json
hooksbase projects list           # local inventory of saved profiles
hooksbase projects get --json     # current project read (admin keys)
hooksbase templates list --json

hooksbase webhooks list --limit 20 --json
hooksbase webhooks get wh_123 --json
hooksbase webhooks create --file ./webhook.json
hooksbase webhooks pause wh_123
hooksbase webhooks resume wh_123
hooksbase webhooks archive wh_123
hooksbase webhooks restore wh_123
hooksbase webhooks destroy wh_123
hooksbase webhooks rotate-ingest-secret wh_123
hooksbase webhooks rotate-signing-secret wh_123
hooksbase webhooks secret-versions wh_123 --json

hooksbase schedules list wh_123 --json
hooksbase schedules create wh_123 --file ./schedule.json
hooksbase schedules pause wh_123 sch_456
hooksbase schedules resume wh_123 sch_456
hooksbase schedules delete wh_123 sch_456

hooksbase deliveries list --limit 20 --json
hooksbase deliveries get del_123
hooksbase deliveries replay del_123
hooksbase replay-jobs get replay_123
hooksbase dlq list --limit 20 --json
hooksbase dlq get dlq_123
hooksbase dlq redrive dlq_123
hooksbase dlq export --format ndjson
hooksbase usage show --from 1740000000000 --to 1740086400000 --json

hooksbase ingest send \
  --ingest-url https://hooks.hooksbase.com/v1/ingest/hook_123 \
  --ingest-secret whsec_... \
  --file ./payload.json \
  --idempotency-key quickstart-1
hooksbase ingest send \
  --webhook-name orders \
  --ingest-secret whsec_... \
  --file ./payload.json --json

List commands also accept --cursor for paging and common filters such as --status or --webhook-id. replay-jobs get and dlq get always output JSON.

The CLI favors:

• profile-based auth
• stable --json output for automation
• JSON-file input for create flows such as webhooks and schedules
• either direct ingest URLs or webhook-name lookup for ingest sends

AI and agent workflows

For terminal-first agents, the CLI is usually the best default Hooksbase surface:

• it gives agents stable --json output instead of scraping the dashboard
• it keeps auth explicit through stored profiles, --api-key, or environment variables
• it covers the operator loops agents reach for most often: list, inspect, replay, DLQ export, usage lookup, schedule management, and test ingest

Recommended agent pattern:

1. Validate or select a profile with hooksbase auth profiles --validate --json.
2. Read the current project with hooksbase projects get --json.
3. Enumerate webhooks, deliveries, or DLQ rows one page at a time with --limit, --cursor, and --json.
4. Use replay, DLQ re-drive, or ingest send as explicit actions, ideally with idempotency keys where the underlying route supports them.

If you are orchestrating coding agents or shell automations, start with AI agents. That page is the opinionated workflow guide for agent-safe CLI usage and when to fall back to raw HTTP.

Coverage and limits

The current CLI covers:

• auth and profile management (auth login, auth profiles)
• current-project inspection (projects get) and local profile inventory (projects list)
• webhook template catalog reads (templates list)
• webhook lifecycle — list, get, create, pause, resume, archive, restore, destroy
• secret rotation and version listing
• schedules — list, create, pause, resume, delete
• deliveries — list, get, replay
• replay jobs — get
• DLQ — list, get, redrive, export
• usage
• public ingest sends (direct URL or webhook-name lookup)

It does not yet wrap:

• HTTP pack catalog reads
• destinations
• routing
• transforms
• metrics or backlog
• email allowlists
• event drain management
• operator alerting
• file retrieval helpers
• bulk replay / bulk DLQ re-drive and bulk-operation polling

Use raw HTTP for the public route families above when the Public API reference lists them as customer-facing routes. The raw HTTP examples page covers the highest-friction gaps. Use the dashboard, not raw HTTP, for browser-only product workflows such as project creation, team invites, billing checkout, and onboarding.

Common mistakes

• Expecting projects list to query a remote project inventory. It is a local profile inventory command.
• Forgetting --json when you want stable automation output.
• Using outdated examples with old API-key or ingest-secret prefixes.
• Reaching for the CLI first on public routes it does not wrap yet, instead of falling back to documented raw HTTP.
• Passing both --ingest-url and --webhook-name to hooksbase ingest send. The command requires exactly one of them.
• Trying to use the CLI as a substitute for dashboard-only setup or billing flows.