Skip to content

OutboundSync CLI

Install the OutboundSync CLI from npm, authenticate with an API key, and run API v1 commands for syncs, sources, block lists, and webhooks.

When to use this guide: You want to check readiness, inspect syncs, retry errors, or manage webhooks from a terminal, a shell script, or a CI job, without writing REST calls by hand.

outboundsync is the command-line interface for the OutboundSync API v1. It covers the same surface as the OutboundSync MCP: account readiness, sources, syncs, destinations, block lists, webhooks, events, and prior outreach. Each command calls one API route with your API key and prints JSON, so its output pipes straight into jq, a log, or an agent.

The CLI is in Beta. It’s open source (outboundsync/outboundsync-cli) and published to npm as outboundsync. The command reference below is generated from the CLI’s own command registry, so it always matches the published package.

The CLI needs Node.js 20 or newer and has no runtime dependencies.

Terminal window
npm i -g outboundsync
outboundsync --help

Or run it without installing:

Terminal window
npx outboundsync --help

outboundsync with no arguments prints every command. outboundsync <group> lists one group, and outboundsync <command> --help shows that command’s flags.

The CLI uses the same API keys as REST and MCP. Create a key under Platform access → API keys (it starts with osapi_), then export it:

Terminal window
export OUTBOUNDSYNC_API_KEY=osapi_your_key_here
outboundsync me

outboundsync me shows the key’s scopes and whether it’s account-wide or scoped to one CRM connection. There’s no login command, and the CLI never stores or prints the key.

  • --token <key> overrides the variable for one command, but a flag value shows up in shell history and the process list. Prefer the variable.
  • Write scope. Keys created in the dashboard are read-only. Write commands need a key with the write scope; ask OutboundSync support for one. See Scopes.
  • Account-wide keys for webhooks. webhooks commands need an account-wide key, and webhooks and events commands need Sync Monitoring webhooks on your plan.
  • Base URL. Requests go to https://app.outboundsync.com/api/v1. OUTBOUNDSYNC_API_BASE_URL or --base-url overrides it; the CLI accepts only https and doesn’t follow redirects, so the key is only ever sent to that base URL.

Every command that changes something exits with code 1, without calling the API, unless you pass --yes, and says what it would have done. Confirm the target first, then add the flag:

Terminal window
outboundsync syncs get 1001
outboundsync syncs retry 1001 --yes
  • outboundsync syncs retry re-queues one failed HubSpot or Salesforce sync. outboundsync sources retry-syncs re-queues every recorded error from the last 30 days for one source, once per source per 24 hours, so retry one sync first to check the fix.
  • outboundsync destinations replay and outboundsync webhooks replay queue a delivery to be sent to its URL again; the API answers before the re-send happens.
  • outboundsync blocklists pause stops fetching and pushing a list. outboundsync blocklists resync turns it back on and queues a full reload from the CRM.
  • outboundsync webhooks delete is a soft delete the API can’t undo. outboundsync webhooks rotate-secret stops the old secret verifying at once.

outboundsync webhooks create and outboundsync webhooks rotate-secret print the oswhsec_… signing secret once. Store it then: a later read doesn’t return it.

Range commands take --from and --to as full ISO-8601 timestamps with a timezone offset (2026-08-01T00:00:00Z), or --since 24h|7d|30d, which ends at now. A range can span at most 31 days, the same as the API.

List commands accept --cursor and --limit. --all follows nextCursor until the API reports no more pages, up to 200 pages (--max-pages raises the cap); with --json it prints one JSON object per line.

Terminal window
outboundsync account status
outboundsync syncs list --since 24h --status error --connection-id 7
outboundsync destinations deliveries 3 --since 7d --status error --all --json
outboundsync contacts outreach --file contacts.csv --json > outreach.jsonl

Success prints pretty JSON on stdout; --json prints compact JSON with no summary line. Errors go to stderr, and the exit code says what happened, so scripts can branch on it:

Code Meaning
0 Success
1 Usage or validation error, including a missing --yes
2 Unauthorized (401): the key is missing, invalid, or revoked
3 Forbidden (403): no write scope, a connection-scoped key on a webhook command, or a plan feature that isn’t on
4 Rate limited (429)
5 Server error (5xx), timeout, network error, or a response that wasn’t JSON
6 Any other HTTP status, including 400, 404, and 409

The CLI retries a 429 once when Retry-After fits in 30 seconds, and a failed read once after a 5xx other than 504. It never retries a write. All keys on an account share 120 requests per 60 seconds, and outboundsync contacts outreach has its own 600 per 60 seconds. See Errors and rate limits.

Surface Best for
CLI (this page) Terminals, shell scripts, cron and CI jobs, and agents that run shell commands
MCP Coding agents calling OutboundSync tools directly from Cursor, Claude Code, or Codex
API Your own code, low-code HTTP modules, and anything that speaks REST
Agent Skills Guided workflows such as launch preflight and sync monitoring

All four use the same API keys and the same API v1 routes.

The CLI is built to be driven by coding agents and scripts, not just people at a terminal.

  • Start with outboundsync me. It tells the agent which scopes the key has and whether it’s account-wide, so it knows up front which commands will be allowed.
  • Parse --json and branch on the exit code. Output is plain JSON on stdout, errors go to stderr, and the exit codes separate a bad key (2), a missing scope (3), rate limits (4), and server trouble (5).
  • Confirm with the user before adding --yes. Run the command without it first: it exits 1 and says what it would change. Show that to the user, then re-run with --yes.
  • Pin a version for repeatable runs. npx outboundsync@<version> runs an exact release; npx outboundsync uses the latest.
  • Discover commands from data. Every release ships commands.json, the machine-readable version of the reference below (command, usage, flags, API route, and whether it writes). It’s also at commands.json on GitHub.

Every command, grouped by what it works on. Each API route links to its section in the API v1 reference, which documents fields, responses, and errors.

38 commands: 27 read, 11 write. Generated from theCLI's command registry, so it matches the published package.

Account, key, and setup

Count requests, syncs, and destination deliveries in a date range.

outboundsync account metrics (--from <iso> --to <iso> | --since 24h|7d|30d)

API route: GET /api/v1/account/metrics

Flags for outboundsync account metrics
FlagDescription
--connection-idCount one connection.
--source-idCount one source. Does not filter destination deliveries.
--fromRange start, ISO-8601 with a timezone offset.
--toRange end, ISO-8601 with a timezone offset.
--sinceRelative range: 24h, 7d, or 30d. Sets --to to now. Values: 24h, 7d, 30d.

Print the OpenAPI document. No API key required.

outboundsync openapi

API route: GET /api/v1/openapi.yaml

Flags for outboundsync openapi
FlagDescription
--formatDocument format. Default yaml. Values: yaml, json.

Prior outreach

Look up whether a contact was outreached. Pass --email, --profile-url, or --file.

outboundsync contacts outreach

API route: GET /api/v1/contacts/outreach

Flags for outboundsync contacts outreach
FlagDescription
--emailOne email address.
--profile-urlLinkedIn (/in/ or /pub/) or X profile URL. Repeat up to 5 times.
--fileJSONL or CSV file of contacts. Use - to read stdin.

Sources and inbound requests

List webhook requests received by one source.

outboundsync sources requests <sourceId> (--from <iso> --to <iso> | --since 24h|7d|30d)

API route: GET /api/v1/sources/{sourceId}/requests

Flags for outboundsync sources requests
FlagDescription
--fromRange start, ISO-8601 with a timezone offset.
--toRange end, ISO-8601 with a timezone offset.
--sinceRelative range: 24h, 7d, or 30d. Sets --to to now. Values: 24h, 7d, 30d.
--cursorPage cursor from a previous response.
--limitPage size. Default 100, max 500. Omitted unless you pass it.
--allFollow nextCursor until the server reports no more pages.
--max-pagesStop after this many pages. Default 200.

List CRM syncs for one source.

outboundsync sources syncs <sourceId> (--from <iso> --to <iso> | --since 24h|7d|30d)

API route: GET /api/v1/sources/{sourceId}/syncs

Flags for outboundsync sources syncs
FlagDescription
--statusFilter by sync status. Values: success, warning, error.
--connection-idFilter by connection.
--fromRange start, ISO-8601 with a timezone offset.
--toRange end, ISO-8601 with a timezone offset.
--sinceRelative range: 24h, 7d, or 30d. Sets --to to now. Values: 24h, 7d, 30d.
--cursorPage cursor from a previous response.
--limitPage size. Default 100, max 500. Omitted unless you pass it.
--allFollow nextCursor until the server reports no more pages.
--max-pagesStop after this many pages. Default 200.

List webhook requests in a date range.

outboundsync requests list (--from <iso> --to <iso> | --since 24h|7d|30d)

API route: GET /api/v1/requests

Flags for outboundsync requests list
FlagDescription
--source-idFilter by source.
--fromRange start, ISO-8601 with a timezone offset.
--toRange end, ISO-8601 with a timezone offset.
--sinceRelative range: 24h, 7d, or 30d. Sets --to to now. Values: 24h, 7d, 30d.
--cursorPage cursor from a previous response.
--limitPage size. Default 100, max 500. Omitted unless you pass it.
--allFollow nextCursor until the server reports no more pages.
--max-pagesStop after this many pages. Default 200.

Count webhook requests in a date range.

outboundsync requests metrics (--from <iso> --to <iso> | --since 24h|7d|30d)

API route: GET /api/v1/requests/metrics

Flags for outboundsync requests metrics
FlagDescription
--source-idCount one source.
--fromRange start, ISO-8601 with a timezone offset.
--toRange end, ISO-8601 with a timezone offset.
--sinceRelative range: 24h, 7d, or 30d. Sets --to to now. Values: 24h, 7d, 30d.

CRM syncs

List CRM syncs in a date range.

outboundsync syncs list (--from <iso> --to <iso> | --since 24h|7d|30d)

API route: GET /api/v1/syncs

Flags for outboundsync syncs list
FlagDescription
--statusFilter by sync status. Values: success, warning, error.
--source-idFilter by source.
--connection-idFilter by connection.
--fromRange start, ISO-8601 with a timezone offset.
--toRange end, ISO-8601 with a timezone offset.
--sinceRelative range: 24h, 7d, or 30d. Sets --to to now. Values: 24h, 7d, 30d.
--cursorPage cursor from a previous response.
--limitPage size. Default 100, max 500. Omitted unless you pass it.
--allFollow nextCursor until the server reports no more pages.
--max-pagesStop after this many pages. Default 200.

Count CRM syncs in a date range.

outboundsync syncs metrics (--from <iso> --to <iso> | --since 24h|7d|30d)

API route: GET /api/v1/syncs/metrics

Flags for outboundsync syncs metrics
FlagDescription
--source-idCount one source.
--connection-idCount one connection.
--fromRange start, ISO-8601 with a timezone offset.
--toRange end, ISO-8601 with a timezone offset.
--sinceRelative range: 24h, 7d, or 30d. Sets --to to now. Values: 24h, 7d, 30d.

outboundsync syncs retry

Write, needs --yesAPI key

Re-queue one failed HubSpot or Salesforce sync. Requires --yes and the write scope.

outboundsync syncs retry <id>

API route: POST /api/v1/syncs/{id}/retry

Flags for outboundsync syncs retry
FlagDescription
--yesrequiredConfirm this write.

Destinations and deliveries

List deliveries for one destination.

outboundsync destinations deliveries <id> (--from <iso> --to <iso> | --since 24h|7d|30d)

API route: GET /api/v1/destinations/{id}/deliveries

Flags for outboundsync destinations deliveries
FlagDescription
--statusFilter by delivery status. Values: success, error.
--fromRange start, ISO-8601 with a timezone offset.
--toRange end, ISO-8601 with a timezone offset.
--sinceRelative range: 24h, 7d, or 30d. Sets --to to now. Values: 24h, 7d, 30d.
--cursorPage cursor from a previous response.
--limitPage size. Default 100, max 500. Omitted unless you pass it.
--allFollow nextCursor until the server reports no more pages.
--max-pagesStop after this many pages. Default 200.

Count deliveries for one destination.

outboundsync destinations delivery-metrics <id> (--from <iso> --to <iso> | --since 24h|7d|30d)

API route: GET /api/v1/destinations/{id}/deliveries/metrics

Flags for outboundsync destinations delivery-metrics
FlagDescription
--fromRange start, ISO-8601 with a timezone offset.
--toRange end, ISO-8601 with a timezone offset.
--sinceRelative range: 24h, 7d, or 30d. Sets --to to now. Values: 24h, 7d, 30d.

List destination deliveries in a date range.

outboundsync deliveries list (--from <iso> --to <iso> | --since 24h|7d|30d)

API route: GET /api/v1/deliveries

Flags for outboundsync deliveries list
FlagDescription
--statusFilter by delivery status. Values: success, error.
--destination-idFilter by destination.
--fromRange start, ISO-8601 with a timezone offset.
--toRange end, ISO-8601 with a timezone offset.
--sinceRelative range: 24h, 7d, or 30d. Sets --to to now. Values: 24h, 7d, 30d.
--cursorPage cursor from a previous response.
--limitPage size. Default 100, max 500. Omitted unless you pass it.
--allFollow nextCursor until the server reports no more pages.
--max-pagesStop after this many pages. Default 200.

Block lists

Sync Monitoring webhooks and events

outboundsync webhooks create

Write, needs --yesAPI key

Create a platform webhook endpoint. The signing secret is printed once. Requires --yes, the write scope, and an account-scoped key.

outboundsync webhooks create

API route: POST /api/v1/webhooks

Flags for outboundsync webhooks create
FlagDescription
--urlrequiredhttps endpoint that will receive events.
--descriptionOptional label, at most 500 characters.
--eventEvent type to enable. Repeat to set the list. Omit to enable every event.
--yesrequiredConfirm this write.

outboundsync webhooks delete

Write, needs --yesAPI key

Soft-delete a platform webhook endpoint. Requires --yes, the write scope, and an account-scoped key.

outboundsync webhooks delete <id>

API route: DELETE /api/v1/webhooks/{id}

Flags for outboundsync webhooks delete
FlagDescription
--yesrequiredConfirm this write.

List delivery attempts for one platform webhook. Requires an account-scoped key.

outboundsync webhooks deliveries <id>

API route: GET /api/v1/webhooks/{id}/deliveries

Flags for outboundsync webhooks deliveries
FlagDescription
--statusFilter by delivery status. Values: PENDING, SUCCEEDED, FAILED, DEAD.
--cursorPage cursor from a previous response.
--limitPage size. Default 25, max 100. Omitted unless you pass it.
--allFollow nextCursor until the server reports no more pages.
--max-pagesStop after this many pages. Default 200.

outboundsync webhooks test

Write, needs --yesAPI key

Queue a test.ping delivery to one platform webhook. Requires --yes, the write scope, and an account-scoped key.

outboundsync webhooks test <id>

API route: POST /api/v1/webhooks/{id}/test

Flags for outboundsync webhooks test
FlagDescription
--yesrequiredConfirm this write.

outboundsync webhooks update

Write, needs --yesAPI key

Update a platform webhook endpoint. Pass at least one field. Requires --yes, the write scope, and an account-scoped key.

outboundsync webhooks update <id>

API route: PATCH /api/v1/webhooks/{id}

Flags for outboundsync webhooks update
FlagDescription
--urlReplacement https endpoint.
--descriptionReplacement label, at most 500 characters.
--eventReplacement event type. Repeat to replace the list.
--activetrue to enable the endpoint, false to disable it. Values: true, false.
--yesrequiredConfirm this write.

List platform events. Connection-scoped keys see their connection's events plus account-level events.

outboundsync events list

API route: GET /api/v1/events

Flags for outboundsync events list
FlagDescription
--typeEvent type. Repeat to include more than one.
--deliveredtrue for events with at least one successful delivery, false for the rest. Values: true, false.
--cursorPage cursor from a previous response.
--limitPage size. Default 25, max 100. Omitted unless you pass it.
--allFollow nextCursor until the server reports no more pages.
--max-pagesStop after this many pages. Default 200.