CLI commands

These commands follow CLI 0.4.0 from a saved message to an inspected review. They create draft and review state in the selected workspace; they do not send email.

Use your own workspace slug, saved sender identifier, purpose, and collection. The acme values and UUIDs below are fictional. Generate a fresh draft UUID once, save it before creating the draft, and keep it throughout the workflow. Replace version numbers with the latest returned version.

• CLI setup
• Use MCP tools instead

Use Node.js 20.9.0 or newer. An agent with terminal access can run the same commands.

npm install -g @fonte-is/cli@0.4.0
fonte --version
fonte auth login

Complete browser sign-in. It establishes account access; it does not choose an audience or approve a broadcast.

Start with the workspace and saved sender resolved from Fonte or the MCP catalogs. CLI 0.4.0 has no general workspace-list or sender-list command. MCP provides fonte_list_workspaces and fonte_list_broadcast_senders for that discovery.

List the workspace’s communication purposes and factual audience source identifiers:

fonte broadcast audience options \
  --workspace acme \
  --environment production \
  --json

Read result.communication_purposes and result.sources. Use the selected communication_purpose_id and collection_id in the create command. Do not turn a collection label or sender email into a guessed identifier.

• MCP workspace and sender discovery

CLI draft creation saves the title, subject, message, sender, purpose, and selected audience together. The idempotency key is also the draft ID, so save it before invoking the command.

fonte broadcast draft create \
  --workspace acme \
  --environment production \
  --idempotency-key 10000000-0000-4000-8000-000000000001 \
  --title 'October update' \
  --subject 'A note from the studio' \
  --preheader 'A few things we have been making.' \
  --body '<h1>Something worth sharing.</h1><p>Here is our October update.</p>' \
  --sender-profile-id sender_example \
  --communication-purpose-id 10000000-0000-4000-8000-000000000002 \
  --include-collection 10000000-0000-4000-8000-000000000003 \
  --json

Selected fields from a successful response:

{
  "outcome": "completed",
  "reason": "broadcast_draft_created",
  "result": {
    "kind": "broadcast_draft",
    "outcome": "applied",
    "draft_id": "10000000-0000-4000-8000-000000000001",
    "version": 1
  }
}

Use your complete, tested message in place of the short body above. The included collection determines the intended audience; live permission and opt-outs still determine eligibility.

• Prepare and test an email

Read the draft you just created, a draft opened in Fonte, or the original ID after a lost create response:

fonte broadcast draft read \
  --workspace acme \
  --environment production \
  --draft-id 10000000-0000-4000-8000-000000000001 \
  --json

Use result.version as the expected version when requesting a review. CLI 0.4.0 does not expose a draft-update command; edit the same draft in Fonte or use fonte_update_broadcast_draft over MCP, then read it again. Re-running create with changed content is not an edit.

• Save changes through MCP

Save a new request UUID for this exact review. Use the version returned by the latest read; version 1 below is the example’s initial draft version.

fonte broadcast review \
  --workspace acme \
  --environment production \
  --draft-id 10000000-0000-4000-8000-000000000001 \
  --expected-version 1 \
  --request-id 10000000-0000-4000-8000-000000000005 \
  --audience-mode reuse_compatible \
  --wait-ms 1000 \
  --json

The result contains request_id and operation. Keep operation.operationUri. A pending response means the observation wait ended while the review continues; it does not require another request.

{
  "outcome": "pending",
  "request_id": "10000000-0000-4000-8000-000000000005",
  "reason": "broadcast_review_queued",
  "operation": {
    "operationId": "10000000-0000-4000-8000-000000000006",
    "operationUri": "/v1/workspaces/acme/broadcast-review-operations/10000000-0000-4000-8000-000000000006?environment=production",
    "state": "queued",
    "executionAuthorized": false
  }
}

This response shows selected fields. Review checks the saved message, sender route, audience, and commercial state. audience-mode refresh explicitly requests a refreshed audience; a retry keeps the original inputs.

Copy the returned operation URI exactly. This fictional example uses the URI from the preceding response:

fonte broadcast operation \
  --workspace acme \
  --environment production \
  --draft-id 10000000-0000-4000-8000-000000000001 \
  --operation-uri '/v1/workspaces/acme/broadcast-review-operations/10000000-0000-4000-8000-000000000006?environment=production' \
  --kind review \
  --wait-ms 1000 \
  --json

Read operation.state. queued and running mean work continues; ready means a review is available. failed and cancelled need the returned blocker or recovery guidance. operation.summary gives recipientCount and excludedCount when ready.

The review contains a commercialReviewRef, not a display price. Use Billing for payment terms or a required card authorization, then check the recipient counts and approve the exact audience send in Fonte. A ready review has executionAuthorized false.

• Review recipients and cost in Fonte

If the review response was lost, recover using the original request ID. The CLI reloads the saved immutable request from this installation and reuses its identity.

fonte broadcast send recover \
  --workspace acme \
  --environment production \
  --draft-id 10000000-0000-4000-8000-000000000001 \
  --request-id 10000000-0000-4000-8000-000000000005 \
  --wait-ms 1000 \
  --json

Despite its command name, send recover also recovers a saved review. Recovering the review above does not send email. A previously approved Send request remains a Send request when recovered.

If the local saved input is unavailable, retain the original review command and request UUID and replay those unchanged. Read a lost create response with draft read. If you deliberately change the message, read its new version and request a new review; do not reuse a request ID with different inputs.

For a broadcast that has already been submitted, this command reads Send state by draft ID:

fonte broadcast send status \
  --workspace acme \
  --environment production \
  --draft-id 10000000-0000-4000-8000-000000000001 \
  --json

Use broadcast operation with kind send when observing a returned Send operation URI. Processing, executable work, provider acceptance, and delivery describe different stages; report the observed state.

After separate approval of an exact Send, broadcast send consumes its complete immutable send-input. Preserve the approved input and request ID for recovery. The old broadcast authorize and unreviewed send now paths are retired.

• Monitor a broadcast in Fonte
• Resolve a blocked or uncertain result

fonte auth status --json
fonte --help
fonte broadcast --help
fonte broadcast review --help

Auth status checks local credential state. A successful local check does not establish that the account can access a particular workspace. Use authenticated reads for that confirmation. Command help describes the flags admitted by your installed release.