CLI reference
This page lists every command of the reputecast CLI, the single binary that runs the server, the workers and the maintenance tasks.
In the Docker image, run a command inside the app container: docker compose exec app /usr/local/bin/reputecast <command>. Configuration comes from the same sources as reputecast serve (see configure ReputeCast), so pass --config or the REPUTECAST_* variables the server uses.
reputecast serve
Section titled “reputecast serve”Run the web app, API, webhook ingest and workers.
By default one process runs every role. Use --role to split the roles across processes, for example several web and ingest nodes behind a load balancer and one worker. Without --auto-migrate, pending migrations only log a warning. Processes with the web role also run the SMTP relay once an instance admin turns it on.
reputecast serve [--role <roles>] [--addr <address>] [--auto-migrate] [--auto-install]| Flag | Type | Default | Description |
|---|---|---|---|
--role | string | — | Comma-separated roles to run: web, worker, ingest. Without it, the roles config key applies (all three by default). |
--addr | string | — | Listen address. Without it, http.addr applies (:8080 by default). |
--auto-migrate | bool | false | Apply pending migrations at start. The default comes from REPUTECAST_AUTO_MIGRATE when it is set. |
--auto-install | bool | false | Create the first Owner when the database has no users, from REPUTECAST_ADMIN_EMAIL, REPUTECAST_ADMIN_NAME and REPUTECAST_ADMIN_PASSWORD, and print the sign-in details to the log. The default comes from REPUTECAST_AUTO_INSTALL when it is set. |
Run every role in one process.
reputecast serveServe the web app, API and provider webhooks only; run the workers in another process.
reputecast serve --role=web,ingestWhat the Docker image runs at start.
reputecast serve --auto-migrate --auto-installreputecast worker
Section titled “reputecast worker”Run only the background workers.
Same as serve --role=worker. Runs sends, event processing, syncs and scheduled jobs. It opens no HTTP listener, except the metrics server when metrics.addr is set, and does not apply migrations. Run at least one worker per instance.
reputecast workerStart a worker process next to processes that run serve --role=web,ingest.
reputecast workerreputecast migrate
Section titled “reputecast migrate”Manage the database schema.
reputecast migrate <up|down|status>reputecast migrate up
Section titled “reputecast migrate up”Apply all pending migrations.
Applies ReputeCast's migrations, then the job queue's, and prints Database is up to date.
reputecast migrate upApply migrations after replacing the binary with a new version.
reputecast migrate upreputecast migrate down
Section titled “reputecast migrate down”Roll back the latest migration.
Rolls back one migration only. Run it again to roll back further.
reputecast migrate downRoll back the most recent migration.
reputecast migrate downreputecast migrate status
Section titled “reputecast migrate status”List migrations and whether they are applied.
Prints the columns VERSION, APPLIED and FILE. APPLIED shows the date and time a migration ran, or pending.
reputecast migrate statusCheck for pending migrations before an upgrade.
reputecast migrate statusreputecast install
Section titled “reputecast install”Migrate the database and create the first Owner.
Applies migrations and creates the first Owner: an instance admin whose password sign-in keeps working when an SSO domain is enforced. Without --password, it prints a temporary password that must be replaced at first sign-in, where the Owner also adds a passkey or authenticator app, saves recovery codes, confirms the public URL and creates the first workspace. Fails when the database already has users.
reputecast install [--email <address>] [--name <name>] [--password <password>]| Flag | Type | Default | Description |
|---|---|---|---|
--email | string | — | Owner email. Without it, REPUTECAST_ADMIN_EMAIL is used; one of them is required. |
--name | string | — | Owner name. Without it, REPUTECAST_ADMIN_NAME is used. |
--password | string | — | Owner password. Without it, REPUTECAST_ADMIN_PASSWORD is used, and when neither is set a temporary password is printed. A password you set must meet auth.password_min_length. |
Create the first Owner and print a temporary password.
reputecast install --email linh@acme.io --name "Linh Nguyen"reputecast user
Section titled “reputecast user”Manage accounts from the server.
Works without a sending provider, so you can recover access before email is set up. Each action is written to the audit log with the actor "CLI (server)".
reputecast user <command> --email <address>reputecast user reset-password
Section titled “reputecast user reset-password”Print a one-time password reset link.
Prints a link that lets the person set a new password. It works once and expires in 15 minutes, and their current password keeps working until they use it. Deactivated accounts are refused. With --password, the password is set directly instead and every session of the account is signed out.
reputecast user reset-password --email <address> [--password <password>]| Flag | Type | Default | Description |
|---|---|---|---|
--email | string | — | Account email. Required. |
--password | string | — | Set this password directly instead of printing a reset link. It must meet auth.password_min_length. |
Print a reset link to send to the person privately.
reputecast user reset-password --email aisha@acme.ioreputecast user reset-2fa
Section titled “reputecast user reset-2fa”Remove an account's authenticator app and recovery codes.
Passkeys stay. The person gets 72 hours to set up two-factor authentication again, and every session of the account is signed out. The reason is required and is written to the audit log.
reputecast user reset-2fa --email <address> --reason <text>| Flag | Type | Default | Description |
|---|---|---|---|
--email | string | — | Account email. Required. |
--reason | string | — | Why the reset is needed. Required; written to the audit log. |
Reset two-factor authentication for a person who lost their phone.
reputecast user reset-2fa --email aisha@acme.io --reason "lost phone, verified by video call"reputecast user make-admin
Section titled “reputecast user make-admin”Make an account an instance admin.
reputecast user make-admin --email <address>| Flag | Type | Default | Description |
|---|---|---|---|
--email | string | — | Account email. Required. |
Give an existing account access to Instance admin.
reputecast user make-admin --email aisha@acme.ioreputecast user unlock
Section titled “reputecast user unlock”Clear a sign-in lockout.
reputecast user unlock --email <address>| Flag | Type | Default | Description |
|---|---|---|---|
--email | string | — | Account email. Required. |
Let a locked-out person sign in again without waiting for the lockout to end.
reputecast user unlock --email aisha@acme.ioreputecast seed
Section titled “reputecast seed”Load demo data for development and screenshots.
Applies migrations, then loads a sample instance. The Acme sample has Acme Newsletter with 48,213 subscribers, Amazon SES, Postmark and a warming Postal server, campaigns, automations, a team and audit history. The demo accounts and their password are printed at the end. Refuses to run unless REPUTECAST_ENV is development.
reputecast seed [--sample <acme|northwind>] [--force]| Flag | Type | Default | Description |
|---|---|---|---|
--sample | string | acme | Which sample to load: acme, or northwind (an agency with seven clients, into an empty database). |
--force | bool | false | Seed even when REPUTECAST_ENV is not development. |
Load the Acme sample.
REPUTECAST_ENV=development reputecast seedLoad the agency sample into an empty database.
REPUTECAST_ENV=development reputecast seed --sample northwindreputecast demo
Section titled “reputecast demo”Development helpers for the Acme demo.
Refuses to run unless REPUTECAST_ENV is development.
reputecast demo <command>reputecast demo send
Section titled “reputecast demo send”Send a demo campaign through the simulated providers so the live monitor moves.
Starts the named campaign's send through the demo transport: nothing leaves the machine, and delivery, bounces, complaints, opens and clicks are simulated. The running server's worker sends it in real time, so start the server first. Only workspaces whose providers are all demo providers can send.
reputecast demo send "<campaign>" [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--scenario | string | normal | normal; outlook-complaints (lapsed Outlook readers complain until the Outlook share auto-pauses); or postal-outage (Postal refuses connections 14 minutes in and its share is held). |
--workspace | string | acme-newsletter | Workspace slug. |
--elapsed | duration | 0s | Start the send this long ago and send that part at once with back-dated times, so the monitor opens mid-send. |
--ab-window | duration | 7m | How long the A/B test runs before the winner goes to the rest. |
--reset | bool | false | Clear an earlier send of the campaign first, including what it changed outside the campaign (provider statistics, suppressions from its bounces). |
Open the live monitor 20 minutes into a normal send.
REPUTECAST_ENV=development reputecast demo send "Weekly DigestShow an auto-pause caused by Outlook complaints.
REPUTECAST_ENV=development reputecast demo send "Weekly DigestShow a provider outage with a held share.
REPUTECAST_ENV=development reputecast demo send "Weekly Digestreputecast openapi
Section titled “reputecast openapi”Print the OpenAPI 3.1 document of the REST API.
Prints indented JSON by default. Needs no database or configuration.
reputecast openapi [--yaml]| Flag | Type | Default | Description |
|---|---|---|---|
--yaml | bool | false | Print YAML instead of JSON. |
Save the API description to generate a client.
reputecast openapi > openapi.jsonSave it as YAML.
reputecast openapi --yaml > openapi.yamlreputecast secrets
Section titled “reputecast secrets”Manage the key that encrypts credentials at rest.
reputecast secrets <command>reputecast secrets generate-key
Section titled “reputecast secrets generate-key”Print a new random key for REPUTECAST_SECRETS__KEY.
Prints 32 random bytes as standard base64. Needs no database or configuration.
reputecast secrets generate-keyCreate a key to set as REPUTECAST_SECRETS__KEY instead of using a key file.
reputecast secrets generate-keyreputecast adapter
Section titled “reputecast adapter”Install community adapters and tell ReputeCast where they run.
Community adapters run in their own process and speak the adapter protocol. Install one from its manifest, run its process with the signing secret ReputeCast prints, and check it. Adapter addresses on loopback or private networks need providers.allow_private_networks.
reputecast adapter <command>reputecast adapter list
Section titled “reputecast adapter list”List installed community adapters, where they run and their last check.
Prints the columns ADAPTER, VERSION, ADDRESS, SECRET ISSUED, LAST CHECK and CONNECTED.
reputecast adapter listSee which adapters are installed and how many providers use each.
reputecast adapter listreputecast adapter install
Section titled “reputecast adapter install”Install a community adapter from its manifest.json, or update it when its id is already installed.
Reads the manifest from an https:// URL on a public address (redirects are not followed) or from a local file, up to 256 KiB. On a first install, ReputeCast prints the adapter's signing secret once: set it on the adapter process as REPUTECAST_ADAPTER_SECRET.
reputecast adapter install <manifest-url-or-file> [--url <address>]| Flag | Type | Default | Description |
|---|---|---|---|
--url | string | — | Where the adapter process listens, like http://example-esp:4600. If you omit it, set it later with adapter set-url. |
Install from a published manifest.
reputecast adapter install https://raw.githubusercontent.com/you/example-esp-adapter/main/manifest.json --url http://example-esp:4600Install from a local file, for an adapter running on the same machine.
reputecast adapter install ./manifest.json --url http://127.0.0.1:4600reputecast adapter set-url
Section titled “reputecast adapter set-url”Set where an adapter's process listens.
reputecast adapter set-url <id> <url>Point ReputeCast at the adapter's address.
reputecast adapter set-url example-esp http://example-esp:4600reputecast adapter secret
Section titled “reputecast adapter secret”Issue a new signing secret for an adapter and print it once.
The previous secret keeps working for 24 hours, so you can update the adapter process without downtime: it accepts several comma-separated secrets in REPUTECAST_ADAPTER_SECRET.
reputecast adapter secret <id>Rotate the adapter's signing secret.
reputecast adapter secret example-espreputecast adapter check
Section titled “reputecast adapter check”Call an adapter's health operation and record the result.
reputecast adapter check <id>Confirm that ReputeCast can reach the adapter with its signing secret.
reputecast adapter check example-espreputecast adapter remove
Section titled “reputecast adapter remove”Uninstall an adapter that no connected provider uses.
reputecast adapter remove <id>Remove an adapter after disconnecting the providers that use it.
reputecast adapter remove example-espreputecast version
Section titled “reputecast version”Print the version.
Prints the version, the first 12 characters of the commit and the Go version.
reputecast versionCheck which version is installed.
reputecast versionGlobal flags
Section titled “Global flags”These flags work with every command.
| Flag | Type | Default | Description |
|---|---|---|---|
--config | string | — | Path to a YAML config file. Without it, ReputeCast reads the file named in REPUTECAST_CONFIG, if any. |
--database-url | string | — | PostgreSQL connection URL. Overrides database.url from the config file, REPUTECAST_DATABASE__URL and DATABASE_URL. |
--log-level | string | — | Log level: debug, info, warn or error. Overrides log.level. |
Exit codes
Section titled “Exit codes”| Code | Meaning |
|---|---|
0 |
The command succeeded. |
1 |
The command failed: a database, network or configuration error, an unknown flag or a wrong number of arguments. |
2 |
ReputeCast refused the request before doing anything: user reset-2fa without --reason, a --password that breaks the password policy, an unknown seed --sample, or seed (without --force) or demo send outside REPUTECAST_ENV=development. |
Every error is printed to standard error as Error: <message>.
Related
Section titled “Related”- Install the binary runs
reputecast installandreputecast serveunder systemd. - Recover access from the command line walks through the
usercommands. - Scale with web, ingest and worker roles explains
serve --roleandworker. - Write a community adapter uses the
adaptercommands. - Configuration reference lists every key the
--configfile and environment variables set.