# CLI (/docs/cli)

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:

```sh
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](https://github.com/cosscom/coss-cli/releases) (`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 [#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](/docs/environments#personal-keys): what it sends
counts as your spend.

```sh
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 [#set-a-project-up]

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

```sh
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](/docs/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 [#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](/docs/webhooks) would receive it:

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

```ts twoslash title="app/webhooks/route.ts"
import { verifyWebhook } from "coss";

export async function POST(request: Request) {
  // In development, the secret `coss listen` printed; in production, the endpoint's.
  const event = await verifyWebhook(
    await request.text(),
    request.headers,
    process.env.COSS_WEBHOOK_SECRET!,
  );
  console.log(event.type, event.id);
  return new Response("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](/docs/logs)
  (`webhook.forward`). A failed forward isn't retried: [trigger](#trigger-test-events) 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 [#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:

```sh
# 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](/docs/webhooks) 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 [#webhook-endpoints-and-deliveries]

```sh
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 [#send-test-emails]

```sh
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](/docs/environments), 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 [#find-and-debug-emails]

```sh
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 [#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 [#suppressions]

```sh
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](/docs/email/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 [#sub-accounts]

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

[Sub-accounts](/docs/email/subaccounts) 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 [#send-test-sms]

```sh
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](/docs/sms/testing) 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](/docs/sms/senders). Also: `--body` (default "Test message
from the coss.com CLI"), `--tag name=value` (repeatable) and `--json`.

## Read SMS [#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 [#verify]

Send and check [one-time codes](/docs/verify). Development keys deliver nothing, and the code is
all zeros:

```sh
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 [#contacts-and-broadcasts]

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

```sh
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 [#audiences-segments-and-topics]

```sh
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](/docs/email/audiences-and-segments) 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](/docs/email/topics-and-preferences) 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 [#sign]

Collect [signatures](/docs/sign) on a PDF:

```sh
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 [#follow-the-log]

```sh
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](/docs/logs) 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 [#log-drains]

```sh
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](/docs/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 [#hooks]

The [Hooks](/docs/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.

```sh
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](/docs/hooks/portal) (`--open` opens it, `--read-only`, `--expires-in <seconds>`). Anyone
  with the link is signed in until it expires.

## Risk [#risk]

Try [Risk](/docs/risk) decisions before wiring them into your app, and manage what the environment
remembers:

```sh
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](/docs/risk/testing) 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:

```sh
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](/docs/risk/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](/docs/risk/lookups). 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](/docs/risk/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 [#forms]

See the environment's [forms](/docs/forms) and what was submitted to them:

```sh
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 [#scheduling]

See the environment's [hosts and bookings](/docs/scheduling):

```sh
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](/docs/scheduling/reassigning),
  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](/docs/scheduling/reassigning#many-at-once),
  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](/docs/scheduling/out-of-office) (`--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:

```sh
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 [#receive-emails]

```sh
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](/docs/email/receiving) 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 [#inboxes]

```sh
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](/docs/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 [#domains]

```sh
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](/docs/email/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 [#templates-as-code]

Keep [email templates](/docs/email/templates) in your repository and push them from there:

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

```text
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 [#call-any-endpoint]

`coss api` calls an endpoint of the [API](/docs/api-reference) 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`:

```sh
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 [#shell-completion]

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

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

## Scripting [#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:

| Code | |
| --- | --- |
| `0` | Done. |
| `1` | It failed: an API error, a network error, a key that isn't valid. |
| `2` | Wrong usage: an unknown command or option, or a bad value. |
| `130` | Stopped with Ctrl-C (how `coss listen` and `coss logs tail` end). |

## Updates [#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 [#environment-variables]

| Variable | |
| --- | --- |
| `COSS_API_KEY` | Use this key instead of a saved profile. |
| `COSS_PROFILE` | The saved profile to use. |
| `COSS_BASE_URL` | Another API origin. Remembered by `coss login`. |
| `COSS_DASHBOARD_URL` | Another dashboard for `coss login`. |
| `NO_COLOR` | No colors (or `--no-color`). |
| `COSS_NO_UPDATE_CHECK` | `1`: no update notice. |
