# 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.

**Available through**

The CLI wraps common public route families and public ingest sends. It is the safest default for shell automation.

| Surface | Status | Notes |
| --- | --- | --- |
| [CLI](/docs/agents.md) | Preferred | Use --json for automation, page with limit/cursor, mutate one target, then re-read state. |
| [Public API](/docs/api-reference.md) | Available | Use raw HTTP for documented public route families the CLI does not wrap. |
| [Dashboard](/docs/dashboard.md) | Not applicable | The CLI does not automate browser-only dashboard workflows. |
| [TypeScript SDK](/docs/sdks.md) | Available | Use the SDK instead when the workflow runs inside application code. |

## Install and login

**Install the CLI**

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

**Login with a profile**

```bash
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

**Profiles and current project**

```bash
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
```

**Webhook inventory and lifecycle**

```bash
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
```

**Schedules**

```bash
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
```

**Deliveries, replay jobs, and DLQ**

```bash
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
```

**Public ingest sends**

```bash
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](/docs/agents.md). 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](/docs/api-reference.md) lists them as customer-facing routes. The [raw HTTP examples](/docs/raw-http-examples.md) 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.