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 skills get hooksbase

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_...)

Agent skills

hooksbase skills list
hooksbase skills get hooksbase
hooksbase skills get webhook-ops
hooksbase skills get automations
hooksbase skills path hooksbase

The CLI package includes version-matched skill content for AI agents and terminal automations. These commands do not require a profile or API key, so an agent can read the local guide before touching remote Hooksbase state. Use hooksbase skills get hooksbase --full when the agent needs bundled reference files as well as the core guide.

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 projects update --file ./project.json --json
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 webhooks deliveries wh_123 --limit 20 --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 automations list --webhook wh_123 --json
hooksbase automations create --webhook wh_123 --name "Normalize agent event" --json
hooksbase automations update auto_123 --file ./automation-patch.json --json
hooksbase automations versions list auto_123 --json
hooksbase automations versions create auto_123 --file ./transform.js --activate --json
hooksbase automations test auto_123 --payload ./payload.json --json
hooksbase automations bind wh_123 auto_123 --json
hooksbase automations runs get run_123 --json
hooksbase automations runs egress-events run_123 --json
hooksbase automations runs export --format jsonl --automation auto_123 --limit 100

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 ships version-matched skill guides through hooksbase skills
• 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 and update (projects get, projects update) and local profile inventory (projects list)
• webhook template and HTTP pack catalog reads (templates list, http-packs list)
• webhook lifecycle — list, get, create, update, pause, resume, archive, restore, destroy
• destinations, routing, transforms, test delivery, metrics, backlog, email allowlists, secret rotation, and version listing
• Automations — create, update, pause, resume, archive, versions, activate, test, bind, unbind, run list/get/logs/export, quotas, usage, templates, and Enterprise egress policy/credential management
• schedules — list, create, pause, resume, delete
• deliveries — project-wide list, per-webhook list, get, replay, replay-jobs, and bulk-replay
• replay jobs and bulk operations — get
• DLQ — list, get, redrive, export, bulk-redrive
• usage
• event drains
• operator webhooks, alert channels, alert rules, and operator incidents
• file downloads from signed URLs or retained delivery files
• public ingest sends (direct URL or webhook-name lookup)

Form ingest is browser/raw HTTP only; the CLI does not provide form-specific helpers. 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.
• Expecting form-ingest helpers. Use a browser form or direct raw HTTP for /v1/form/{publicId}.
• 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.