Skip to content

CLI reference

The binary is the CLI. In development run commands from source with go run ./cmd/app <command>; a built binary runs them as ims <command>. Global flags work with every command.

Global flags

Flag Default Description
--env-file — path to the env file (default: APP_ENV_FILE or .env)
--verbose — enable debug logging

Commands

Command Description
backup:clean Apply the retention policy to stored backups
backup:list List recent backup runs
backup:monitor Check backup freshness and storage usage
backup:run Create a database backup archive
billing:expire-subscriptions Mark overdue subscriptions as expired
billing:send-renewal-reminders Log renewal reminders for subscriptions expiring within 7/3/1 days
cache:clear Clear the configured cache store
config:show Print the effective configuration
data-processing:cleanup-completed Delete completed processing-job records older than the retention window
db:seed Seed permissions, tenant/roles/admin, settings groups/globals and feature flags
dev-dashboard:prune Delete developer dashboard telemetry past its retention window
feature-flags:sync Insert missing global feature flags with their catalog defaults
gen docs Generate the reference pages of the documentation site
gen module Scaffold a CRUD module from a declarative field spec
gen openapi Refresh the generated regions of api/openapi.yaml
health:check Run application health checks
migrate Apply all pending database migrations
migrate:rollback Roll back the most recent migrations
migrate:status Show migration status
openapi:check Validate the OpenAPI document and check for route drift
permission:sync Sync the permission catalog into the database
queue:stats Show queue depths and failed counts
queue:work Start a queue worker (River)
schedule Run the scheduler daemon (one process per deployment)
schedule:list List registered scheduled tasks
schedule:run Run a scheduled task once, immediately
serve Start the HTTP API server
settings:sync Upsert settings groups and insert missing global settings
version Print the build version

backup:clean

Apply the retention policy to stored backups.

Terminal window
ims backup:clean [flags]
Flag Default Description
--dry-run — report what would be deleted without deleting

backup:list

List recent backup runs.

Terminal window
ims backup:list [flags]
Flag Default Description
--limit 20 maximum runs to list

backup:monitor

Check backup freshness and storage usage.

Terminal window
ims backup:monitor

backup:run

Create a database backup archive.

Terminal window
ims backup:run [flags]
Flag Default Description
--destinations — comma-separated destinations (local is always included)
--filename — archive filename override
--with-files — include BACKUP_FILES_PATHS in the archive

billing:expire-subscriptions

Mark overdue subscriptions as expired.

Terminal window
ims billing:expire-subscriptions

billing:send-renewal-reminders

Log renewal reminders for subscriptions expiring within 7/3/1 days.

Terminal window
ims billing:send-renewal-reminders

cache:clear

Clear the configured cache store.

Terminal window
ims cache:clear [flags]
Flag Default Description
--store — override the cache driver (memory|file|redis|database)

config:show

Print the effective configuration.

Terminal window
ims config:show

data-processing:cleanup-completed

Delete completed processing-job records older than the retention window.

Terminal window
ims data-processing:cleanup-completed [flags]
Flag Default Description
--days 0 retention window in days (default: data_processing_job.cleanup_days setting)
--dry-run — report how many jobs would be deleted

db:seed

Seed permissions, tenant/roles/admin, settings groups/globals and feature flags.

Terminal window
ims db:seed [flags]
Flag Default Description
--force — Allow seeding in production (with safeguards)

dev-dashboard:prune

Delete developer dashboard telemetry past its retention window.

Terminal window
ims dev-dashboard:prune

feature-flags:sync

Insert missing global feature flags with their catalog defaults.

Terminal window
ims feature-flags:sync

gen docs

Render docs/reference/{cli,configuration,permissions,make}.md from the code: the command tree, .env.example, the permission catalog and the Makefile. With —check nothing is written and the command fails when a committed page is stale (CI).

Terminal window
ims gen docs [flags]

Examples:

Terminal window
ims gen docs
ims gen docs --check
Flag Default Description
--check — fail when a generated page is stale instead of writing it
--root . repository root

gen module

Generate a goose migration, sqlc queries and a feature-first module package from a field spec. Non-interactive and CI-friendly.

Terminal window
ims gen module [flags]

Examples:

Terminal window
ims gen module --name=product --fields="name:string,price:decimal,is_active:bool"
ims gen module --name=product --fields="name:string,notes:text?" --dry-run
Flag Default Description
--dry-run — print the files without writing them
--fields — comma-separated name:type spec, e.g. name:string,notes:text?
--force — overwrite existing files
--module — go module path (default: read from go.mod)
--name — module name, lower_snake, singular (required)
--no-openapi — skip refreshing the generated OpenAPI regions
--no-sqlc — skip the automatic sqlc generate step
--package — go package name (default: —name)
--root . repository root
--table — table name (default: naive plural of —name)

gen openapi

Insert or update the generated paths and schemas for one module (—module), every module in the index (—all), or insert the empty marker regions (—init). Managed regions are owned by the tool; everything outside the markers is hand-written and never touched.

Terminal window
ims gen openapi [flags]

Examples:

Terminal window
ims gen openapi --init
ims gen openapi --module=product
ims gen openapi --all --check
ims gen openapi --all --dry-run
Flag Default Description
--all — refresh every module listed in the generated-region index
--check — exit non-zero when the committed regions are stale
--dry-run — print the regenerated regions without writing
--init — insert the empty managed regions (one-time)
--module — refresh a single module (lower_snake name)
--root . repository root

health:check

Run application health checks.

Terminal window
ims health:check

migrate

Apply all pending database migrations.

Terminal window
ims migrate

migrate:rollback

Roll back the most recent migrations.

Terminal window
ims migrate:rollback [flags]
Flag Default Description
--steps 1 number of migrations to roll back

migrate:status

Show migration status.

Terminal window
ims migrate:status

openapi:check

Validate the embedded OpenAPI document (api/openapi.yaml) and compare it against the live router. Requires database connectivity (the route table is built from the full dependency graph), like health:check.

Terminal window
ims openapi:check

permission:sync

Sync the permission catalog into the database.

Terminal window
ims permission:sync

queue:stats

Show queue depths and failed counts.

Terminal window
ims queue:stats

queue:work

Start a queue worker (River).

Terminal window
ims queue:work [flags]
Flag Default Description
--max-workers 0 max workers per queue (default: QUEUE_WORKER_CONCURRENCY)
--once — process due jobs and exit
--once-timeout 30s how long —once waits for a job
--queues — comma-separated queues to process (default: critical,default,heavy)

schedule

Run the scheduler daemon (one process per deployment).

Terminal window
ims schedule

schedule:list

List registered scheduled tasks.

Terminal window
ims schedule:list

schedule:run

Run a scheduled task once, immediately.

Terminal window
ims schedule:run <task-id>

serve

Start the HTTP API server.

Terminal window
ims serve

settings:sync

Upsert settings groups and insert missing global settings.

Terminal window
ims settings:sync

version

Print the build version.

Terminal window
ims version