CLI Overview

AutoROICalc includes backend command line tools for self-deployed and on-premise installations. They are intended for administrators who run the API/backend server and need to provision databases, manage identities, create records, inspect tokens, run scheduled jobs, or perform operational maintenance without using the web UI.

Run these commands from the backend project directory in the same environment that runs the API, with the normal database and application environment variables loaded.

For trusted operators only

CLI commands can create users, write records, expose service tokens, delete identities, and run backups. Use them only on trusted servers and avoid pasting secrets into shared terminals, shell history, tickets, or screenshots.

Command Files

File	Purpose
`db_cli.py`	Database setup, service tokens, listings, service plans, and backups.
`identity_cli.py`	Identity/user registration, verification, database assignment, token reassignment, and plan changes.
`record_cli.py`	Add, query, update, and delete records for a specific identity.
`report_cli.py`	Add, update, delete, calculate, and render reports for a specific identity.
`automation_cli.py`	Run scheduled email reports, report automation, imports, and cleanup jobs.
`auth_cli.py`	Log a user out of all sessions.
`email_cli.py`	Send or save operational email smoke tests and admin usage emails.

Database Setup

Initialize or update the system databases and required tables:

python3 db_cli.py --setup

Set the default service-plan limits:

python3 db_cli.py --service-plans-set-default

List identities and related operational tables:

python3 db_cli.py --list-users --limit 50 --offset 0
python3 db_cli.py --list-service-plans
python3 db_cli.py --list-service-plan-limits
python3 db_cli.py --list-user-settings --identity-id 123
python3 db_cli.py --list-audit-log --identity-id 123

Users and Identities

Register a user from the backend:

python3 identity_cli.py --register \
  --email admin@example.com \
  --user-name admin \
  --password 'change-this-password'

List identities:

python3 identity_cli.py --list --limit 50 --offset 0

Inspect identity-related records for one user:

python3 identity_cli.py --audit --identity-id 123

Verify an email address with an existing verification token:

python3 identity_cli.py --verify-email EMAIL_VERIFICATION_TOKEN

Assign an existing user database to an identity:

python3 identity_cli.py --assign-database \
  --identity-id 123 \
  --database-name rms_123_example

Rename a user database:

python3 identity_cli.py --rename-database \
  --old-name rms_11_oldname \
  --new-name rms_123_example

Change a user's service plan:

python3 identity_cli.py --set-plan Premium --identity-id 123
python3 identity_cli.py --get-plan 123

Delete an identity:

python3 identity_cli.py --delete 123

Service and Web Tokens

Create tokens for an identity that already has a user database:

python3 db_cli.py --create-service-token 123
python3 db_cli.py --create-web-token 123

Read tokens for an identity:

python3 db_cli.py --get-service-token 123
python3 db_cli.py --get-web-token 123

Set a known token value for an identity and database:

python3 identity_cli.py --set-service-token \
  --identity-id 123 \
  --database-name rms_123_example \
  --token 'SERVICE_TOKEN_VALUE'

python3 identity_cli.py --set-web-token \
  --identity-id 123 \
  --database-name rms_123_example \
  --token 'WEB_TRACKING_TOKEN_VALUE'

Reassign an existing service token after moving a user to a new identity or database:

python3 identity_cli.py --reassign-service-token \
  --token 'SERVICE_TOKEN_VALUE' \
  --old-identity-id 11 \
  --new-identity-id 123 \
  --old-db-name rms_11_oldname \
  --new-db-name rms_123_example

Records

Record commands require --identity-id. The CLI uses that identity to find the user's database.

Add one record:

python3 record_cli.py --identity-id 123 --add '{
  "date": "2026-09-15",
  "time": "14:30:00",
  "type": "sale",
  "activity": "closed",
  "desc": "Order paid",
  "source": ["woocommerce"],
  "tags": ["ecommerce", "paid-order"],
  "value": 129.9,
  "custom_data": {
    "order_id": "100045"
  },
  "raw_data": {
    "provider": "woocommerce"
  }
}'

Add several records:

python3 record_cli.py --identity-id 123 --add-many '[
  {
    "date": "2026-09-15",
    "time": "14:30:00",
    "type": "sale",
    "activity": "closed",
    "desc": "Order paid",
    "source": ["woocommerce"],
    "tags": ["ecommerce"],
    "value": 129.9
  },
  {
    "date": "2026-09-15",
    "time": "15:10:00",
    "type": "lead",
    "activity": "open",
    "desc": "Pricing form submitted",
    "source": ["website"],
    "tags": ["lead", "pricing"],
    "value": 1
  }
]'

Read records:

python3 record_cli.py --identity-id 123 --get 456
python3 record_cli.py --identity-id 123 --get-many --offset 0 --limit 25
python3 record_cli.py --identity-id 123 --get-total

Filter records:

python3 record_cli.py --identity-id 123 --get-many --filter '{
  "types": ["sale"],
  "sources": ["woocommerce"],
  "tags": ["ecommerce"]
}'

Update a record. Include the record id in the JSON payload:

python3 record_cli.py --identity-id 123 --update '{
  "id": 456,
  "date": "2026-09-15",
  "time": "14:30:00",
  "type": "sale",
  "activity": "closed",
  "desc": "Order paid and fulfilled",
  "source": ["woocommerce"],
  "tags": ["ecommerce", "paid-order", "fulfilled"],
  "value": 129.9
}'

Delete records:

python3 record_cli.py --identity-id 123 --delete 456
python3 record_cli.py --identity-id 123 --delete-many '[456, 457, 458]'

List known record types and sources:

python3 record_cli.py --identity-id 123 --get-types
python3 record_cli.py --identity-id 123 --get-sources

Reports

Calculate report data from a report configuration JSON payload:

python3 report_cli.py --identity-id 123 --calc '{
  "name": "Revenue report",
  "recordType": "sale",
  "recordSources": ["woocommerce"]
}'

Get a saved report configuration:

python3 report_cli.py --identity-id 123 --get-config 789

Delete a report:

python3 report_cli.py --identity-id 123 --delete 789

Automation Jobs

Run backend automations manually, or call them from cron/systemd timers in self-hosted deployments.

python3 automation_cli.py --do-email-reporting
python3 automation_cli.py --do-report-automation
python3 automation_cli.py --do-ga4-imports
python3 automation_cli.py --do-gsc-imports
python3 automation_cli.py --do-fb-imports
python3 automation_cli.py --cleanup

For testing schedule behavior, override the current time:

python3 automation_cli.py --do-email-reporting --force-current-time 08:00

Generate dashboard email HTML without sending it:

python3 automation_cli.py --do-email-reporting --save-to /tmp/autoroicalc-email-preview

Backups

Run built-in backup tasks from the backend environment:

python3 db_cli.py --backup

Sessions and Email Smoke Tests

Log a user out of all sessions:

python3 auth_cli.py --logout --user-id 123

Save email smoke-test HTML instead of sending it:

python3 email_cli.py --test-send-notif-email-new-registration --save-to /tmp/new-registration-email.html
python3 email_cli.py --send-admin-usage-overview --save-to /tmp/usage-overview.html
python3 email_cli.py --test-send-sample-report-email admin@example.com --save-to /tmp/sample-report-email.html

Send a transaction verification email test for an identity that has a verification token:

python3 email_cli.py --test-send-tx-verify-email 123

Operational Notes

Prefer running commands as the same OS user and environment used by the backend service.
Use python3 on Linux hosts unless your deployment uses a different Python executable.
Keep JSON payloads in files or protected shell scripts for repeatable production operations.
Check command exit codes in cron jobs and deployment scripts.
Use the API reference for public HTTP integrations; use these CLI tools for trusted backend administration.

API Overview Service Token API Records Overview