AI Agents

If you are operating Hooksbase from a coding agent, terminal automation, or LLM-driven workflow, start with the CLI. It is the most stable public surface for non-browser automation because it gives you predictable JSON output, profile management, and a narrower operational contract than scraping the dashboard.

Why agents should start with the CLI

The CLI is the default control plane for external agents because it already solves three problems that agents otherwise have to reinvent:

• credential resolution through profiles, environment variables, or explicit flags
• stable machine-readable output through --json
• version-matched local guidance through hooksbase skills get hooksbase
• common operator actions such as webhook listing, delivery inspection, replay, DLQ export, Automation inspection, Code Mode versioning, schedule lifecycle, event drains, operator alerting, file downloads, and ingest send

Use the TypeScript SDK when you are embedding Hooksbase inside your own Node.js or TypeScript runtime. Use the CLI when the agent is orchestrating shell commands, scripts, or local terminal workflows.

Automations in agent flows

Automations let you keep event-shaping logic in Hooksbase instead of pushing it into every agent runtime. The common pattern is: ingest provider events, route on the original payload, run a versioned Code Mode transform, then deliver the persisted dispatch snapshot to the agent.

Use Automations when an agent needs:

• one normalized event envelope across providers
• sensitive field removal before the agent sees the payload
• versioned delivery-path logic with test runs and logs
• bounded run exports for operational review

hooksbase automations list --webhook wh_123 --json
hooksbase automations versions list auto_123 --json
hooksbase automations runs list --automation auto_123 --limit 20 --json
hooksbase automations runs get run_123 --json

Auth model

Recommended agent loop

Load the local skill content first:

hooksbase skills get hooksbase
hooksbase skills get webhook-ops
hooksbase skills get automations

For most agent workflows, use this sequence:

1. Validate credentials and discover the current profile state.
2. Read the current project and webhook inventory.
3. Inspect deliveries, replay jobs, or DLQ rows one page at a time.
4. Execute one explicit mutation such as replay, re-drive, schedule create, or ingest send.
5. Re-read the mutated surface and stop.

That pattern keeps the agent grounded in server truth and avoids wide, unbounded crawls.

hooksbase auth profiles --validate --json
hooksbase projects get --json
hooksbase webhooks list --limit 20 --json
hooksbase deliveries list --limit 20 --json

Core command patterns

Use these patterns as the defaults for terminal agents:

hooksbase projects get --json
hooksbase templates list --json
hooksbase webhooks get wh_123 --json
hooksbase deliveries get del_123 --json
hooksbase dlq get dlq_123 --json
hooksbase usage show --from 1740000000000 --to 1740086400000 --json

hooksbase deliveries replay del_123 --json
hooksbase dlq redrive dlq_123 --json
hooksbase schedules create wh_123 --file ./schedule.json --json
hooksbase automations test auto_123 --payload ./payload.json --json
hooksbase webhooks rotate-signing-secret wh_123 --json
hooksbase ingest send --ingest-url https://hooks.hooksbase.com/v1/ingest/hook_123 --ingest-secret whsec_... --file ./payload.json --json
hooksbase ingest send --webhook-name orders --ingest-secret whsec_... --file ./payload.json --json

Operational guidance:

• prefer --json for every agent-invoked command
• use --limit and --cursor instead of assuming full collection reads
• use the CLI for explicit remote state changes, not inferred local bookkeeping
• use idempotency keys on ingest sends whenever the agent may retry
• prefer --webhook-name when the agent already has project API key access and should resolve the current ingest URL automatically
• stop after one mutation unless the user explicitly asks for a broader batch
• re-read the same webhook, delivery, schedule, DLQ entry, or operation job before deciding whether the mutation worked

When to fall back to raw HTTP

Use raw HTTP when the agent needs a browser/raw surface or a language/runtime where the TypeScript SDK and CLI are not appropriate. Form ingest is the main browser/raw public workflow:

• render or submit /v1/form/{publicId}
• inspect the cURL-level contract for routes that also have package wrappers

Use the dashboard when the agent request touches browser-only product workflows:

• project creation or deletion
• team membership and invitations
• billing checkout or provider management
• onboarding wizard state and validation

That separation is intentional. Raw HTTP and the CLI are public automation surfaces; the dashboard is a product UI for signed-in humans.

Common mistakes

• Scraping the dashboard instead of using the CLI or raw HTTP.
• Running list commands without --json and then trying to parse table output.
• Giving the agent a write key and expecting admin-only project reads to work.
• Letting the agent perform broad destructive actions without first re-reading the target resource.
• Falling back to undocumented browser routes for dashboard-only workflows.