@groundfloorcloud/cli 0.1.13 → 0.2.0

package/README.md

@@ -45,6 +45,18 @@ gf coderunner ls
 gf deploy
 ```
 
+Non-interactive use (CI, containers): set `GROUNDFLOOR_TOKEN` to a Control
+Plane JWT. It takes precedence over the saved `gf login` session (an expired
+`GROUNDFLOOR_TOKEN` is ignored when a saved session exists, so a stale export
+does not shadow it). Mint one from an M2M client:
+
+```bash
+export GROUNDFLOOR_TOKEN="$(gf m2m token)"   # needs GROUNDFLOOR_M2M_CLIENT_ID / _SECRET
+export GROUNDFLOOR_WORKSPACE_ID=<workspace-id>
+# non-production cells also need GROUNDFLOOR_API_URL
+gf coderunner ls
+```
+
 Use the session from a shell or script:
 
 ```bash
@@ -81,7 +93,7 @@ key. `gf coderunner vault-token` is deprecated.
 gf deploy
 gf deploy --git https://github.com/me/my-fn.git --ref main
 gf deploy --name my-fn --runtime python --cpu 250m --memory 256Mi \
-  -e API_KEY=secret
+  -e LOG_LEVEL=debug
 gf deploy --workload-type service
 gf deploy --workload-type schedule --schedule "*/5 * * * *"
 gf deploy --app-id <app-uuid>
@@ -93,6 +105,33 @@ How the target is chosen:
 - Otherwise the name comes from `--name`, then `groundfloor.json`, then the
   folder or repo name. A matching slug is reused; otherwise a new coderunner
   is created.
+- `--app-id` applies only when a **new** coderunner is created. When an
+  existing one is reused or `-c` is given, it is ignored and `gf deploy` warns.
+
+Deploy target safety:
+
+- The workspace comes from `-w`, `GROUNDFLOOR_WORKSPACE_ID`, or the saved
+  machine-wide default (`gf workspaces use`). The saved default is shared by
+  every shell on the machine, so it is never used silently: without an
+  interactive terminal `gf deploy` refuses and asks for `-w <workspace-id>`;
+  on a terminal it prints the workspace name and id and asks to confirm.
+  `-w` and `GROUNDFLOOR_WORKSPACE_ID` deploy without that prompt.
+- Reusing a same-named coderunner prints its name, id and environment and asks
+  to confirm. Without a terminal, pass `-y/--yes`.
+- Check the printed coderunner id and URL after the deploy; an unexpected new
+  id means it went somewhere you did not intend.
+
+**Redeploys and env vars.** The platform stores only the env var *names* of a
+deployment, never the values. A redeploy that does not resend a variable
+(`-e`, or `groundfloor.json` `env`) drops it from the new deployment. `gf
+deploy` warns about previously-set keys that are not being resent. Resend every
+variable you need on each deploy.
+
+**Secrets at runtime.** Do not rely on `--secret` to pass secrets into a
+deployment. Read them at runtime with an M2M client that has `secrets:read`
+(`gf m2m token`, then `GET /v1/workspaces/{id}/secrets`). `--secret NAME`
+injection only works where the platform has secret injection enabled, which is
+currently not the case; the server rejects it with a 422 otherwise.
 
 Runtime is auto-detected when omitted (`package.json` → node,
 `requirements.txt` / `pyproject.toml` → python), defaulting to python.
@@ -135,7 +174,13 @@ wrong identity for testing Coderunner Vault/Files as the workload.
 
 | Flag | Description |
 |------|-------------|
-| `-w, --workspace <id>` | Workspace override (else `gf workspaces use`). |
+| `-w, --workspace <id>` | Target workspace. Required without a terminal unless `GROUNDFLOOR_WORKSPACE_ID` is set; the saved default needs an interactive confirm. |
+| `-n, --name <name>` | Coderunner name (else `groundfloor.json`, then folder name). |
+| `-c, --coderunner <id\|slug>` | Deploy into this existing coderunner. |
+| `--app-id <uuid>` | Bind a **new** coderunner to an App as a helper. Ignored on reuse. |
+| `--secret <NAME>` | Inject a workspace secret (repeatable). Only works where the platform has injection enabled; prefer runtime reads via M2M `secrets:read`. |
+| `--api-url <url>` | Control Plane base URL override. |
+| `-y, --yes` | Skip the reuse confirmation (required without a terminal). |
 | `-p, --path <dir>` | Directory to package (default: cwd). |
 | `--git <url>` / `--ref <ref>` | Clone and deploy a remote repo. |
 | `--subdir <dir>` | Package a subdirectory of the source. |
@@ -159,8 +204,9 @@ halves), `*.pem`, `*.key`, `*.p12`, `*.pfx`, `*.jks`, `*.keystore`, `*.ppk`,
 `.gcloud/`, `.gnupg/`, `.docker/`, `.kube/`, `.terraform/` or `.chef/`.
 
 Every exclusion is printed, and so is every dot-file that survived the filter.
-There is no flag to turn it off: pass values with `gf secrets` or
-`-e KEY=VALUE` instead.
+There is no flag to turn it off: keep credentials in `gf secrets` and read them
+at runtime (M2M `secrets:read`), or pass non-sensitive config with
+`-e KEY=VALUE`. Credential-shaped `-e` keys are rejected.
 
 This is a **denylist**, so it only knows names. A secret in a file called
 `config.json`, `settings.py` or `serviceAccount.json` is still uploaded —
@@ -184,7 +230,7 @@ npm run release
 gf apps publish --path release.zip
 ```
 
-`gf apps init` downloads the public ZIP from the Customer Portal
+`gf apps init` downloads the public ZIP from the Client Portal
 (`/downloads/shell-starter-kit.zip` on the current cell) and stamps
 `APP_ID` / `groundfloor.manifest.json` `appId` to the slug.
 
@@ -213,7 +259,7 @@ gf dataplane status
 gf dataplane provision
 
 gf secrets ls
-gf secrets set DATABASE_URL 'postgres://…'
+printf '%s' "$DATABASE_URL" | gf secrets set DATABASE_URL -   # stdin keeps the value out of shell history
 gf secrets get DATABASE_URL
 gf secrets rm DATABASE_URL
 
@@ -226,6 +272,11 @@ gf apps ls
 gf apps get <id|slug>
 ```
 
+`gf env` and `gf secrets get` print raw secret values to stdout by design; do
+not run them where output is logged. For `gf m2m token`, set
+`GROUNDFLOOR_M2M_CLIENT_SECRET` instead of `--client-secret` (argv is visible
+in `ps` and shell history).
+
 ## Feature flags
 
 Per-environment toggles and config values. `-e` takes an environment id or name
@@ -261,12 +312,15 @@ https://docs.groundfloor.cloud/docs/configure/feature-flags.
 | `gf coderunner ls` (`cr ls`) | List coderunners. |
 | `gf coderunner status -c <id\|slug>` | Status and current deployment. |
 | `gf coderunner logs -c <id\|slug>` | Process Log (stdout/stderr). Also printed automatically on `gf deploy` failure. |
-| `gf coderunner cancel-deployment -c <id\|slug>` | Delete the current (or `--deployment-id`) deployment. |
+| `gf coderunner cancel-deployment -c <id\|slug>` | **Destructive.** Deletes the current (or `--deployment-id`) deployment; if it is the live one the service goes offline. Confirms on a terminal; requires `-y/--yes` without one. |
 | `gf coderunner run -c <id\|slug> [--payload '{}']` | Invoke a deployed function or job. |
 | `gf m2m token` | Print a short Control Plane JWT from M2M client_id + secret. Not `gf token`. |
 | `gf coderunner vault-token` | **Deprecated.** Use `gf m2m token`. |
-| `gf deploy` | Package code and deploy as a coderunner. |
-| `gf domains ls\|add\|rm\|verify -c <id\|slug>` | Custom domains for a service. |
+| `gf deploy` | Package code and deploy as a coderunner (see Deploy flags). |
+| `gf domains ls\|add\|rm\|verify --app <id\|slug>` | Custom domains for a standalone App. Domains belong to Apps; standalone coderunner domain routes are not supported. |
+| `gf identities ls\|mint --identity <id>` | Workload identities (Vault principals); first mint returns `refresh_secret` once. |
+| `gf usage [--account <id>] [--since-days <n>] [--json]` | Read-only account quota/usage and billing estimate. The account is the billing parent of the workspace, not the workspace id. |
+| `gf api <path> [-X <method>] [--body <json>]` | Call a Control Plane path; `{workspace_id}` expands to the current workspace. |
 | `gf secrets ls\|get\|set\|rm` | Workspace secrets. |
 | `gf flags ls\|get\|set\|rm\|compare\|promote` | Feature flags per environment (`-e <id\|name>`). |
 | `gf files ls\|upload\|download\|rm` | Workspace files. |
@@ -290,11 +344,12 @@ still override the hosts for that login.
 | IdP issuer | `--issuer` | `GROUNDFLOOR_ISSUER` | Groundfloor managed IdP |
 | OIDC client id | `--client-id` | `GROUNDFLOOR_CLIENT_ID` | `groundfloor-cli` |
 | Default workspace | (via `gf workspaces use`) | `GROUNDFLOOR_WORKSPACE_ID` | (none) |
+| Access token | (none) | `GROUNDFLOOR_TOKEN` | (none; wins over the saved session) |
 
 State is stored under `~/.groundfloor/`:
 
 - `auth.json` — cached tokens (chmod `600`).
-- `config.json` — non-secret defaults (issuer, client id, api url, workspace).
+- `config.json` — non-secret defaults (issuer, client id, api url, workspace); chmod `600`.
 
 ### Redirect URI mismatch
 
@@ -308,7 +363,7 @@ sign-in fails with an invalid redirect URI:
 
 ## More
 
-- [Customer Portal](https://app.groundfloor.cloud)
+- [Client Portal](https://console.groundfloor.cloud)
 - [Developers](https://docs.groundfloor.cloud/docs/developer-tools/cli)
 - [Deploy with agents](https://docs.groundfloor.cloud/docs/developer-tools/ai-agents)
 - [Coderunner](https://docs.groundfloor.cloud/docs/deploy)