Skip to content
ReputeCastReputeCast Docs

CLI reference

Reference
For:
Server operators, Developers

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.

Usage
reputecast serve [--role <roles>] [--addr <address>] [--auto-migrate] [--auto-install]
FlagTypeDefaultDescription
--rolestring—Comma-separated roles to run: web, worker, ingest. Without it, the roles config key applies (all three by default).
--addrstring—Listen address. Without it, http.addr applies (:8080 by default).
--auto-migrateboolfalseApply pending migrations at start. The default comes from REPUTECAST_AUTO_MIGRATE when it is set.
--auto-installboolfalseCreate 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.

Terminal window
reputecast serve

Serve the web app, API and provider webhooks only; run the workers in another process.

Terminal window
reputecast serve --role=web,ingest

What the Docker image runs at start.

Terminal window
reputecast serve --auto-migrate --auto-install

reputecast 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.

Usage
reputecast worker

Start a worker process next to processes that run serve --role=web,ingest.

Terminal window
reputecast worker

reputecast migrate

Section titled “reputecast migrate”

Manage the database schema.

Usage
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.

Usage
reputecast migrate up

Apply migrations after replacing the binary with a new version.

Terminal window
reputecast migrate up

reputecast migrate down

Section titled “reputecast migrate down”

Roll back the latest migration.

Rolls back one migration only. Run it again to roll back further.

Usage
reputecast migrate down

Roll back the most recent migration.

Terminal window
reputecast migrate down

reputecast 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.

Usage
reputecast migrate status

Check for pending migrations before an upgrade.

Terminal window
reputecast migrate status

reputecast 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.

Usage
reputecast install [--email <address>] [--name <name>] [--password <password>]
FlagTypeDefaultDescription
--emailstring—Owner email. Without it, REPUTECAST_ADMIN_EMAIL is used; one of them is required.
--namestring—Owner name. Without it, REPUTECAST_ADMIN_NAME is used.
--passwordstring—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.

Terminal window
reputecast install --email [email protected] --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)".

Usage
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.

Usage
reputecast user reset-password --email <address> [--password <password>]
FlagTypeDefaultDescription
--emailstring—Account email. Required.
--passwordstring—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.

Terminal window
reputecast user reset-password --email [email protected]

reputecast 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.

Usage
reputecast user reset-2fa --email <address> --reason <text>
FlagTypeDefaultDescription
--emailstring—Account email. Required.
--reasonstring—Why the reset is needed. Required; written to the audit log.

Reset two-factor authentication for a person who lost their phone.

Terminal window
reputecast user reset-2fa --email [email protected] --reason "lost phone, verified by video call"

reputecast user make-admin

Section titled “reputecast user make-admin”

Make an account an instance admin.

Usage
reputecast user make-admin --email <address>
FlagTypeDefaultDescription
--emailstring—Account email. Required.

Give an existing account access to Instance admin.

Terminal window
reputecast user make-admin --email [email protected]

reputecast user unlock

Section titled “reputecast user unlock”

Clear a sign-in lockout.

Usage
reputecast user unlock --email <address>
FlagTypeDefaultDescription
--emailstring—Account email. Required.

Let a locked-out person sign in again without waiting for the lockout to end.

Terminal window
reputecast user unlock --email [email protected]

reputecast 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.

Usage
reputecast seed [--sample <acme|northwind>] [--force]
FlagTypeDefaultDescription
--samplestringacmeWhich sample to load: acme, or northwind (an agency with seven clients, into an empty database).
--forceboolfalseSeed even when REPUTECAST_ENV is not development.

Load the Acme sample.

Terminal window
REPUTECAST_ENV=development reputecast seed

Load the agency sample into an empty database.

Terminal window
REPUTECAST_ENV=development reputecast seed --sample northwind

reputecast demo

Section titled “reputecast demo”

Development helpers for the Acme demo.

Refuses to run unless REPUTECAST_ENV is development.

Usage
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.

Usage
reputecast demo send "<campaign>" [flags]
FlagTypeDefaultDescription
--scenariostringnormalnormal; 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).
--workspacestringacme-newsletterWorkspace slug.
--elapsedduration0sStart the send this long ago and send that part at once with back-dated times, so the monitor opens mid-send.
--ab-windowduration7mHow long the A/B test runs before the winner goes to the rest.
--resetboolfalseClear 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.

Terminal window
REPUTECAST_ENV=development reputecast demo send "Weekly Digest

Show an auto-pause caused by Outlook complaints.

Terminal window
REPUTECAST_ENV=development reputecast demo send "Weekly Digest

Show a provider outage with a held share.

Terminal window
REPUTECAST_ENV=development reputecast demo send "Weekly Digest

reputecast 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.

Usage
reputecast openapi [--yaml]
FlagTypeDefaultDescription
--yamlboolfalsePrint YAML instead of JSON.

Save the API description to generate a client.

Terminal window
reputecast openapi > openapi.json

Save it as YAML.

Terminal window
reputecast openapi --yaml > openapi.yaml

reputecast secrets

Section titled “reputecast secrets”

Manage the key that encrypts credentials at rest.

Usage
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.

Usage
reputecast secrets generate-key

Create a key to set as REPUTECAST_SECRETS__KEY instead of using a key file.

Terminal window
reputecast secrets generate-key

reputecast 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.

Usage
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.

Usage
reputecast adapter list

See which adapters are installed and how many providers use each.

Terminal window
reputecast adapter list

reputecast 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.

Usage
reputecast adapter install <manifest-url-or-file> [--url <address>]
FlagTypeDefaultDescription
--urlstring—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.

Terminal window
reputecast adapter install https://raw.githubusercontent.com/you/example-esp-adapter/main/manifest.json --url http://example-esp:4600

Install from a local file, for an adapter running on the same machine.

Terminal window
reputecast adapter install ./manifest.json --url http://127.0.0.1:4600

reputecast adapter set-url

Section titled “reputecast adapter set-url”

Set where an adapter's process listens.

Usage
reputecast adapter set-url <id> <url>

Point ReputeCast at the adapter's address.

Terminal window
reputecast adapter set-url example-esp http://example-esp:4600

reputecast 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.

Usage
reputecast adapter secret <id>

Rotate the adapter's signing secret.

Terminal window
reputecast adapter secret example-esp

reputecast adapter check

Section titled “reputecast adapter check”

Call an adapter's health operation and record the result.

Usage
reputecast adapter check <id>

Confirm that ReputeCast can reach the adapter with its signing secret.

Terminal window
reputecast adapter check example-esp

reputecast adapter remove

Section titled “reputecast adapter remove”

Uninstall an adapter that no connected provider uses.

Usage
reputecast adapter remove <id>

Remove an adapter after disconnecting the providers that use it.

Terminal window
reputecast adapter remove example-esp

reputecast version

Section titled “reputecast version”

Print the version.

Prints the version, the first 12 characters of the commit and the Go version.

Usage
reputecast version

Check which version is installed.

Terminal window
reputecast version

Global flags

Section titled “Global flags”

These flags work with every command.

FlagTypeDefaultDescription
--configstring—Path to a YAML config file. Without it, ReputeCast reads the file named in REPUTECAST_CONFIG, if any.
--database-urlstring—PostgreSQL connection URL. Overrides database.url from the config file, REPUTECAST_DATABASE__URL and DATABASE_URL.
--log-levelstring—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>.

Section titled “Related”
Report a problem with this pageReputeCast websiteHostReputeContent licensed under CC BY 4.0