Owl Bound/CLI ReferenceAPI docs

Developer tools

Owlbound CLI

Use the CLI to validate plays, inspect stuck enrollments, audit connector readiness, discover node contracts, and run real live tests against production data when explicitly confirmed.

Commands using --confirm RUN_REAL_ACTIONS can call connected providers such as HubSpot, Slack, Salesforce, Google Chat, and webhooks. Run previews first when testing backfills.
Mature play QA means: source discovery, validation, connector readiness, live test with a real sample, step-result audit, then backfill. Platform reports include recent source patterns, play health, connector blockers, and backfill previews. A trusted live test should show a result, provider status, or provider error for every connector action; empty connector results should be treated as a product bug.

Install

Run from this repo with `bun run owl ...`.

Auth

Internal ops use Convex CLI credentials; API and agent calls should use environment variables for secrets.

Output

Add `--json` for machine-readable output.

API

Use `/api/v1/capabilities` for public scopes and credit costs.

Reports

Generate a GTM ops report across agent capabilities, connector coverage, source patterns, play health, and backfill readiness.

bun owl report platform --prod --json
bun owl report platform --workspace <workspaceId> --play <playId-or-name> --source website_visitors --prod --json

Plays

Inspect, validate, live-test, and backfill GTM plays from the terminal.

bun owl plays list --workspace <workspaceId> --prod
bun owl plays inspect --workspace <workspaceId> --play <playId-or-name> --prod
bun owl plays validate --workspace <workspaceId> --play <playId-or-name> --prod
bun owl plays maturity-audit --workspace <workspaceId> --play <playId-or-name> --prod
bun owl plays health --workspace <workspaceId> --play <playId-or-name> --prod
bun owl plays enrollments --workspace <workspaceId> --play <playId-or-name> --status active --prod
bun owl plays live-test --workspace <workspaceId> --play <playId-or-name> --source website_visitors --confirm RUN_REAL_ACTIONS --prod
bun owl plays replay-enrollment --workspace <workspaceId> --enrollment <enrollmentId> --confirm RUN_REAL_ACTIONS --prod
bun owl plays cancel-enrollment --workspace <workspaceId> --enrollment <enrollmentId> --confirm CANCEL_ENROLLMENT --prod

Agent

Compare dashboard-agent capabilities with Play node contracts and optionally ask the real agent through the dashboard API.

bun owl agent capabilities --category plays --json
bun owl agent tools --json
OWL_AGENT_COOKIE="<browser auth cookie>" bun owl agent ask --base-url https://app.owlbound.ai --workspace <workspaceId> --prompt "How would you build and test this play?"

Backfills

Preview matching records before queuing real work. Start commands can call providers.

bun owl plays backfill-preview --workspace <workspaceId> --play <playId-or-name> --source website_visitors --prod
bun owl plays backfill-status --workspace <workspaceId> --play <playId-or-name> --prod
bun owl plays backfill-start --workspace <workspaceId> --play <playId-or-name> --confirm RUN_REAL_ACTIONS --prod

Nodes

Discover the node contract registry: inputs, outputs, connector needs, test behavior, and common errors.

bun owl nodes list --prod
bun owl nodes list --category action --connector hubspot --prod
bun owl nodes list --query segment --prod
bun owl nodes describe --type hs_add_to_segment --prod

Connectors

Audit configured workspace connectors and browse the integration catalog.

bun owl connectors catalog --prod
bun owl connectors catalog --category crm --prod
bun owl connectors list --workspace <workspaceId> --prod
bun owl connectors list --workspace <workspaceId> --provider hubspot --prod
bun owl connectors test --workspace <workspaceId> --provider hubspot --prod

Contacts

Inspect recent API contact sources and send a real contact through the public API trigger path.

bun owl contacts sources --workspace <workspaceId> --prod
OWL_API_KEY=<key> bun owl contacts create --base-url https://app.owlbound.ai --email ada@example.com --source website_visitors

Replies

Audit replied contacts, message bodies, prior outbound context, sender identity, and sequence attribution across workspace messaging accounts.

bun owl replies list --workspace <workspaceId> --limit 100 --prod
bun owl replies audit --workspace <workspaceId> --limit 30 --prod --json
bun owl replies export --workspace <workspaceId> --limit 500 --prod > replies.csv

Webhooks

Generate copy-ready payloads for API Contact Created triggers before configuring external tools.

bun owl webhooks payload --workspace <workspaceId> --play <playId-or-name> --source website_visitors --prod

Recommended Workflow

  1. Start with maturity audit, node contracts, and agent capabilities.
  2. Compare the agent answer with what validation/runtime can execute.
  3. Use connector catalog/list/test commands to confirm readiness.
  4. Use a representative trigger sample before live testing.
  5. Run live tests on selected samples and inspect Records step results. Connector actions should show trusted status, provider status, provider success IDs, or provider errors, never a blank result.
  6. Preview backfills before starting real provider writes. Review source patterns, connector readiness, sample contacts, and estimated action calls before queuing matching records.
  7. Check duplicate trigger criteria before deploying multi-trigger plays so the same feed does not enroll records twice.
  8. Replay failed enrollments or cancel stuck ones only after inspecting their last step.