Gardomatic/doc/cli.md

Gardomatic administration CLI

The CLI connects directly to PostgreSQL and is implemented in cmd/cli.

Configuration

GARDOMATIC_DB_DSN is required for every database command. The following variables are optional:

Variable	Default	Purpose
GARDOMATIC_ENV	development	Enables confirmations for risky production operations
GARDOMATIC_WEB_BASE_URL	http://localhost:4040	Base URL for activation links
GARDOMATIC_SMTP_MODE	file	Mail delivery mode (file or smtp)
GARDOMATIC_SMTP_HOST	empty	SMTP server hostname
GARDOMATIC_SMTP_PORT	25	SMTP server port
GARDOMATIC_SMTP_USERNAME	empty	SMTP username
GARDOMATIC_SMTP_PASSWORD	empty	SMTP password
GARDOMATIC_SMTP_SENDER	gardomatic@localhost	Sender address
GARDOMATIC_SMTP_FILE_PATH	/tmp/gardomatic-mails.log	Development mail output

Global flags can override the DSN, environment, and public URL. Global flags must appear before the command. Use --json for machine-readable output and --yes to confirm an explicitly configured production operation.

Examples

Create an invited user and print a generated initial password:

go run ./cmd/cli users create \
    --name "Alice Example" \
    --email alice@example.com \
    --invite \
    --generate-password

Create the initial active application administrator atomically:

go run ./cmd/cli users create \
    --name "Initial Admin" \
    --email admin@example.com \
    --role application:admin \
    --active \
    --generate-password

Create an active development user and read the password without exposing it in the process list:

printf '%s\n' 'correct horse battery staple' | \
    go run ./cmd/cli users create \
        --name "Development User" \
        --email dev@example.com \
        --active \
        --password-stdin

Without --password-stdin or --generate-password, the CLI securely prompts for the password twice. An invitation is printed by default; add --send-email to deliver it using the configured mail backend.

Other common operations:

go run ./cmd/cli users list
go run ./cmd/cli users show --email alice@example.com
go run ./cmd/cli users invite --email alice@example.com --send-email
go run ./cmd/cli users activate --email alice@example.com
go run ./cmd/cli users deactivate --email alice@example.com
go run ./cmd/cli users reset-password --email alice@example.com --generate-password
go run ./cmd/cli users set-role --email alice@example.com --role application:admin
go run ./cmd/cli gardens add-user --garden-id 3 --email alice@example.com --role admin
go run ./cmd/cli db ping

users create requires exactly one of --active and --invite and accepts application:user or application:admin as --role. User creation, its role, and its activation token are committed in one database transaction. Password reset invalidates existing bearer and password reset tokens. The CLI never accepts passwords as command-line arguments.

Application roles (application:user, application:admin) are independent of garden roles (owner, admin, member, viewer, worker). gardens add-user uses member when --role is omitted.