CLI

Use email, marketing, inboxes, SMS, Verify, Sign, Forms, Scheduling, Hooks and Risk from your terminal, follow your log and get webhooks on localhost.

The coss command line works with one environment at a time, like an API key does. Install it with Homebrew, the install script or npm:

brew install cosscom/tap/coss     # macOS and Linux, with shell completions
curl -fsSL https://raw.githubusercontent.com/cosscom/coss-cli/main/install.sh | sh
npm install -g coss-cli           # Node.js 22+
coss login

Or run any command with npx coss-cli <command> without installing it (npx coss is the SDK, not the CLI).

  • Homebrew and the install script install a standalone executable, which needs no Node.js: each release on cosscom/coss-cli (coss-cli@<version>) has one for macOS, Linux (glibc and musl) and Windows, arm64 and x64, with a SHA256SUMS.
  • The install script picks the archive for your machine, checks it against SHA256SUMS and installs coss into ~/.local/bin (set COSS_INSTALL_DIR for another directory, COSS_VERSION for another version).
  • Alpine and other musl systems need libstdc++ (apk add libstdc++).
  • macOS executables are signed with coss.com's Developer ID and notarized by Apple (since 0.3.0), so one you download with a browser runs without a Gatekeeper warning.
  • Windows: download coss-cli-<version>-windows-x64.zip from the release, or use npm.

Sign in

coss login opens the dashboard in your browser. Check that the page shows the same verification code as your terminal, pick the environment the CLI should work in (a development environment is the default), and approve: the CLI gets a new API key of that environment, named after your machine, and saves it. It is your personal key: what it sends counts as your spend.

coss login
coss whoami   # Acme / Default / Development (sandbox)
  • No browser on that machine (over SSH, the default there): coss login --no-browser prints a link to open anywhere you're signed in; paste the code the page shows back into the terminal.
  • Members sign in to environments open to personal keys (new projects' development environments are). Elsewhere, ask an owner or admin for a key and run coss login --manual, which asks for the key (or reads it from stdin: echo "$KEY" | coss login --manual).
  • Several environments: save each under a profile (coss login --profile prod), then pass --profile prod or set COSS_PROFILE=prod. coss profiles list shows the saved profiles (--json: one object per profile, never its key) and coss use prod makes one the default.
  • CI and scripts: set COSS_API_KEY; it wins over saved profiles. No flag takes a key, since command lines are visible to other processes on the machine.

coss logout removes the saved key and revokes it if coss login created it (--revoke also revokes a key you pasted; --all signs every profile out). Keys are saved in ~/.config/coss/config.json ($XDG_CONFIG_HOME, or %APPDATA% on Windows), readable only by you.

coss open opens the environment in the dashboard: coss open logs, coss open webhooks, coss open api-keys, coss open domains, or an organization page (coss open members, coss open billing). coss open --help lists every page, each product's included (coss open risk-rules, coss open scheduling-hosts); --print (or --json) prints the URL instead.

Set a project up

coss init, in a project's directory, gets it ready to send:

cd my-app
coss init
  • It asks the dashboard for a new development key for the project (approved like coss login, offering only sandbox environments, and named after the project) and writes it as COSS_API_KEY to .env.local in a Next.js project, .env otherwise, or the file --env-file names. This key is the project's, not the CLI's. A file that already has a key keeps it unless you pass --force; it warns when git doesn't ignore the file.
  • It installs the coss package with the project's package manager (from its lockfile: bun, pnpm, yarn or npm); --no-install skips that.
  • --product <product> ends with that product's step instead of email's: what it still needs, or with a development key how to try it (email, sms, verify, sign, forms, scheduling, inboxes, hooks, risk or marketing).
  • It adds a short section on coss.com to the project's AGENTS.md (its CLAUDE.md when it has no AGENTS.md): where the docs are for agents, what the development key does, and how to test. --agents is the default. Running it again updates that section. --no-agents skips it. See Coding agents.
  • It prints the one next step for this key (a from address that will succeed, or the DNS still missing) and, when the project already uses one, the Nodemailer, Better Auth, Auth.js, Laravel, Rails or Django drop-in. --json includes that report as setup.
  • --no-browser works as with coss login; --json prints what it did as one object.

Receive webhooks locally

coss.com can't reach localhost, so coss listen fetches the environment's events and forwards each one to your local server, exactly as an endpoint would receive it:

coss listen --forward-to localhost:3000/webhooks
# Ready! Listening to Acme / Default / Development (sandbox), forwarding to http://localhost:3000/webhooks.
# COSS_WEBHOOK_SECRET=whsec_…
# Saved COSS_WEBHOOK_SECRET in .env.local (API version 2026-10-10)

Requests are signed with that secret. An existing COSS_WEBHOOK_SECRET in the project's env file is kept, so the handler's secret does not change; otherwise coss listen writes the profile's secret, or a new one, into the same file as COSS_API_KEY. Verify requests as you would in production:

app/webhooks/route.ts
import {  } from "coss";

export async function (: ) {
  // In development, the secret `coss listen` printed; in production, the endpoint's.
  const  = await (
    await .(),
    .,
    ..!,
  );
  .(., .);
  return new ("ok");
}
  • Only events created while it runs are forwarded, oldest first; the webhook-id header is the event's id, as in production. --events email.delivered,email.bounced subscribes to fewer.
  • Each forward shows its status in the terminal and in the environment's log (webhook.forward). A failed forward isn't retried: trigger it again.
  • Without --forward-to, events are only printed (--print-json shows their bodies, --json prints one JSON object per event).
  • --header "Authorization: Bearer dev-token" adds a header to every forwarded request (repeatable), for a local server that expects one.
  • Events render in your organization's API version unless you pass --api-version.
  • domain.*, account.* and billing.* events only reach live environments. Listening to a live environment, with its real events, needs --live.
  • An environment has at most 5 listeners at once. One that stops polling (your laptop sleeps) closes after 10 minutes, and coss listen opens a new one when it wakes up: events in between are missed.

Trigger test events

With coss listen running, coss trigger sends a test event of any type, so you can work on a handler without making the real thing happen:

# terminal 1
coss listen --forward-to localhost:3000/webhooks
# terminal 2
coss trigger email.bounced
# ✔ email.bounced evt_01k7c8m4r0c2b8w9y3d5f6g7h8 → 0 endpoints, 1 listener
coss trigger contact.unsubscribed -F contact.email=ada@example.com
coss trigger risk.assessment.review --data '{"user_id":"u_42","score":0.91}'

The event is a realistic sample of its type, sent to the environment's subscribed endpoints and open listeners exactly like a real one: same body, signature, retries and log lines, with nothing marking it as a test. Its ids are made up, so pass real ones for a handler that looks them up: --data takes a JSON object merged over the sample's data, and -F name=value (--field) sets one field, with dotted names reaching into objects (-F bounce.sub_type=NoEmail) and values read as JSON when they parse (@path reads a file). Unknown fields are refused. --json prints the event that was sent.

  • Test events are for development environments (sandbox keys) only, and of every type except the live-only domain.*, account.* and billing.*. Tab completes the types.
  • To run an email through the real pipeline instead (sending, the provider, then its events), send it to the mailbox simulator: coss emails send --simulate bounced.

Webhook endpoints and deliveries

coss webhooks list
coss webhooks add https://example.com/webhooks --events email.delivered,email.bounced
coss webhooks deliveries whep_01k7c8m4q2f3e9v6t5r1n0p8yz --status failed
coss webhooks retry whep_01k7c8m4q2f3e9v6t5r1n0p8yz whdel_01k7c8m4q2f3e9v6t5r1n0p8yz

coss webhooks list shows the environment's endpoints with their URL, state (enabled, failing, disabled) and event types. coss webhooks add <url> creates one. Its signing secret is returned once and written to the project env file as COSS_WEBHOOK_SECRET (a previous value is replaced, so coss listen signs with the same secret). --description stores a note, --events limits the types (the default is every event, including ones added later), and --force creates another endpoint when that URL already has one. Without --force the existing endpoint is left as it is. Creation is not retried. coss webhooks deliveries <endpoint> lists an endpoint's deliveries, newest first, with the last status code and error; filter with --status pending|succeeded|failed or --event <event id>, and show up to --limit 100 (default 20). coss webhooks retry <endpoint> <delivery> sends a finished delivery once more, within seconds. Each takes --json.

Send test emails

coss emails send --to you@example.com
coss emails send --simulate bounced --wait

With a development key nothing is delivered, but every event and webhook a real send has still happens. --simulate delivered|bounced|complained|suppressed sends to the mailbox simulator, which produces that outcome in development and production alike; --wait follows the email until it's known and prints its events, so with coss listen running you see the matching webhooks arrive. It waits up to 60 seconds (--timeout <seconds>).

The default sender for development keys is coss.com CLI <cli@example.com>; production keys need --from on a verified domain. Also: --subject, --text/--text-file, --html/--html-file, --template <id or alias> with --var name=value, --cc, --bcc, --reply-to, --category, --tag name=value and --json.

Find and debug emails

coss emails list --recipient-status bounced --since 1d
coss emails diagnose email_01k7c8m4q2f3e9v6t5r1n0p8yz
coss emails diagnose --to ada@example.com

coss emails list shows the environment's emails, newest first, with where each one stands: its status until it was handed to the provider, then its recipients' (delivered, 2 delivered, 1 bounced). Filter by --to, --status, --recipient-status, free text (-q), --category, --batch <id> and creation time (--since, --until); --limit sets how many (20 by default, read page by page). --json prints one email per line.

coss emails get <id> shows one email: sender, recipients and their statuses, its failure, tracking counts and attachments (--text or --html prints that body alone). coss emails events <id> lists its events, with what the receiving server answered.

coss emails diagnose <id> explains the outcome: a verdict, what each recipient's status means (a hard bounce and the server's reason, the suppression entry that skipped an address, a delay, a failure and its cause), account problems that affect it (an unverified domain, reputation, a billing hold) and the next steps, as commands to run. --to <address> diagnoses the newest email to that address. It's the same diagnosis as the SDK's coss/diagnose and the MCP server's diagnose_email, and each product has one (coss sms diagnose, coss verify diagnose, coss sign diagnose, coss forms diagnose, coss hooks diagnose, coss scheduling diagnose).

Scheduled emails

coss emails cancel <email> cancels an email scheduled for later. coss emails reschedule <email> --at <time> moves it (ISO 8601 with an offset, at most 30 days ahead). A time that has passed sends it right away, so a live key asks first; off a terminal that needs --yes.

Suppressions

coss suppressions check ada@example.com --category newsletter
coss suppressions add ada@example.com --scope newsletter
coss suppressions list --scope "*"
coss suppressions remove sup_01k7c8m4q2f3e9v6t5r1n0p8yz

Suppressions are the addresses sends skip.

  • coss suppressions list lists them, newest first (--address, --scope, --limit).
  • coss suppressions check <address> says whether a send would skip it and which entries match (--category, --stream transactional|marketing). It exits 0 either way: scripts read suppressed from --json.
  • coss suppressions add <address> adds one, for every email or one category (--scope).
  • coss suppressions remove <suppression> removes one by id. Someone who complained or unsubscribed asked not to be contacted.

Each takes --subaccount <subaccount> for a sub-account's own list (check for the sub-account you plan to send for), except remove, which takes the entry's id.

Sub-accounts

coss subaccounts create "Acme Inc" --uid acme --per-day 1000
coss subaccounts stats acme --from 2026-10-01

Sub-accounts give each of your users their own domains, suppressions, quotas and reputation. Every <subaccount> is its id or your uid.

  • coss subaccounts list (--limit) and coss subaccounts get <subaccount> show them, with their quotas and reputation.
  • coss subaccounts create <name> makes one (--uid, --metadata name=value, and the quotas --per-day, --per-second, --burst).
  • coss subaccounts update <subaccount> changes what is given: --name, --uid (none removes it), --status active|disabled, --metadata (replaces what it has) and the quotas (none removes one).
  • coss subaccounts reinstate <subaccount> lifts a reputation pause once you fixed the cause.
  • coss subaccounts stats <subaccount> prints its sending per day (--from, --to; at most the last 45 days).
  • coss subaccounts delete <subaccount> starts deleting it: its sends are refused at once, then its domains are released and it is removed with its suppressions. It can't be undone, so with a live key it asks first, and off a terminal it needs --yes.

Send test SMS

coss sms send --simulate filtered --wait
coss sms send --to +14155550199 --from +14155550123 --body "Your code is 482913"

--simulate delivered|invalid|filtered|opted-out|reply sends to the SMS simulator and needs a development key: nothing reaches a phone, but every event and webhook a real send has still happens. Otherwise pass --to (E.164). --wait follows the message until its outcome is known and prints its events (with --simulate reply, also the simulated reply); it waits up to 60 seconds (--timeout <seconds>).

The default sender for development keys is +14155550100; production keys need --from, one of your organization's registered numbers. Also: --body (default "Test message from the coss.com CLI"), --tag name=value (repeatable) and --json.

Read SMS

  • coss sms list lists the environment's messages, newest first (--to, --status, --limit).
  • coss sms get <message> prints a message's text, status, failure and events.
  • coss sms received lists what your numbers received (--from, --to, --limit).
  • coss sms numbers lists your numbers and whether each can send.
  • coss sms suppressions list (--number, --limit), coss sms suppressions add <number> and coss sms suppressions remove <suppression> manage the numbers that won't be texted.
  • coss sms diagnose <message> (or --to <number>, the newest to it) explains the outcome: a verdict, what the failure code means, the carrier's error code, problems with the sender's registration, suppressions, reputation or billing, and what to do next.

coss sms cancel <message> cancels a scheduled message. coss sms suppressions check <number> says whether a send to a number would be skipped; it exits 0 either way.

Verify

Send and check one-time codes. Development keys deliver nothing, and the code is all zeros:

coss verify start +15005550006
coss verify check --to +15005550006 --code 000000
  • coss verify start <to> sends a code to a number in E.164 form or an address (--channel, --ip, --user).
  • coss verify check --code <code> compares a code, by --id <verification> or --to <destination>. It exits 0 only when the code is right, and a wrong code spends an attempt.
  • coss verify list (--to, --status, --limit), coss verify get <verification> and coss verify cancel <verification>.
  • coss verify diagnose <verification> (or --to <to>) says why no code arrived or a check failed: the fraud guard's reasons, expiry and attempts, each code's route and the latest message's outcome. It never shows a code.
  • coss verify settings get shows the settings, and coss verify settings set changes them: --app-name, --code-length, --ttl, --max-attempts, --sms-from, --email-from, --countries US,CA,GB. The word default goes back to coss.com's sender or the project's name.

Contacts and broadcasts

coss contacts add ada@example.com --audience aud_01kd2m8n3p4q5r6s7t8v9w0x1y
coss broadcasts create --name October --from news@acme.com --subject News --html october.html \
  --audience aud_01kd2m8n3p4q5r6s7t8v9w0x1y
coss broadcasts test bcast_01kd2m8n3p4q5r6s7t8v9w0x1y --to you@acme.com
coss broadcasts send bcast_01kd2m8n3p4q5r6s7t8v9w0x1y
  • coss contacts list (--email, --status, --audience, --limit), coss contacts get <contact> and coss contacts remove <contact>, by id or address.
  • coss contacts add <email> creates or updates a contact (--first-name, --last-name, --audience, repeatable, and --double-opt-in).
  • coss broadcasts list (--status, --limit), coss broadcasts get <broadcast> and coss broadcasts cancel <broadcast>.
  • coss broadcasts create makes a draft: --name, --from, --subject, --html <file>, --text <file>, and --audience, --segment or --topic. It sends nothing.
  • coss broadcasts test <broadcast> --to <address> sends a test (--contact renders it for one).
  • coss broadcasts send <broadcast> sends it, or schedules it with --at <time>. With a production key it asks first, and needs --yes off a terminal.

Change and move contacts in bulk:

coss contacts update ada@example.com --first-name Ada --property plan=pro
coss contacts import people.csv --audience aud_01k7c8m4q2f3e9v6t5r1n0p8yz
coss contacts export --status subscribed --out contacts.csv
  • coss contacts update <contact> changes what is given: --first-name and --last-name ("" clears one), --status subscribed|unsubscribed, --property name=value (JSON values when they parse, null removes it), and --data '{…}' for the rest of the body, such as topics.
  • coss contacts import <file> creates or updates contacts from a CSV or a JSON array of import entries (- reads stdin), and adds them to --audience. A CSV is what coss contacts export writes, or any file with an email column (First Name-style headers work) or just addresses, one per line. Columns named after a custom property set it, and other columns are reported and left out. Imports never resubscribe an unsubscribed contact and are safe to run again. Rows it can't use are skipped and listed, and then it exits 1. Only import people who agreed to hear from you.
  • coss contacts export prints the contacts as CSV (--status, --audience), or saves them with --out <file> (a new file is readable only by you). A pipe gets the bytes as they came; a terminal gets them without control characters. --json prints { csv }, or { file, size } with --out.

Broadcasts can change until they send, and stop and start while they do:

  • coss broadcasts update <broadcast> changes a draft (--name, --from, --subject, --html, --text, --audience, --segment, --topic, where none means every contact, and --data).
  • coss broadcasts remove <broadcast> deletes a draft, or a broadcast canceled before it sent anything.
  • coss broadcasts pause <broadcast> pauses a scheduled or sending one. coss broadcasts resume <broadcast> sends the rest: with a live key it asks first, and off a terminal it needs --yes.

Audiences, segments and topics

coss audiences create Customers
coss audiences contacts add aud_01k7c8m4q2f3e9v6t5r1n0p8yz ada@example.com bo@example.com
coss segments create "Acme staff" --filter '{"version":1,"match":"all","conditions":[{"field":"email","op":"ends_with","value":"@acme.com"}]}'
coss topics create product --name "Product news" --default opt_in
  • Audiences are static lists: coss audiences list, coss audiences get <audience>, coss audiences create <name>, coss audiences update <audience> --name <name> and coss audiences remove <audience>, which leaves their contacts. coss audiences contacts list <audience>, coss audiences contacts add <audience> <contact>... (ids or addresses of existing contacts; exits 1 when one is no contact) and coss audiences contacts remove <audience> <contact> manage who is in one.
  • Segments are filters, evaluated whenever they're used: coss segments list, coss segments get <segment>, coss segments create <name> --filter <json>, coss segments update <segment> (--name, --filter) and coss segments remove <segment>. --filter takes JSON inline, as @file or as - for stdin. coss segments contacts list <segment> lists who a segment matches now.
  • Topics are what contacts subscribe to: coss topics list, coss topics get <topic>, coss topics create <key> --name <name> --default opt_in|opt_out, coss topics update <topic> and coss topics remove <topic> (--description, where none clears it on update, --visibility public|private, --position).
  • coss marketing settings get shows the sender's name and postal address marketing email carries, and how double opt-in confirms. coss marketing settings set changes --display-name, --mailing-address, --double-opt-in or --no-double-opt-in, --confirmation-from, --confirmation-subject, --confirmation-html <file>, --confirmation-text <file> and --confirmed-redirect-url; the word default clears one.

Sign

Collect signatures on a PDF:

coss sign upload nda.pdf
coss sign create --title NDA --document sdoc_01kd2m8n3p4q5r6s7t8v9w0x1y --signer "Ada Lovelace <ada@example.com>"
coss sign send sreq_01kd2m8n3p4q5r6s7t8v9w0x1y
  • coss sign upload <file.pdf> prints the document's id and the text anchors found in it.
  • coss sign create makes a draft: --title, --message, --document (repeatable) and --signer "Name <email>" (repeatable), each signer signing at the anchor {{signature:signer_1}}, {{signature:signer_2}}…; or --template with --signer "role:Name <email>" and --merge name=value. --send sends it at once. coss api takes any other fields.
  • coss sign list (--status, --limit), coss sign get <request>, coss sign send <request>, coss sign remind <request> and coss sign cancel <request>.
  • coss sign download <request> saves the sealed PDF (--out <file>), and coss sign audit <request> prints the audit trail.
  • coss sign templates lists templates and their roles.
  • coss sign diagnose <request> says where a request stands: each signer's state and whose turn it is, a draft never sent, declined, expired, or signed and still being sealed.

coss sign templates (or coss sign templates list) lists templates. coss sign templates create <name> makes one: --title, --message, --signing-order parallel|sequential, --document <document> (repeatable), --role key:Name (repeatable), and --data '{"fields":[…]}' or --data @template.json for its fields. It may start empty and be built in the embedded builder; requests can be made from it once it has documents and a signature field for every role.

coss sign settings get shows the name signers see, the sender, branding, reminders and embedding origins. coss sign settings set changes --display-name, --email-from, --accent-color, --theme system|light|dark, --disclosure, --reminder-days and --origin (repeatable, replacing the list); the word default clears one.

Follow the log

coss logs tail
coss logs tail --source email --level error
coss logs tail --type api.request --status 4xx,5xx --since 15m

New lines of the environment's log as they arrive: API requests made with its keys, email and SMS events, webhook attempts and coss listen forwards. Filter by --source, --level, --type, --status and free text (-q); --since starts with earlier lines, and --json prints one log object per line for jq. It checks for new lines every 2 seconds (--interval <ms>, at least 500).

Log drains

coss log-drains create https://logs.acme.com/in --source api,email
printf '%s' "$DD_API_KEY" | coss log-drains create https://http-intake.logs.datadoghq.com/api/v2/logs --format datadog --auth-header DD-API-KEY
coss log-drains update ldr_01k7c8m4q2f3e9v6t5r1n0p8yz --disabled

Log drains stream the environment's log to your own endpoint or an intake API.

  • coss log-drains list and coss log-drains get <drain> show them; secrets are never included.
  • coss log-drains create <url> makes one (--description, --source api|email|webhook|audit, repeatable or comma-separated, --format ndjson|loki|datadog|otlp) and prints its signing secret: the only time it's shown. It isn't retried, since the API doesn't deduplicate it.
  • --auth-header <name> sends that header with every batch. Its value is a secret, and no flag takes a secret, since command lines are visible to other local processes: a terminal asks for it without echoing, and anything else pipes it to stdin.
  • coss log-drains update <drain> changes what is given: --url, --description (none clears it), --source, --format, --auth-header, --remove-auth-header. --disabled stops it and drops the lines waiting for it; --enabled starts it again, also after coss.com disabled it for failing.
  • coss log-drains delete <drain> deletes it and its batch log.

Hooks

The Hooks loop from the terminal: set up an application with an endpoint, send it messages, and see what its endpoints answered. Wherever a command takes <app>, an application's uid works as well as its id.

coss hooks event-types create invoice.paid --example '{"invoice_id":"in_1","amount":4200}'
coss hooks apps create "Acme" --uid acme
coss hooks endpoints add acme --url https://example.com/hooks --types invoice.paid
coss hooks send acme invoice.paid -F amount=4200 -f invoice_id=in_2
coss hooks deliveries acme --status failed
coss hooks portal acme --open
  • coss hooks apps list and coss hooks apps create <name> (--uid, --metadata key=value) manage applications; coss hooks event-types list (--archived) and coss hooks event-types create <name> (--description, --schema, --example, each JSON inline, @file or - for stdin) the event types. Lists show 50 (--limit, up to 100).
  • coss hooks endpoints list <app> shows each endpoint's state; coss hooks endpoints add <app> --url <url> (--types, --description, --rate-limit) prints the new endpoint's signing secret, the only time it's shown.
  • coss hooks send <app> <event-type> sends a message: the payload is --data (a JSON object) with -F name=value (JSON values, @file) and -f name=value (strings) on top, or, with none of them, the event type's first example. --idempotency-key sends it once only.
  • coss hooks deliveries <app> lists deliveries, newest first, of every endpoint or one (--endpoint), or of one message (--message), by --status (pending, succeeded, failed); coss hooks attempts <app> <delivery> shows each HTTP request of one, and coss hooks retry <app> <delivery> queues a finished one for another attempt.
  • coss hooks diagnose <app> <delivery> (or --message <message>, its worst delivery, or --endpoint <endpoint>, its latest failure) says what the endpoint answered on each attempt, when the next retry is, whether it's disabled or failing, and what to do next.
  • coss hooks portal <app> prints a link that signs in to the application's portal (--open opens it, --read-only, --expires-in <seconds>). Anyone with the link is signed in until it expires.

Risk

Try Risk decisions before wiring them into your app, and manage what the environment remembers:

coss risk assess --event signup --email ada@disposable.test --ip 192.0.2.1
coss risk assessments --review open
coss risk feedback rass_01k7c8m4q2f3e9v6t5r1n0p8yz --outcome fraud --note "chargeback"
coss risk lists add block domain evil.example --expires 30d --note "spam wave"
  • coss risk assess --event <event> (signup, login, message, checkout or custom with --event-name) takes --email, --ip, --user (your user id), --user-agent, --content, --captcha and --device tokens, and --data for anything else of the request (a checkout, say), and prints the decision, its score and each reason. It counts like any assessment.
  • In development environments the test fixtures produce each decision: 192.0.2.1 (Tor), .2 (a cloud), .3 (a VPN), .4 (a proxy) and .5 (a privacy relay); addresses at disposable.test, undeliverable.test and new.test; captcha tokens test-pass and test-fail; the device token test-device-automated; content with [coss-test:spam] (or phishing, malware, fraud, and [coss-test:spam:0.6] for a given score).
  • coss risk assessments lists assessments by --decision, --event, --user and --review (open is the review queue); coss risk feedback <assessment> --outcome legitimate|fraud|abuse (--note) reports what the user turned out to be.
  • coss risk lists list (--list allow|block, --type), coss risk lists add <allow|block> <email|domain|ip|asn|country|user> <value> (--note, --expires as 7d, 12h or a time) and coss risk lists remove <entry> manage the allow and block lists.

Manage what decides:

coss risk rules create "No Tor sign-ups" --action block --event signup --condition "ip.tor is true"
coss risk check email ada@gmial.com
coss risk classify --file message.txt
coss risk settings set --review-threshold 0.4
  • coss risk rules list and coss risk rules get <rule> show the rules, in the order they're tried: the first enabled one whose conditions match decides, after the lists.
  • coss risk rules create <name> adds one: --action allow|review|block and --condition "<field> <operator> <value>", repeatable ("velocity.ip_1h gt 10", "ip.country in RU,KP"; operators is, eq, neq, gt, gte, lt, lte, in, not_in), with --match all|any, --event (repeatable), --position, --enabled or --disabled, and --data for the same body as JSON.
  • coss risk rules update <rule> changes what is given (--name too); --condition replaces all of its conditions. coss risk rules delete <rule> deletes it.
  • coss risk check email <address>, coss risk check ip <ip> and coss risk check phone <number> ask about one signal on its own. Nothing is stored. Live phone checks that get an answer are billed, so they're never retried.
  • coss risk classify <text> scores text for spam, phishing, malware and fraud (--file <path>, or - for stdin). You choose the thresholds, and the text is neither stored nor logged.
  • coss risk settings get shows the settings. coss risk settings set changes --review-threshold, --block-threshold, --disabled-reason (repeatable, replacing the list; none empties it) and --data for content_thresholds and reason_weights.
  • --captcha turnstile|hcaptcha|off sets the captcha provider, with --captcha-required or --captcha-optional. --captcha-secret-stdin reads its secret from stdin (a terminal asks without echoing), and inline --data refuses one: no secret goes on a command line.

Forms

See the environment's forms and what was submitted to them:

coss forms list
coss forms submissions form_01kd2m8n3p4q5r6s7t8v9w0x1y --status held
  • coss forms list prints each form's id, name, whether it takes submissions and its endpoint (--limit).
  • coss forms get <form> prints a form's endpoint and settings; coss forms create <name> makes one that accepts any field (--origin, repeatable, and --redirect <url>; coss api takes every other setting).
  • coss forms update <form> changes what is given and leaves the rest: --name, --enabled or --disabled, --origin (replaces the list), --redirect (none clears it) and --data '{…}' for any other setting (fields, spam, notifications, hosted…).
  • coss forms remove <form> deletes a form with its submissions and files. It can't be undone, so with a live key it asks first, and off a terminal it needs --yes.
  • coss forms submission <form> <submission> prints one submission's values, and coss forms release <form> <submission> accepts one Risk held for review, which sends it on to the form's webhooks, notification emails and contacts.
  • coss forms submissions <form> lists a form's submissions, newest first, with their status, submitter and field names; --status accepted|held|spam|pending_confirmation narrows them (held is Risk's review queue), --limit caps them. Values are what someone typed: read them with --json or coss api forms/<form>/submissions/<id>.
  • coss forms diagnose <form> [submission] says what happened to a submission (the form's newest without an id): held, spam and why, waiting to be confirmed, or accepted and where it goes. Spam is answered exactly like a success, so a submitter who saw a success proves nothing.

Scheduling

See the environment's hosts and bookings:

coss scheduling hosts
coss scheduling bookings --host doctor_482 --status confirmed
  • coss scheduling hosts prints each host's id, your uid, name, time zone and status (--limit).
  • coss scheduling bookings lists bookings, newest first; --host and --status held|pending_approval|confirmed|cancelled|declined narrow them, --limit caps them. --json prints attendees' details, which coss scheduling bookings otherwise leaves out.
  • coss scheduling event-types lists what can be booked (--limit).
  • coss scheduling slots <event-type> --start <time> --end <time> lists bookable starts (--host).
  • coss scheduling booking-events <booking> shows a booking's history (--json), and coss scheduling cancel <booking> takes --reason.
  • coss scheduling slots explain <event-type> --start <time> says whether one start can be booked and, host by host, why not (--host).
  • coss scheduling booking <booking> shows a booking, and coss scheduling cancel <booking> cancels it and tells the attendee.
  • coss scheduling candidates <booking> lists who a booking could go to, and why not.
  • coss scheduling reassign <booking> --to <host> gives it to another host, or --auto lets coss.com pick. --from says who's leaving, if it has several hosts; --reason says why, with --note in your own words; --any-host allows someone who doesn't take the event type, --override goes past what a candidate couldn't do, and --no-notify doesn't tell the attendee.
  • coss scheduling reassign-many --from <host> moves many bookings, or --ooo <id> those in an out of office entry. --to gives them all to one host; --preferred tries those first (comma-separated) and then the fairest who's free, unless --leave-rest. --after and --before narrow it, --reason and --note say why, --no-notify doesn't tell attendees, and --dry-run shows who they'd go to and moves nothing.
  • coss scheduling reassignments lists runs (--limit). coss scheduling reassignment <id> shows one and what didn't move, --cancel stops what hasn't happened yet, and --undo gives back what it moved.
  • coss scheduling ooo lists time hosts are away (--host, --limit).
  • coss scheduling no-show <booking> marks a booking as a no-show, once it has started.
  • coss scheduling notifications <booking> lists what was queued for a booking and what became of it, newest first, including why a reminder wasn't sent (--limit).
  • coss scheduling reminders lists what goes out around a booking (--event-type for one event type's own list). Change it with coss api or in the dashboard.
  • coss scheduling calendars <host> lists a host's calendar connections. needs_reauth means that calendar can't be read, so the host isn't offered.
  • coss scheduling diagnose <event-type> explains an empty list (--start, --end, --host), each finding certain, likely or possible: no host or schedule, a calendar to reauthorize, minimum notice, the booking window, limits, bookings and buffers. A calendar's busy times aren't readable through the API, so they can only be possible.

Set scheduling up and book from the command line:

coss scheduling hosts create "Dr. Reyes" --uid doctor_482 --time-zone America/New_York
coss scheduling schedules create doctor_482 --rule "mon-fri 09:00-17:00"
coss scheduling event-types create Consultation --uid consult --minutes 30 --host doctor_482
coss scheduling book consult --start 2027-01-04T15:00:00Z --time-zone America/New_York --name Bo --email bo@example.com

coss scheduling hosts and coss scheduling event-types still list; coss scheduling hosts list and coss scheduling event-types list are the same commands.

  • coss scheduling hosts create <name> --time-zone <zone> adds a host (--uid, --email, --attribute name=value, repeat a name for a list, --metadata name=value, --data). coss scheduling hosts update <host> changes what is given (--name, --time-zone, --status active|disabled; --uid and --email take none). coss scheduling hosts remove <host> deletes one.
  • coss scheduling schedules list <host>, coss scheduling schedules create <host> --rule "<days> <start>-<end>" (repeatable: "mon-fri 09:00-17:00", "sat,sun 10:00-12:00"; --name, --time-zone, --default, --data for overrides), coss scheduling schedules update <host> <schedule> (--rule replaces its rules; without one they stay) and coss scheduling schedules remove <host> <schedule> manage when a host is free.
  • coss scheduling event-types create <title> --minutes <n> adds what can be booked (--uid, --kind one_on_one|pool|collective|group, --host, repeatable, --requires-approval, --data for buffers, limits, questions and locations). coss scheduling event-types update <event-type> changes what is given (--title, --status active|archived, --no-approval; --host replaces the hosts).
  • coss scheduling book <event-type> --start <time> --time-zone <zone> books a slot for an attendee (--name, --email, --phone, --uid, --host, --minutes, --attribute, --answer name=value, --metadata, --data).
  • coss scheduling reschedule <booking> --start <time> moves a booking (--host); the old time stays booked if the new one isn't free. coss scheduling approve <booking> and coss scheduling decline <booking> decide one waiting for approval.

book, reschedule, approve and decline tell the attendee, so with a live key they ask first, and off a terminal they need --yes.

Receive emails

coss inbox
# Inbound domain: k3j9x2m7qp4l.inbound.coss.com
coss inbox get rcv_01k7c8m4q2f3e9v6t5r1n0p8yz

coss inbox prints the environment's inbound domain: mail to any address at it is received with no DNS setup. It then prints each email the environment receives as it arrives, at that domain or at a receiving domain (--since 1h shows earlier ones too, --interval <ms> sets how often it checks, --json prints the address and then one email per line).

coss inbox get <id> shows a received email: sender, recipients, the receiving server's spam, virus, SPF, DKIM and DMARC verdicts, attachments and the text body (--html for the HTML, --headers for every header). Received mail is written by someone else, so control characters in it are left out of what's printed. --raw > message.eml saves the whole message as received (it refuses to write it to a terminal).

Inboxes

coss inboxes create --username support-agent --name "Acme Support"
coss inboxes threads inbox_01k7c8m4q2f3e9v6t5r1n0p8yz
coss inboxes thread inbox_01k7c8m4q2f3e9v6t5r1n0p8yz thread_01k7c8m4r0c2b8w9y3d5f6g7h8
coss inboxes reply inbox_01k7c8m4q2f3e9v6t5r1n0p8yz imsg_01k7c8m4s1d3c9x0z4e6g7h8j9 --text "On it."

Inboxes are email addresses for agents. coss inboxes create makes one (--username, --domain for one of the environment's receiving domains, --name for the name it sends with, --client-id for your own id: creating it again returns the same inbox), and coss inboxes list lists them (--limit). coss inboxes threads <inbox> lists its conversations, latest first, with ● on those whose latest message is inbound; coss inboxes thread <inbox> <thread> prints one, each message's own words without the quoted conversation (--full for all of it). coss inboxes reply <inbox> <message> --text <text> replies in the thread (--all replies to everyone on the message). Run coss listen to get each inbox.message.received event as it arrives.

Domains

coss domains add acme.com                 # the DNS records to publish
coss domains add acme.com --format bind   # the same, as zone-file lines to import
coss domains verify acme.com --wait       # check now, and keep checking until it's verified

coss domains list shows the organization's sending domains, and coss domains get <domain> one domain's records with what the last DNS check saw: verified, missing, or a mismatch (with the value DNS returned). Domains are named by their name or their id. coss domains verify checks now instead of waiting for the background check; with --wait it checks again every 10 seconds, printing the records still missing, until the domain is verified (exit 0), verification gives up (1), or --timeout passes (600 seconds by default, 1). A domain whose verification had given up starts over with new DKIM records, which you publish again. --json prints the domain object.

Templates as code

Keep email templates in your repository and push them from there:

coss templates pull                       # every template's draft, into ./templates
coss templates push --watch               # save the draft again on every edit
coss templates preview welcome --var first_name=Ada --open
coss templates push --publish             # publish the drafts sends use

coss templates pull [<template>...] writes each draft into a folder of --dir (templates by default) named by the template's alias, else its id:

templates/welcome/
  template.json        # name, alias, description, default_locale, variables, sample_variables
  en.subject.txt
  en.html
  en.txt
  de.subject.txt
  de.txt

Files are written byte for byte, so pulling and pushing changes nothing; a locale needs its .subject.txt and an .html, a .txt or both. coss templates push [<path>...] (template folders, or folders of them; --dir without arguments) replaces each draft with its files. It finds the template by its alias, so the same folder pushes to every environment (sign in to another with --profile), and creates templates that don't exist there yet. Without an alias the folder is tied to the template's id. A push saves only drafts its files change, lists problems (syntax errors, undeclared variables) with their file, line and column, and with --publish publishes each draft too. --watch keeps running and pushes a template again whenever one of its files changes.

coss templates preview <template> renders the draft as a send would, without sending: with its sample_variables, overridden by --var name=value (JSON values when they parse), in --locale, or a published --version. It prints the subject and text; --open shows the HTML in your browser and --output preview.html saves it. Given a folder, it previews that template's draft and warns when your files differ from it. coss templates list lists the environment's templates.

Call any endpoint

coss api calls an endpoint of the API with the CLI's key and prints the response's JSON, for anything the other commands don't cover (an unknown command's error says so too). Paths are relative to /v1:

coss api domains
coss api emails/email_01k7c8m4q2f3e9v6t5r1n0p8yz/events
coss api -X POST domains/dom_01k7c8m4q2f3e9v6t5r1n0p8yz/verify
coss api suppressions -f reason=bounce --paginate | jq -r .address
  • Fields: -f name=value (--raw-field) is always a string; -F name=value (--field) is JSON when it parses (-F limit=5, -F enabled=true, -F 'to=["a@example.com"]') and a file's contents with @path. name[]=value adds to a list. GET and DELETE send fields as query parameters, every other method as the JSON body.
  • Methods: -X (--method) takes GET (the default), POST, PUT, PATCH or DELETE. --input body.json sends that file as the body (--input - reads stdin) and makes the default POST; fields then go in the query.
  • Lists: --paginate reads every page and prints each item as one JSON object per line.
  • Other bodies: --raw prints a response that isn't JSON as it is, such as a CSV export or a received email's raw message (coss api received_emails/<id>/raw --raw > message.eml).
  • Versions: requests use the API version the CLI was built for; --api-version 2026-10-10 asks for another. --json prints JSON on one line instead of indented.

A failed call prints the error ({ "error": { "type", "code", "message", … } }) on stdout too, and exits with 1. Writes aren't retried automatically, since not every endpoint deduplicates them: run the command again.

Shell completion

coss completion bash|zsh|fish prints a script that completes commands, flags and their values (--simulate b → bounced):

eval "$(coss completion zsh)"     # in ~/.zshrc, after compinit
eval "$(coss completion bash)"    # in ~/.bashrc
coss completion fish > ~/.config/fish/completions/coss.fish

Scripting

Results go to stdout and progress to stderr, so pipes get only the results; --json makes them one JSON object per line. coss <command> --help lists a command's options and coss --version prints the CLI's. Exit codes:

Updates

Once a day, when it runs in a terminal, the CLI asks the npm registry for its latest version (a plain GET https://registry.npmjs.org/coss-cli/latest; nothing else is sent) and prints one line on stderr if a newer one exists. It never checks with --json, in CI (CI set) or when stderr isn't a terminal, never delays a command, and COSS_NO_UPDATE_CHECK=1 turns it off.

Environment variables

Last updated