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.8","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

​Global flags

​Command groups

​Dry run

​Headless data commands

​Examples

Global flags

Command groups

Dry run

Headless data commands

Examples