Initial commit

2026-09-12 22:22:17 +02:00
commit 904d14b64c
314 changed files with 31884 additions and 0 deletions
@@ -0,0 +1,87 @@
+# 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:
+
+```sh
+go run ./cmd/cli users create \
+    --name "Alice Example" \
+    --email alice@example.com \
+    --invite \
+    --generate-password
+```
+
+Create the initial active application administrator atomically:
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+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.