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.
ims backup:clean [flags]| Flag | Default | Description |
|---|---|---|
--dry-run |
— | report what would be deleted without deleting |
backup:list
List recent backup runs.
ims backup:list [flags]| Flag | Default | Description |
|---|---|---|
--limit |
20 |
maximum runs to list |
backup:monitor
Check backup freshness and storage usage.
ims backup:monitorbackup:run
Create a database backup archive.
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.
ims billing:expire-subscriptionsbilling:send-renewal-reminders
Log renewal reminders for subscriptions expiring within 7/3/1 days.
ims billing:send-renewal-reminderscache:clear
Clear the configured cache store.
ims cache:clear [flags]| Flag | Default | Description |
|---|---|---|
--store |
— | override the cache driver (memory|file|redis|database) |
config:show
Print the effective configuration.
ims config:showdata-processing:cleanup-completed
Delete completed processing-job records older than the retention 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.
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.
ims dev-dashboard:prunefeature-flags:sync
Insert missing global feature flags with their catalog defaults.
ims feature-flags:syncgen 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).
ims gen docs [flags]Examples:
ims gen docsims 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.
ims gen module [flags]Examples:
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.
ims gen openapi [flags]Examples:
ims gen openapi --initims gen openapi --module=productims gen openapi --all --checkims 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.
ims health:checkmigrate
Apply all pending database migrations.
ims migratemigrate:rollback
Roll back the most recent migrations.
ims migrate:rollback [flags]| Flag | Default | Description |
|---|---|---|
--steps |
1 |
number of migrations to roll back |
migrate:status
Show migration status.
ims migrate:statusopenapi: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.
ims openapi:checkpermission:sync
Sync the permission catalog into the database.
ims permission:syncqueue:stats
Show queue depths and failed counts.
ims queue:statsqueue:work
Start a queue worker (River).
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).
ims scheduleschedule:list
List registered scheduled tasks.
ims schedule:listschedule:run
Run a scheduled task once, immediately.
ims schedule:run <task-id>serve
Start the HTTP API server.
ims servesettings:sync
Upsert settings groups and insert missing global settings.
ims settings:syncversion
Print the build version.
ims version