Commands - FirstSales Developer

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.

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

{"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.17","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`

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. connectors create cal-com reads the Cal.com key only from FIRSTSALES_CAL_COM_API_KEY; passing it as a flag fails.

Examples

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.

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 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:

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

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:

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.

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:

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

Fallback emails, Meetings payments and imports, and bulk approve

Version 0.1.16 adds 21 commands, bringing the CLI to 224 commands. Version 0.1.17 adds inbox bulk-approve, bringing it to 225. All require --org and --workspace. Write commands take --data or --data-file.

Command	Required inputs	Purpose
`fallback-emails list`	`--campaign`	List a campaign’s fallback emails.
`fallback-emails set`	`--campaign`, JSON body	Set a campaign’s fallback emails.
`fallback-emails update`	`--campaign`, `--follow-up-number`, JSON body	Update one fallback email.
`fallback-emails delete`	`--campaign`, `--follow-up-number`	Delete one fallback email. Needs `--confirm`.
`meetings merchant-connect`	—	Start a merchant handoff.
`meetings merchant-status`	`--handoff`	Read a merchant handoff.
`meetings payment-quote`	JSON body	Create a payment quote.
`meetings payment-approve`	`--quote`	Approve a payment quote.
`meetings payment-hold`	`--quote`	Hold a payment quote.
`meetings import-status`	—	Check a Cal.com import.
`meetings import-cta`	JSON body	Start a Cal.com import.
`meetings import-intake`	JSON body	Send Cal.com import details.
`meetings import-preview`	JSON body	Preview a Cal.com import.
`meetings import-run`	JSON body	Run a Cal.com import.
`inbox bulk-approve`	JSON body	Approve up to 200 pending drafts in one call.

0.1.16 also adds seven Meetings commands for routing forms, templates, schedules and the organization profile: meetings routing-form-publish, meetings schedules, meetings template-preview, meetings template-apply, meetings template-publish, meetings organization-profile and meetings organization-catalog.

firstsales inbox bulk-approve --org ORG_ID --workspace WS_ID --data '{"threadIds":["THREAD_ID"]}' --dry-run --json

Campaign email state

Version 0.1.18 adds campaigns email-state, bringing the CLI to 226 commands. It reads where one campaign email is in its life, so you can tell an email that is waiting for approval from one that is scheduled or sent. It requires --org, --workspace and --campaign-email.

firstsales campaigns email-state --org org_123 --workspace ws_123 --campaign-email em_123 --json

{"id":"em_123","campaignId":"cmp_123","status":"draft","lifecycleState":"awaiting-approval","awaitingApproval":true,"scheduledAt":null,"sentAt":null}

The command calls GET /api/v1/organizations/{organizationId}/workspaces/{workspaceId}/campaign-emails/{campaignEmailId}/state. scheduledAt and sentAt are null until the email is scheduled or sent.

Campaign email preview

Version 0.1.19 adds campaigns email-preview, bringing the CLI to 227 commands. It shows one campaign email as it will be sent: subject, body, sender and recipients, status, whether it waits for approval, lifecycle state, schedule and quality history. It requires --org, --workspace and --campaign-email.

firstsales campaigns email-preview --org org_123 --workspace ws_123 --campaign-email em_123 --json

{"subject":"Quick question","body":"<p>Hi Sam,</p>","textBody":"Hi Sam,","from":"you@example.com","to":"sam@example.com","status":"draft","awaitingApproval":true,"lifecycleState":"awaiting-approval","retryCount":0,"sequenceStep":1,"totalSteps":3,"qualityEvaluationHistory":[]}

The command calls GET /api/v1/organizations/{organizationId}/workspaces/{workspaceId}/campaign-emails/{campaignEmailId}/preview. It needs the same campaign:view permission as the app. An email you cannot see returns 404, and a malformed ID returns 400. cc, bcc, scheduledAt and sentAt appear only when set.

​Global flags

​Command groups

​Dry run

​Headless data commands

​Examples

​Campaign activation

​Testimonials and inbox assistance

​Signals, changelog and inbox templates

​Meetings

​Fallback emails, Meetings payments and imports, and bulk approve

​Campaign email state

​Campaign email preview

Global flags

Command groups

Dry run

Headless data commands

Examples

Campaign activation

Testimonials and inbox assistance

Signals, changelog and inbox templates

Meetings

Fallback emails, Meetings payments and imports, and bulk approve

Campaign email state

Campaign email preview