sendsetsctl

sendsetsctl is the CLI for a SendSets instance, and it has two halves with two trust models.

The operator commands answer two questions: what state is this install in, and how do I get back in. They read and write the database directly, so they keep working when the sign-in page does not. Their authorization is container or host access, the same trust model as Sentry's createuser, Gitea's admin user create and authentik's ak changepassword, and it is the right one when the identity system is the thing that is broken.

The API commands drive a running instance over its public REST API with an API key, so they work from any machine against any instance you hold a key for, the hosted service included. They exist so scripts and AI agents can operate the product itself: campaigns, contacts, mailboxes, the inbox, settings. Everything they can do is bounded by the key's scopes.

The CLI never serves HTTP. The API commands are a client of the already-gated public API, which adds no new surface to your instance.

Those API commands predate the sendsets CLI and still work exactly as documented below. For day-to-day product work prefer sendsets: it signs in for you, holds a credential per host, prints tables rather than raw JSON, and runs on your laptop rather than inside a container.

Running it

The binary ships inside the backend image at /usr/local/bin/sendsetsctl, so it is on the path in every runtime. Running it inside the backend is the documented path because the environment there is already correct.

docker compose -p sendsets exec backend sendsetsctl status   # docker compose
docker exec -it sendsets-backend sendsetsctl status          # plain docker
kubectl exec -it deploy/sendsets-backend -- sendsetsctl status
sendsetsctl status                                          # bare binary

Every example on this page shows the compose form. Substitute the prefix you need.

For a compose install, make cli is the same thing with less typing. Flags go through ARGS, because make reads a bare --email as one of its own options:

make cli status
make cli setup-link
make cli ARGS="user create --email you@example.com --admin"

Terminals and pipes

This is the one piece of shell mechanics the CLI cannot hide from you.

docker compose exec allocates a TTY unless you pass -T. Commands that prompt need that TTY. Commands you pipe into need it gone.

A command that would set a password refuses on a non-TTY unless you passed --password-stdin, rather than creating an account nobody can sign in to.

What it reads from the environment

backup and restore also need pg_dump and psql, which the backend image ships for exactly this reason. Inside the backend container all of these are already set, except the API key, which is yours. Outside it, export what the command needs, and match AUTH_SECRET to the backend's exactly.

The operator commands

sendsetsctl --help lists them, and sendsetsctl <command> --help prints one command's flags with an example. The API commands are further down, because they authenticate differently.

status

docker compose -p sendsets exec backend sendsetsctl status

It prints four blocks in this order: the instance state, the platform admins, how to get in, and the checks. A sample run is on first run.

The How to get in block changes with the state. An unclaimed instance is told to print a setup link; a claimed one is given the recovery commands; an instance with no platform admin is told to promote an account.

The Checks block holds the same findings the admin panel's Setup and health page shows. Every one of them is documented on instance health.

make doctor is sendsetsctl status for a compose install.

Exit status and JSON

status exits non-zero when any check is at error severity, which is what makes make doctor usable as the last line of a deploy script.

--json is the exception: it always exits 0, because make claim uses it to decide whether the backend is answering at all. Read .summary.error for the verdict instead.

Those keys are a contract. They are only ever appended to, never renamed or dropped.

setup-link

docker compose -p sendsets exec backend sendsetsctl setup-link

Prints a single-use link that claims an unclaimed instance. It expires in 24 hours, replaces any outstanding link, and only its hash is stored, so this is the only time it is printed.

It refuses on an instance that already has accounts, by design: a second owner must never be mintable without an existing account. If you get that refusal, you want user create instead.

This is the one command that cannot degrade, because the token lives in Redis. With Redis down, create the owner directly instead.

make claim wraps it for a compose install, and finds the link already in the logs before minting a new one.

user create

docker compose -p sendsets exec backend sendsetsctl user create --email you@example.com --admin

It creates the account, an organization and a free trial, and with --admin grants every platform admin bit. Use --no-org when the person will accept an invitation into a workspace that already exists.

An address that already exists is an error, and the message points you at reset-password.

The password is the one you type

There is no generated or default password. On a terminal the command prompts for it twice, with echo off:

Password for you@example.com:
Repeat password for you@example.com:
Created account you@example.com (id ...), organization "Your Organization" (id ...),
a free trial, every platform admin permission (mask 4194303).

Next
  Sign in at http://localhost:5173 with the password you just set.

It must be between 8 and 128 characters, which is the same rule the dashboard enforces, so the scripted route is never weaker than the interactive one.

From a script, pipe it in so it never reaches your shell history or ps output:

printf '%s' "$PASSWORD" | docker compose -p sendsets exec -T backend \
  sendsetsctl user create --email you@example.com --admin --password-stdin

Signing in afterwards

Open the URL the command printed, which is APP_URL, and sign in with the address and that password. On the default compose stack that is http://localhost:5173.

Nothing else stands in the way on a stock self-hosted instance:

• No emailed login code. AUTH_LOGIN_CODE defaults to off when self-hosted, and a transport that does not deliver can never gate a login whatever the setting says. See login codes
• No email confirmation. REQUIRE_EMAIL_VERIFICATION defaults to off when self-hosted, so the account is usable immediately
• No captcha unless you set TURNSTILE_SECRET
• No invitation, and no dependency on the registration mode. invite_only and true both govern the sign-up form, which this command does not use

The dashboard and the admin panel are separate apps. --admin opens the panel on ADMIN_URL, port 5174 in the default stack, not APP_URL.

user list

docker compose -p sendsets exec backend sendsetsctl user list --admin

Prints address, name, admin role and creation date, oldest first. --admin answers the narrow question of whether any admin account survives, and when none does it prints the two commands that fix that.

user reset-password

docker compose -p sendsets exec backend sendsetsctl user reset-password --email you@example.com

Without --password-stdin it prints a single-use reset URL and changes nothing yet. Open it in a browser and choose the new password there, which keeps it out of your shell history, your scrollback and the process list. It redeems through exactly the same path as the reset link the product emails, and opening it revokes every existing session for the account.

--ttl is capped at 24 hours because a reset link is a bearer credential for the account.

The automation path sets the password directly and revokes every existing session the same way:

printf '%s' "$PASSWORD" | docker compose -p sendsets exec -T backend \
  sendsetsctl user reset-password --email you@example.com --password-stdin

Reach for that form when Redis is down, since a link cannot be minted without it.

user grant-admin

docker compose -p sendsets exec backend sendsetsctl user grant-admin --email you@example.com --role super

The role replaces the account's existing mask rather than adding to it, and re-granting the role it already holds is reported as no change. The permissions are read from the session, so the account has to sign out and back in before the panel reflects the grant.

The account must already exist. make grant-admin EMAIL=... ROLE=... wraps this for a compose install. The admin panel now offers the same under Accounts > Admins, by preset or per bit, so this command is no longer the only way to add a second admin.

user revoke-admin

docker compose -p sendsets exec backend sendsetsctl user revoke-admin --email old@example.com

Removes every platform admin permission and leaves the account otherwise untouched.

Revoking the only remaining admin is refused without --force, because it closes the admin panel for everyone and nothing inside the product can reopen it. Grant someone else first. make revoke-admin EMAIL=... wraps it.

user disable-2fa

docker compose -p sendsets exec backend sendsetsctl user disable-2fa --email you@example.com

Clears the authenticator enrolment and the recovery codes, so a lost phone does not become a full password reset. The password still works, and the account can enroll a new authenticator from account security after signing in.

hash-password

sendsetsctl hash-password
printf '%s' 'your password' | sendsetsctl hash-password

Prints an argon2 hash for SENDSETS_BOOTSTRAP_PASSWORD_HASH, which provisions the owner before the first start of an instance with no accounts. See unattended provisioning.

It prompts when a terminal is attached and reads the pipe when one is not, so the same command works by hand and in a provisioning script. The hash alone goes to stdout, so it can be captured or piped; the explanation goes to stderr. This is the only command that does not need a database.

backup

docker compose -p sendsets exec backend sendsetsctl backup --out /data/blobs/sendsets.tar.gz
docker compose -p sendsets cp backend:/data/blobs/sendsets.tar.gz ./sendsets.tar.gz \
  && docker compose -p sendsets exec -T backend rm -f /data/blobs/sendsets.tar.gz

/data/blobs is the one path the container and the host both see, so it is the hand-off. Move the bundle out and delete it: backup excludes its own output from the archive, but a bundle left behind is swept into the next one. The delete is chained with && so a failed copy cannot take the only copy with it.

Writes one bundle holding the three things that only restore together: a pg_dump of the database, the blob root (message bodies, attachments, avatars), and the encryption keys.

That combination is the whole reason this is a command rather than a documented list of steps. A dump alone restores an instance whose every mailbox credential decrypts to nothing, because the ciphertext is in the database and the key that opens it is in .env. The blob root alone restores bodies nothing points at.

The bundle is written 0600 and holds every mailbox credential on the instance plus the keys that open them. Treat the file as you would the instance itself: encrypted at rest, off the host, and not in a shared drive.

Blobs travel only on the filesystem provider. An instance storing them in S3 keeps them in the bucket, and the bundle says so rather than pretending to be complete.

restore

docker compose -p sendsets exec backend sendsetsctl restore --file /data/blobs/sendsets.tar.gz
docker compose -p sendsets restart

Empties the schema and replays the bundle into it, so it replaces every organization, user, campaign and mailbox currently on the instance. It prints what the bundle holds and asks you to type restore before it does; --yes skips that for scripts.

Before anything is written it compares the bundle's CREDENTIALS_ENCRYPTION_KEY and KMS_LOCAL_MASTER_KEY against this host's, and refuses to continue when they differ, printing the two lines to put in .env first. That check is the point of the command: without it a restore looks like it worked, and every mailbox fails to authenticate days later with no error that names the cause.

Blobs are unpacked over the blob root additively: files the bundle knows about are overwritten, anything else is left alone.

Data control walks the whole move to a new host.

org list

docker compose -p sendsets exec backend sendsetsctl org list

Prints every workspace with its id, name, owner email, and member, mailbox and contact counts. It exists so the next two commands have something to name: --org accepts the id, the slug, or the owner's email, whichever you have to hand.

org export

docker compose -p sendsets exec backend sendsetsctl org export \
  --org you@example.com --out /tmp/workspace.sendsets.zip

Writes one workspace to a single archive file: the organization, its members and roles, mailboxes, campaigns, sequences, contacts, suppression, CRM, inbox history, and the send state that stops a migrated mailbox from sending twice its daily volume on the day it moves. It is the same archive the dashboard produces under Settings > Data, so either side of a migration can use either tool. The admin panel now offers the same for any organization under Instance > Transfers.

sendsetsctl org export --help prints the group list. core is always included; inbox, sending, events and logs are the ones that grow without limit, so dropping them is how you get a small archive that still rebuilds a working workspace.

Without --with-credentials the credential fields travel empty and every mailbox arrives on the destination needing a reconnect. Everything else moves either way.

Progress goes to stderr and the archive to the file, so --out - streams cleanly:

sendsetsctl org export --org you@example.com --out - | ssh newhost 'cat > /tmp/workspace.zip'

org import

docker compose -p sendsets exec backend sendsetsctl org import \
  --org you@example.com --file /tmp/workspace.sendsets.zip --dry-run

Applies an archive to a workspace on this instance. It always prints what the archive holds, which rows already exist here, and which members have no account, before writing anything.

Run it with --dry-run first. The report is the same preflight the dashboard shows, and it costs nothing. The admin panel offers the same import, preflight included, under Instance > Transfers.

The whole import runs in one transaction: if any part fails, nothing lands and the workspace is untouched. Members are matched to accounts on this instance by email address, and anyone without one has their rows reassigned to the workspace owner, named in the report before you commit. An archive carries no password material, so it can never create an account here.

org export and org import are the per-workspace tool and backup is the instance-level one. They are not interchangeable: a bundle cannot be applied to one workspace, and a workspace archive cannot restore an instance.

Billing history, plan overrides, worker placement, mailbox sync checkpoints and warmup pool membership are exported for the record but never applied: each belongs to the instance rather than to the workspace. Export and import has the full table.

The API commands

Everything in this section talks to the public REST API with an API key, so it runs from anywhere: your laptop, a CI job, an agent's sandbox. It needs no database access and works against the hosted service and self-hosted instances alike.

export SENDSETS_API_KEY=ssk_...                       # Settings > API keys
export SENDSETS_API_URL=https://api.your-instance.com  # omit for the hosted service

sendsetsctl me                 # who the key is, and its scopes
sendsetsctl campaign list
sendsetsctl campaign start --id <uuid>

Every command prints the API's JSON response to stdout, untouched, and exits 1 on failure with the API's own code and request_id on stderr. What a key can do is exactly its granted permissions; sendsetsctl me shows them.

The families

sendsetsctl <family> --help lists a family's subcommands, and sendsetsctl <family> <subcommand> --help prints its flags and the endpoint it calls.

The raw passthrough

Anything the API can do that has no typed command yet is one api call away, so nothing is out of reach:

sendsetsctl api get "/campaigns?limit=10"
sendsetsctl api post /contacts --data '{"email":"jane@example.com"}'
sendsetsctl api patch "/campaigns/<id>" --data @changes.json
sendsetsctl api delete "/webhooks/<id>"

Paths are relative to /v1. --data takes a JSON literal, - for stdin, or @file.

Conventions

• List responses are {"data": [...], "pagination": {"next_cursor", "has_more"}}. Page with --cursor until has_more is false; the cursor is opaque.
• Writes accept --idempotency-key, and a retried command with the same key can never double-apply. Details on authentication.
• A 429 failure names its Retry-After; wait it out and retry.
• contact list is a search: --data carries the filter body, and omitting it lists everything.

For AI agents

The repository ships skills under skills/ (sendsets-cli for the sendsets CLI, sendsets-api for the same product surface through sendsetsctl, sendsets-ops for instance administration, sendsets-install for standing an instance up and moving it) that teach a coding agent these commands, the conventions above, and the sending-safety rules. Install them the way your agent expects, for example cp -r skills/sendsets-api ~/.claude/skills/ for Claude Code, or point the agent at the SKILL.md directly. The sendsets-cli skill is also served at https://sendsets.vercel.app/skills/sendsets-cli/SKILL.md, and https://sendsets.vercel.app/claude.md is the one-page install and sign-in walkthrough an agent can follow without a checkout. An agent given a scoped key and those skills can operate a workspace end to end without touching the database.

When Redis is down

Account recovery must not depend on the cache, so most commands treat an unreachable Redis as a warning and carry on.

Make targets

Every one of these runs sendsetsctl inside the backend container of a compose install.

See also

• First run for claiming a fresh instance and provisioning the owner unattended
• Accounts and access for registration modes, invitations, login codes and single sign-on
• Instance health for every check status can report
• Troubleshooting for symptoms and the command that fixes each one
• Export and import for what an archive contains and what deliberately does not travel
• Configuration reference for every variable named here
• API authentication and permissions for the keys and scopes the API commands run on

fleet

Manages the machines running SendSets. Every process on a machine you own is a node: a worker sends and syncs mail, a consumer processes events. Both enrol with a token, heartbeat, and pull the version the control plane tells them to run.

Adding a machine is two commands:

sendsetsctl fleet join-token

Then on the machine itself:

curl -fsSL https://<your-instance>/join.sh | sh -s -- \
  --url https://<your-instance> --token <token> --role worker

The token is shown once. Issuing another revokes the previous one; machines that already joined are unaffected.

sendsetsctl fleet list

ROLE      NAME      STATE  VERSION           REGION      MEM    SEEN     ID
worker    box-1     live   v1.4.2            eu-central  128MB  12s ago  de434ce4-...
consumer  events-1  live   v1.0.0 -> v1.4.2  -           96MB   30s ago  2b334317-...

STATE is live, unreachable (enrolled but silent) or stopped. A version shown as a -> b has not picked up the target yet. --role worker narrows it; --json is machine-readable.

Moving the fleet:

sendsetsctl fleet version              # what the fleet should be on
sendsetsctl fleet version v1.4.2       # move everything to a tag
sendsetsctl fleet channel stable       # follow releases again
sendsetsctl fleet pin <node-id> v1.4.1 # hold or canary one machine
sendsetsctl fleet pin <node-id>        # clear that pin

Setting a tag also pins the channel, so a release landing later does not undo a deliberate rollback.

sendsetsctl fleet remove <node-id>

Forgets a node. Any mailboxes it carried are re-placed within a few minutes. It does not stop the process: a machine still running re-joins on its next heartbeat, so stop the service there too.