@collective-intelligence/cli 0.1.9 → 0.1.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +107 -2
  2. package/dist/cli.js +46 -37
  3. package/package.json +3 -3
package/README.md CHANGED
@@ -29,8 +29,9 @@ names the version to install.
29
29
 
30
30
  ## Sign In and Enroll Your App
31
31
 
32
- Interactive developers sign in once; pipelines keep using a token. Every
33
- command accepts either credential.
32
+ Interactive developers sign in once; pipelines keep using a token. Most
33
+ management commands accept either credential. API-key creation, rotation and
34
+ revocation require an Organization Admin or Tenant Admin human session.
34
35
 
35
36
  ```sh
36
37
  # Device login: copy this command from the Dashboard (Organization →
@@ -106,6 +107,50 @@ ci logout
106
107
  - `ci apps list|get|rotate-secret|disable` manage existing applications.
107
108
  `list` and `get` show `primaryRedirectUri` beside `redirectUris`.
108
109
 
110
+ ## Manage Server Credentials and API Keys
111
+
112
+ ```sh
113
+ ci apps credentials upsert <app-fqn-or-id> --name pipeline --env-file .env.server
114
+ ci apps credentials list <app-fqn-or-id>
115
+ ci apps credentials get <app-fqn-or-id> --name pipeline
116
+ ci apps credentials rotate <app-fqn-or-id> --name pipeline --env-file .env.server
117
+ ci apps credentials revoke <app-fqn-or-id> --name pipeline
118
+
119
+ # Sign in as an Organization Admin or Tenant Admin first.
120
+ ci api-keys upsert --principal <principal-fqn> --name pipeline --scopes data_read --env-file .env.pipeline
121
+ ci api-keys list --principal <principal-fqn>
122
+ ci api-keys get --principal <principal-fqn> --name pipeline
123
+ ci api-keys rotate --principal <principal-fqn> --name pipeline --env-file .env.pipeline
124
+ ci api-keys revoke --principal <principal-fqn> --name pipeline
125
+ ```
126
+
127
+ `upsert` requires a name. For Server Credentials, omitting `--server-role`
128
+ restricts the credential to the app's Default Server Role. Repeat `--server-role`
129
+ to supply an explicit role list. API keys require at least one `--scopes` value;
130
+ scopes accept comma- or space-separated values and can repeat. A rerun updates
131
+ only these grants and returns no secret.
132
+ `upsert --rotate` explicitly rotates an existing credential; creating a missing
133
+ credential already issues its first secret. Rotation retains the previous secret
134
+ for the backend's grace period; revocation ends both secrets immediately.
135
+
136
+ Output is JSON. Only creation and rotation include a secret. `list`, `get` and
137
+ `revoke` return metadata. With `--env-file`, the secret goes only to the file;
138
+ `--json` additionally prints metadata. Other env-file lines remain intact.
139
+ Server credential files use `CI_CLIENT_SECRET`; API-key files use
140
+ `CI_MANAGEMENT_TOKEN` and `CI_BACKEND_URL`. Both retain `CI_ISSUER`,
141
+ `CI_CLIENT_ID` (the app client ID or principal ID), and `CI_CREDENTIAL_ID`.
142
+ `--prefix` replaces `CI_`. A rerun keeps the existing secret only when all three
143
+ identity fields match. If no matching secret is saved, use `--rotate`; the CLI
144
+ cannot retrieve a stored secret. Keep these files private.
145
+
146
+ Server Credentials belong to the selected app and its declared Server Roles.
147
+ They are separate from the sign-in credential produced by `ci apps enroll`;
148
+ use separate env files for these two credentials. Organization Admins, Tenant
149
+ Admins, and API keys with `external_apps_manage` can manage Server Credentials.
150
+ API keys belong to an existing service principal selected by its exact FQN;
151
+ only Organization Admins and Tenant Admins can create, rotate or revoke them.
152
+ Backend role and scope checks remain authoritative.
153
+
109
154
  ## Manage Redirect URIs and Trusted Websites
110
155
 
111
156
  An application accepts every registered redirect URI. A sign-in chooses its
@@ -174,6 +219,18 @@ downgrades; targeted package and rollback commands remain available separately.
174
219
  Use `--accept-breaking-changes` only to explicitly acknowledge a breaking change
175
220
  under the Organization's authority.
176
221
 
222
+ A declared service principal with `organization_admin` authority requires
223
+ `--allow-admin-principals` or an affirmative interactive confirmation for each
224
+ such principal. The prompt defaults to refusal; `--non-interactive` never
225
+ prompts and refuses without the flag, naming the principal and parameter.
226
+ For directly declared principals, confirmation happens before publication or
227
+ installation. The Backend also
228
+ checks admin principals in the resolved dependency graph. An interactive run
229
+ prompts when that check reports an admin principal; accepting submits a new
230
+ confirmed operation and saves a new recovery receipt. Refusal leaves the
231
+ original operation unapplied. A non-interactive run requires a fresh deployment
232
+ with `--allow-admin-principals`. This confirmation is independent of `--accept-breaking-changes` and is retained in recovery receipts.
233
+
177
234
  JSON mode emits newline-delimited records with `kind: progress`, `result`, or
178
235
  `error`. An accepted operation is progress, not success. The command follows
179
236
  resumable durable operation streams and exits successfully only after every
@@ -229,6 +286,54 @@ fields; adoption keys are concrete declaration FQNs. The backend validates
229
286
  Organization/template/ownership compatibility and keeps credentials in native
230
287
  connection custody. Invalid input errors omit input values.
231
288
 
289
+ Each `ci deploy` invocation evaluates FQN-only dependencies against the catalog's
290
+ latest eligible releases, even for unchanged parent bytes. Install/update keys
291
+ are fresh per invocation; transport retries preserve the admitted operation.
292
+ Before install/update admission, the CLI writes a private recovery receipt and
293
+ prints its path (`kind: "recovery"`, `recoveryFile` in JSON output). Errors also
294
+ include `recoveryFile` once saved. After a lost response, timeout, or process exit,
295
+ resume that admission with:
296
+
297
+ ```sh
298
+ ci deploy --backend-url <same-api-base-url> --organization <same-organization> \
299
+ --resume <receipt-file> --json
300
+ ```
301
+
302
+ Resume replays the original operation kind, request body and idempotency key,
303
+ without rebuilding, looking up releases, or reconciling changed installation
304
+ state. It authenticates with the same Organization management credential as the original
305
+ invocation and needs no publisher token. A salted credential fingerprint binds
306
+ the receipt to that credential; changed or rotated credentials fail closed before
307
+ replay, even for the same Organization, because Backend idempotency is scoped to
308
+ the authenticated principal. The token itself is never stored.
309
+ The Backend still authorizes the request; a rejected/expired recovery fails and
310
+ never silently starts another operation. Do not combine `--resume` with
311
+ `--declaration`, inputs, variables, Gateway bindings, breaking-change flags or `--allow-admin-principals`.
312
+ A normal deploy without `--resume` always creates a fresh invocation.
313
+
314
+ Receipts are stored under `$XDG_STATE_HOME/ci/deployments`, or
315
+ `$HOME/.local/state/ci/deployments` (the OS home directory if HOME is absent),
316
+ in a private 0700 directory with a 0600 file, synchronously flushed before
317
+ admission. If writing fails, no install/update is submitted. Receipts bind the
318
+ full configured API base URL (including any path), Organization and management
319
+ credential; mismatches,
320
+ malformed files, symbolic links and files accessible to other users are rejected
321
+ before replay. They contain deployment inputs, which may include connection
322
+ credentials, but never management/publisher authentication tokens. Keep them
323
+ private and delete their `deploy-*` directories once recovery is no longer needed.
324
+ The operation can also be inspected using its Operation ID when available.
325
+ Dependency declarations are `dependencies: [{ fqn: "com.acme.base" }]`; the old
326
+ `releaseId`/`releaseDigest` fields are rejected. Existing pinned installations
327
+ need the [staged bridge-release cutover](../../../docs/reference/package-release-cli.md#cut-over-existing-pinned-installations)
328
+ on the old Host before strict rollout; rebuilding/republishing or uninstalling
329
+ alone cannot clear retained old Desired/Serving manifests. Exact IDs/digests remain release metadata and
330
+ accepted backend operation selections; offline builds require no catalog access.
331
+
332
+ Existing concrete deployment checks still apply to catalog selections. A later
333
+ promotion can select a lower semantic version, but strict deployment refuses that
334
+ downgrade and preserves the installed selection. It reports the blocker instead
335
+ of silently falling back to another release.
336
+
232
337
  `ci deploy` also accepts `--var <name>=<value>` (repeatable). The value is
233
338
  coerced by the declared type: `string` as-is, `number`, `boolean` as `true` or
234
339
  `false`, `string[]` comma-separated, `json` parsed. `--var <name>=@<ORG_VARIABLE_KEY>`