@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.
- package/README.md +107 -2
- package/dist/cli.js +46 -37
- 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.
|
|
33
|
-
|
|
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>`
|