@supacloud/cli 0.14.5 → 0.15.0

package/README.md

@@ -36,16 +36,102 @@ grants, extensions, and reference-data changes in migrations; use read-only SQL
 for ordinary inspection; dry-run remote migrations; and reconcile existing
 remote drift before touching migration history.
 
-`supacloud-cli` defaults to the current workspace's project context. If you do not pass explicit flags, it tries to auto-link from `.env`:
+## Environment profiles and production safety
+
+Use named environment files to keep test and production configuration separate.
+`--env test` reads `.env.supacloud.test` from the current working directory;
+`--env prod` reads `.env.supacloud.prod` and treats the profile as production.
+For example:
+
+```dotenv
+# .env.supacloud.test
+SUPACLOUD_ENV=test
+SUPACLOUD_API_URL=https://management.test.example.com
+SUPACLOUD_API_TOKEN=<test-management-api-token>
+SUPACLOUD_PROJECT_REF=test-ref
+```
+
+```dotenv
+# .env.supacloud.prod
+SUPACLOUD_ENV=production
+SUPACLOUD_API_URL=https://management.example.com
+SUPACLOUD_API_TOKEN=<production-management-api-token>
+SUPACLOUD_PROJECT_REF=production-ref
+```
+
+Run commands with the selected profile:
+
+```bash
+supacloud-cli --env test status
+supacloud-cli project get --env test
+supacloud-cli status --env-file ./config/supacloud.staging.env
+```
+
+Global flags may appear before or after the command. Both `--key value` and
+`--key=value` syntax are accepted. `--env` and `--env-file` are mutually
+exclusive. An explicit `--env-file` must declare `SUPACLOUD_ENV`.
+
+Environment files contain credentials. The repository root `.gitignore`
+already ignores `.env` and `.env.*`; do not force-add or commit these files.
+Restrict locally created files to the current user:
+
+```bash
+chmod 600 .env.supacloud.test .env.supacloud.prod
+```
+
+CI can provide one complete context through process environment variables
+instead of writing a file:
+
+```bash
+SUPACLOUD_ENV=test \
+SUPACLOUD_API_URL=https://management.test.example.com \
+SUPACLOUD_API_TOKEN="$CI_SUPACLOUD_API_TOKEN" \
+SUPACLOUD_PROJECT_REF=test-ref \
+supacloud-cli status
+```
+
+Project context is resolved from one atomic source: a named profile selected by
+`--env`, an explicit `--env-file`, a complete process environment, or the
+legacy `.env` fallback. Core URL, token, and project-ref values are not filled
+by mixing sources. If `SUPACLOUD_ENV` is set without a complete process context,
+it strictly selects `.env.supacloud.<value>`. For backward compatibility, when
+no selector and no core process variables are present, `supacloud-cli` still
+tries to auto-link from `.env` using:
 
 - `SUPABASE_URL` or `SUPACLOUD_API_URL`
 - `SUPABASE_SERVICE_ROLE_KEY` or `SUPACLOUD_API_TOKEN`
 - `SUPACLOUD_PROJECT_REF` when the project ref cannot be inferred from a managed `<ref>.api.*` hostname
 
-Both `--key value` and `--key=value` flag syntax are accepted. `--ref` can
-override the auto-linked project for an individual command. `status` checks
-configuration, Management API connectivity, and authentication; it exits
-non-zero when any required check fails.
+The legacy `.env` fallback is unclassified and therefore does not enable the
+production confirmation gate. Production automation must select a `prod` or
+`production` profile, or set `SUPACLOUD_ENV=production` together with a complete
+process context. Use `SUPACLOUD_READ_ONLY=true` when legacy workflows must be
+restricted to inspection only.
+
+`SUPACLOUD_READ_ONLY=true` is a safety override that blocks remote writes.
+Production writes require an explicit confirmation equal to the selected
+profile's project ref:
+
+```bash
+supacloud-cli database push_migrations --env prod \
+  --ref production-ref --dir supabase/migrations \
+  --confirm-production production-ref
+```
+
+Dry runs remain read operations. Production `diagnostics repair` is always
+forbidden, and unclassified actions fail closed in production or read-only
+contexts.
+
+For supported command groups, `--ref` overrides the profile's default project
+for one command. A production profile cannot target a different project with
+`--ref`; the requested ref and `--confirm-production` must both exactly match
+the profile's project ref.
+
+`status` checks configuration, Management API connectivity, and authentication;
+it exits non-zero when any required check fails. Its output includes
+`environment`, `source` (`kind` and `path`), `apiUrl`, `projectRef`, `readOnly`,
+`production`, and `hasApiToken`. It never prints the API token or service-role
+key.
 
 Examples:
 
@@ -71,6 +157,9 @@ supacloud-cli branch promote --branch_ref preview123 --plan_checksum <sha256>
 supacloud-cli edge_functions deploy --ref abc123 --slug hello --path ./supabase/functions/hello
 supacloud-cli edge_functions deploy_bundle --ref abc123 --slug hello --files '{"index.ts":"export default { fetch: () => new Response(\"ok\") }"}'
 supacloud-cli edge_functions source --ref abc123 --slug hello --output ./hello.ts
+supacloud-cli edge_functions activate --ref abc123 --slug hello --version 3
+supacloud-cli scheduled_functions list --ref abc123
+supacloud-cli secrets upsert --ref abc123 --from-env API_KEY,WEBHOOK_SECRET
 ```
 
 `edge_functions deploy --path` bundles local TypeScript and dependencies with
@@ -82,6 +171,44 @@ Use `source --output <file>` for large Functions so terminal or automation outpu
 limits cannot truncate the original TS/JS source code. The destination must not
 already exist.
 
+`edge_functions activate` restores an existing immutable Function version and
+returns a machine-readable receipt containing the activated version and JWT
+policy. HTTP and malformed-response failures exit non-zero without echoing the
+server response body.
+
+Mutation receipts use schema `supacloud.cli.release-control.v1`. An
+`OUTCOME_UNKNOWN` error means the server may have committed the mutation before
+the response was lost or failed validation; read back current state before any
+retry.
+
+Scheduled Function lifecycle operations are also project-scoped:
+
+```bash
+supacloud-cli scheduled_functions create --ref abc123 --name nightly \
+  --slug cleanup --cron "0 2 * * *" --method POST
+supacloud-cli scheduled_functions update --ref abc123 --schedule_id <id> \
+  --cron "0 3 * * *"
+supacloud-cli scheduled_functions delete --ref abc123 --schedule_id <id>
+```
+
+Schedule IDs are canonical UUIDv4 values returned by create/list. Cron values
+use bounded numeric five-field syntax with wildcards, lists, ranges, and steps;
+out-of-range endpoints and steps are rejected before HTTP dispatch.
+
+Use `--body_file ./payload.json` for a JSON-object request body. Header values
+must come from environment variables: pass a JSON name mapping such as
+`--header_env '{"x-schedule-token":"SCHEDULE_TOKEN"}'`. Platform-owned
+`authorization`, `apikey`, and `x-project-ref` headers cannot be overridden. Receipts never
+include header values or body content; list and mutation receipts report only
+whether the body is empty and the configured header names.
+
+For secret writes, `--from-env` accepts a comma-separated list of environment
+variable names. The CLI reads each non-empty value from its own process
+environment, so command arguments contain names only and values are never
+printed. Names must be unique shell-style identifiers (`[A-Za-z_][A-Za-z0-9_]*`,
+up to 256 characters). Missing or empty values fail before any HTTP request.
+Do not combine `--from-env` with the compatibility `--secrets` input.
+
 Branch promotion is migration-first. `branch promotion_plan` prints pending
 versions, names, statement counts, and checksums without echoing SQL into terminal
 logs; review the migration files or the Web Console SQL view before approval.
@@ -174,6 +301,22 @@ USING hnsw (embedding vector_cosine_ops);
 
 Transaction boundary: SupaCloud supports transaction blocks inside one SQL request and transactional migrations. It does not expose long-lived HTTP transaction sessions; use a direct Postgres DSN for application-side long transactions.
 
+Auth configuration commands accept a JSON object from the CLI:
+
+```bash
+supacloud-cli auth update_settings --ref abc123 \
+  --config '{"disable_signup":true,"enable_signup":false}'
+supacloud-cli auth update_config --ref abc123 \
+  --config '{"third_party_auth":{"enabled":true}}'
+```
+
+Failed Auth mutations exit non-zero and print a JSON object containing the HTTP
+status plus an allowlisted subset of runtime-apply state. If Management API
+returns `503` with `persisted: true`, the desired configuration was saved but
+runtime propagation was incomplete; automation must read the affected settings
+back exactly before deciding whether it is safe to continue. Free-form server
+messages and request configuration are not echoed.
+
 Project commands owned by this CLI:
 
 - `project get`