> ## Documentation Index
> Fetch the complete documentation index at: https://developer.firstsales.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Commands

> CLI command groups and global flags.

## Global flags

| Flag | Purpose |
| - | - |
| `--api-key` | Use a specific Developer API key. |
| `--base-url` | Override the API base URL. |
| `--profile` | Select a saved API-key profile. |
| `--org` | Target an organization. |
| `--workspace` | Target a workspace. |
| `--output` | Emit `json`, `table`, or `tsv` output. |
| `--json` | Emit compact JSON. |
| `--pretty` | Emit formatted JSON. |
| `--data` | Provide a JSON request body. |
| `--data-file` | Load a JSON request body from disk. |
| `--idempotency-key` | Add an idempotency key for retryable mutations. |
| `--page` | Select a page for supported list commands. |
| `--limit` | Bound the page size for supported list commands. |
| `--all` | Auto-paginate and concatenate supported list commands. |
| `--query` | Add a query string to the raw `api` command. |
| `--days` | Set the `usage get` window from 1 to 90 days (default: 7). |
| `--dry-run` | Print the request that would be sent, and send nothing. |
| `--confirm` | Required for destructive commands. |

## Command groups

The CLI registry is committed at `data/cli-commands.json` and is used to keep docs aligned with implementation.

Launch groups include:

* `whoami`, `doctor`
* `orgs`, `organizations`, `workspaces`
* `campaigns`
* `contacts`, `contact-lists`, `contact-tags`, `contact-imports`, `contact-exports`, `contact-fields`
* `deals`, `pipelines`
* `companies`
* `activities`
* `inbox`
* `connectors`
* `kb`
* `offerings`
* `tracking-domains`
* `email-auth`
* `sequences`
* `learning`
* `alerts`
* `warmup`
* `billing`
* `members`, `invitations`, `groups`, `domains`
* `api-keys`
* `teams`, `usage`, `dashboard`
* `copilot`

## Dry run

`--dry-run` works on named commands and on the raw `api` command. The CLI prints the
request and exits without making any network call. No API key is needed for a dry run.

```bash theme={null}
firstsales api POST /api/v1/organizations/org_123/workspaces/ws_123/contact-lists \
  --data '{"name":"Q4 prospects"}' --dry-run --json
```

```json theme={null}
{"dryRun":{"method":"POST","url":"https://api.app.firstsales.io/api/v1/organizations/org_123/workspaces/ws_123/contact-lists","headers":{"accept":"application/json","authorization":"Bearer fs-key-xxxxxxxx…[redacted]","user-agent":"@firstsales.io/cli/0.1.15","content-type":"application/json"},"body":{"name":"Q4 prospects"}}}
```

The `authorization` header keeps only the public `fs-key-` prefix of the key. Any other
key value shows `[redacted]`, and a missing key shows `[missing]`. The raw key is never
printed.

## Headless data commands

Available in `0.1.8`:

| Command | Route |
| - | - |
| `campaigns workflow get` | `GET .../campaigns/{campaignId}/workflow` |
| `campaigns workflow update` | `PATCH .../campaigns/{campaignId}/workflow` |
| `blocked-domains list\|add\|remove` | `.../blocked-domains`, or the campaign routes with `--campaign` |
| `tracking-domains get` | `GET .../tracking-domains/{domain}` |
| `suppression check` | `POST .../suppression/check` |
| `companies import` | `POST .../companies/imports` |
| `email-auth verify` | `POST .../email-auth/verify` |
| `connectors create cal-com` | `POST .../connectors/cal-com` |
| `emails draft\|send\|schedule` | `POST .../contacts/{contactId}/emails` |
| `emails get\|update` | `GET` or `PATCH .../contacts/{contactId}/emails/{emailId}` |
| `emails cancel\|approve` | `POST .../contacts/{contactId}/emails/{emailId}/cancel` or `/approve` |

```bash theme={null}
firstsales campaigns workflow update --org org_123 --workspace ws_123 --campaign cmp_123 \
  --include-list list_1 --include-list list_2 --sender conn_1
firstsales blocked-domains add --org org_123 --workspace ws_123 \
  --idempotency-key block-example-1 --data '{"domains":["example.com"]}'
```

* `--include-list` and `--sender` repeat. Mixing them with `--data` fails with
  `ambiguous_body`.
* A path value of `.` or `..` fails with `invalid_flag_value` (exit code 2).

The routes, scopes and error codes for these commands are on
[Headless operations](/docs/headless-operations). `connectors create cal-com` reads the
Cal.com key only from `FIRSTSALES_CAL_COM_API_KEY`; passing it as a flag fails.

## Examples

```bash theme={null}
firstsales campaigns list --org org_123 --workspace ws_123 --json
firstsales campaigns start --org org_123 --workspace ws_123 --campaign campaign_123 --data '{"savedVersionId":"sv_123","readinessVersion":"rv_123","idempotencyKey":"launch_123","confirmation":{"token":"confirm_123"}}' --json
firstsales contacts create --org org_123 --workspace ws_123 --data '{"email":"alex@example.com"}' --idempotency-key import-row-001
firstsales contacts delete --org org_123 --workspace ws_123 --contact contact_123 --confirm
firstsales deals create --org org_123 --workspace ws_123 --data '{"title":"Acme renewal","value":12000}'
firstsales companies merge --org org_123 --workspace ws_123 --data '{"survivorId":"company_1","mergeIds":["company_2"]}'
firstsales usage get --org org_123 --days 30 --json
firstsales copilot sessions-list --org org_123 --workspace ws_123 --json
```

## Campaign activation

Version `0.1.10` adds the following campaign controls. They require the accompanying public API deployment; publishing the CLI alone does not make these routes available.

| Command | Purpose |
| - | - |
| `campaigns readiness` | Read the saved campaign's current readiness. |
| `campaigns prepare-test-email` | Prepare a preview and confirmation for a verified workspace member. |
| `campaigns send-test-email` | Send the confirmed test with an explicit body idempotency key. |
| `campaigns prepare-launch` | Prepare the native launch confirmation from current saved and readiness versions. |

Each command requires `--org`, `--workspace`, and `--campaign`. The three preparation/send commands require a JSON body. Use `--data-file` to preserve the exact server-issued versions and confirmation instead of reconstructing them.

```bash theme={null}
firstsales campaigns readiness --org ORG_ID --workspace WS_ID --campaign CAMPAIGN_ID --json
firstsales campaigns prepare-test-email --org ORG_ID --workspace WS_ID --campaign CAMPAIGN_ID \
  --data-file prepare-test.json --dry-run --json
```

Test preparation requires `connectorId`, `savedCampaignVersion`, and `readinessVersion`, with an optional `recipientMemberId`. The recipient must be a verified workspace member; arbitrary recipient email addresses are not accepted. Test sending also requires a body `idempotencyKey` and the exact `confirmation` returned by preparation. The global idempotency header does not replace that body field.

Launch preparation requires `savedVersionId` and `readinessVersion`. Preparation does not launch the campaign: the existing `campaigns start` command consumes the server-issued confirmation. Readiness, sender eligibility, audience, schedule and durable receipt checks remain authoritative on the server.

The [canonical CLI release contract](https://github.com/firstsalesio/firstsales-cli/blob/main/release/firstsales-public-v1.cli-publish-contract.json) owns the complete command registry. These API/CLI additions do not imply new Product MCP activation tools. CLI account acquisition through GitHub, Google or email remains pending; existing CLI profiles use Developer API keys. Account login is separate from connecting an email sender or another Connector.

## Testimonials and inbox assistance

Version `0.1.11` adds five commands, bringing the CLI to 159 commands. All require
`--org` and `--workspace`; the API deployment controls route availability.

| Command | Required inputs | Purpose |
| - | - | - |
| `testimonials list` | `--campaign` | List campaign testimonials. |
| `testimonials add` | `--campaign`, JSON body | Add a campaign testimonial. |
| `testimonials update` | `--campaign`, `--testimonial`, JSON body | Update a testimonial. |
| `inbox score` | JSON body | Score inbox writing. |
| `inbox ai-draft` | JSON body | Request an assisted draft. |

Use `--data-file` for JSON bodies. Scoring and drafting do not send an email.
Inspect requests without making network calls:

```bash theme={null}
firstsales testimonials list --org ORG_ID --workspace WS_ID --campaign CAMPAIGN_ID --dry-run --json
firstsales inbox score --org ORG_ID --workspace WS_ID --data-file score.json --dry-run --json
```

Install the published version with `npm install -g @firstsales.io/cli@0.1.15`.

## Signals, changelog and inbox templates

Version `0.1.12` adds 18 commands, bringing the CLI to 177 commands. All require
`--org` and `--workspace`; the API deployment controls route availability.

| Command | Required inputs | Purpose |
| - | - | - |
| `signals list` | — | List the workspace's signals. |
| `signals create` | JSON body | Create a signal. |
| `signals update` | `--signal`, JSON body | Update a signal. |
| `signals delete` | `--signal` | Delete a signal. |
| `signals run` | `--signal` | Run a signal scan now. |
| `signals analytics` | `--signal` | Read signal analytics. Optional `--range`. |
| `signals leads` | — | List signal leads. Filters: `--signal-id`, `--target`, `--engagement`, `--min-score`, `--q`, `--from`, `--to`, `--sort`, `--limit`, `--offset`, `--before`. |
| `signals export` | — | Export signal leads with the same filters as `signals leads`, without paging. |
| `changelog whats-new` | — | Read unread product updates. `--all` includes read entries. |
| `changelog read` | JSON body | Mark changelog entries as read. |
| `changelog react` | `--slug`, JSON body | React to a changelog entry. |
| `changelog feedback` | `--slug`, JSON body | Send feedback on a changelog entry. |
| `inbox snooze` | `--thread`, JSON body | Snooze an inbox thread. |
| `inbox templates` | — | List reply templates. |
| `inbox template-create` | JSON body | Create a reply template. |
| `inbox template-update` | `--template`, JSON body | Update a reply template. |
| `inbox template-delete` | `--template` | Delete a reply template. |
| `emails compose` | JSON body | Compose a Direct Email. |

`alerts list` also accepts `--category`, `--severity`, `--status`, `--limit` and `--skip`.

Inspect requests without making network calls:

```bash theme={null}
firstsales signals leads --org ORG_ID --workspace WS_ID --min-score 70 --sort score --dry-run --json
firstsales changelog whats-new --org ORG_ID --workspace WS_ID --dry-run --json
```

## Meetings

Version `0.1.15` adds 26 `meetings` commands, bringing the CLI to 203 commands. All require
`--org` and `--workspace`; the API deployment controls route availability. Write commands take
`--data` or `--data-file`.

> [!NOTE]
>
> Meetings is in early access. For an account without it, these commands return `403` with the
> message `Meetings is coming soon`.

| Command | Required inputs | Purpose |
| - | - | - |
| `meetings bookings` | — | List bookings. Filters: `--status`, `--from`, `--to`. |
| `meetings booking-action` | `--booking`, JSON body | Act on a booking. |
| `meetings event-types` | — | List event types. |
| `meetings event-type-update` | `--event-type`, JSON body | Update an event type. |
| `meetings private-link` | `--event-type`, JSON body | Create a private booking link. |
| `meetings slots` | `--event-type` | List open slots. Filters: `--from`, `--to`, `--duration`. |
| `meetings deliveries` | — | List deliveries. |
| `meetings replay` | `--delivery` | Replay a delivery. |
| `meetings insights` | — | Read booking insights. Filters: `--from`, `--to`, `--host-user-id`, `--event-type-id`, `--status`. |
| `meetings export` | — | Export insights with the same filters as `meetings insights`. |
| `meetings route` | `--form`, JSON body | Run a routing form. |
| `meetings schedule-update` | `--schedule`, JSON body | Update an availability schedule. |
| `meetings settings` | — | Read meeting settings. |
| `meetings settings-update` | JSON body | Update meeting settings. |
| `meetings webhook-update` | `--endpoint`, JSON body | Update a webhook endpoint. |
| `meetings workflows` | — | List workflows. |
| `meetings workflow-update` | `--workflow`, JSON body | Update a workflow. |
| `meetings series-create` | JSON body | Create an event series. |
| `meetings series-update` | `--series`, JSON body | Update an event series. |
| `meetings roster` | `--series` | Read a series roster. Optional `--occurrence-key`. |
| `meetings seat-register` | `--series`, JSON body | Register a seat. |
| `meetings instant-readiness` | `--series`, JSON body | Check instant readiness for a series. |
| `meetings seat-accept` | `--registration`, JSON body | Accept a seat. |
| `meetings seat-decide` | `--registration`, JSON body | Approve or decline a seat. |
| `meetings seat-release` | `--registration` | Release a seat. Needs `--confirm`. |

Inspect requests without making network calls:

```bash theme={null}
firstsales meetings slots --org ORG_ID --workspace WS_ID --event-type EVENT_TYPE_ID --from 2026-10-20 --to 2026-10-21 --dry-run --json
firstsales meetings bookings --org ORG_ID --workspace WS_ID --from 2026-10-20 --to 2026-10-27 --dry-run --json
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.