@collective-intelligence/cli 0.1.10 → 0.1.12
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 +121 -3
- package/dist/cli.js +41 -25
- 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,111 @@ 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
|
+
## Create an Organization from a Tenant Session
|
|
111
|
+
|
|
112
|
+
A Tenant Admin can approve `ci login <api-url>` without choosing an Organization.
|
|
113
|
+
Then create a ready-to-use Organization using the installation's configured defaults:
|
|
114
|
+
|
|
115
|
+
```sh
|
|
116
|
+
ci login <api-url>
|
|
117
|
+
ci orgs create --name "Acme" --defaults --json
|
|
118
|
+
ci whoami
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
`--defaults` fills omitted choices from the elected model preset, its embedding
|
|
122
|
+
model and the installation storage provider. It reads only configuration needed
|
|
123
|
+
for omitted choices; complete explicit inputs do not require the defaults catalog.
|
|
124
|
+
Missing required defaults stop
|
|
125
|
+
creation with the applicable override flags. Storage secrets remain server-side.
|
|
126
|
+
The command selects the new Organization in the saved Profile used for the CLI
|
|
127
|
+
Session. An explicit `CI_MANAGEMENT_TOKEN` session works unattended and leaves
|
|
128
|
+
Profiles unchanged; Organization API keys cannot authorize tenant creation.
|
|
129
|
+
|
|
130
|
+
Customize with `--preset`, `--storage-provider`, `--embedding-model`, `--slug`,
|
|
131
|
+
`--timezone`, or `--inputs organization.json`. The JSON file accepts the existing
|
|
132
|
+
partial setup body: `organization`, `presetId`, `storage`, `embedding`, and
|
|
133
|
+
`installPackages`. Flags override matching file leaves; `--defaults` fills only
|
|
134
|
+
omissions. Valid explicit nulls are preserved. Unknown structural fields and
|
|
135
|
+
invalid types fail before creation; `storage.settings` and `embedding.options`
|
|
136
|
+
accept provider-specific records. Omitted timezone is UTC; an omitted slug is
|
|
137
|
+
derived from the name. Empty derived slugs require `--slug`; collisions never
|
|
138
|
+
receive an automatic suffix. Without `--defaults`, provide the required preset,
|
|
139
|
+
storage and embedding configuration explicitly.
|
|
140
|
+
`embedding.defaultChunkSize` accepts an integer or `null`; fractional values
|
|
141
|
+
fail preflight with a field-specific error.
|
|
142
|
+
|
|
143
|
+
```sh
|
|
144
|
+
ci orgs create --inputs organization.json --name "Acme Europe" --defaults --json
|
|
145
|
+
ci orgs create --name "Acme" --preset <preset-id> --storage-provider s3 \
|
|
146
|
+
--embedding-model <model-id> --inputs organization.json --json
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
JSON mode prints one terminal object. `created` exits 0 and includes the complete
|
|
150
|
+
setup `result` plus `selection` (`selected` or `not_applicable`).
|
|
151
|
+
`created_selection_failed` exits 1 but preserves the full created result and
|
|
152
|
+
provides `ci orgs use <id>` recovery. `failed` exits 1 without a created identity.
|
|
153
|
+
`outcome_unknown` exits 1 when a timeout, lost response or untrustworthy response
|
|
154
|
+
cannot establish the result. Creation is never automatically retried.
|
|
155
|
+
Recovery commands retain the resolved backend URL and applicable Profile without
|
|
156
|
+
credentials. If the slug or Profile cannot be represented safely as an option
|
|
157
|
+
value (including a slug starting with `--`), guidance directs you to inspect
|
|
158
|
+
Organizations in the Dashboard for that backend.
|
|
159
|
+
|
|
160
|
+
```sh
|
|
161
|
+
ci orgs list --slug acme --json
|
|
162
|
+
ci orgs use <created-organization-id>
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
Exact-slug lookup uses tenant-read permission (Tenant Admin or Tenant Operator)
|
|
166
|
+
and returns a plain Organization array. A match does not prove that the uncertain
|
|
167
|
+
request created it; an empty result does not prove rollback. Ordinary `ci orgs
|
|
168
|
+
list` continues to list accessible Organizations. Existing `--profile` and
|
|
169
|
+
`--backend-url` options apply; creation requires no Organization selector.
|
|
170
|
+
|
|
171
|
+
## Manage Server Credentials and API Keys
|
|
172
|
+
|
|
173
|
+
```sh
|
|
174
|
+
ci apps credentials upsert <app-fqn-or-id> --name pipeline --env-file .env.server
|
|
175
|
+
ci apps credentials list <app-fqn-or-id>
|
|
176
|
+
ci apps credentials get <app-fqn-or-id> --name pipeline
|
|
177
|
+
ci apps credentials rotate <app-fqn-or-id> --name pipeline --env-file .env.server
|
|
178
|
+
ci apps credentials revoke <app-fqn-or-id> --name pipeline
|
|
179
|
+
|
|
180
|
+
# Sign in as an Organization Admin or Tenant Admin first.
|
|
181
|
+
ci api-keys upsert --principal <principal-fqn> --name pipeline --scopes data_read --env-file .env.pipeline
|
|
182
|
+
ci api-keys list --principal <principal-fqn>
|
|
183
|
+
ci api-keys get --principal <principal-fqn> --name pipeline
|
|
184
|
+
ci api-keys rotate --principal <principal-fqn> --name pipeline --env-file .env.pipeline
|
|
185
|
+
ci api-keys revoke --principal <principal-fqn> --name pipeline
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
`upsert` requires a name. For Server Credentials, omitting `--server-role`
|
|
189
|
+
restricts the credential to the app's Default Server Role. Repeat `--server-role`
|
|
190
|
+
to supply an explicit role list. API keys require at least one `--scopes` value;
|
|
191
|
+
scopes accept comma- or space-separated values and can repeat. A rerun updates
|
|
192
|
+
only these grants and returns no secret.
|
|
193
|
+
`upsert --rotate` explicitly rotates an existing credential; creating a missing
|
|
194
|
+
credential already issues its first secret. Rotation retains the previous secret
|
|
195
|
+
for the backend's grace period; revocation ends both secrets immediately.
|
|
196
|
+
|
|
197
|
+
Output is JSON. Only creation and rotation include a secret. `list`, `get` and
|
|
198
|
+
`revoke` return metadata. With `--env-file`, the secret goes only to the file;
|
|
199
|
+
`--json` additionally prints metadata. Other env-file lines remain intact.
|
|
200
|
+
Server credential files use `CI_CLIENT_SECRET`; API-key files use
|
|
201
|
+
`CI_MANAGEMENT_TOKEN` and `CI_BACKEND_URL`. Both retain `CI_ISSUER`,
|
|
202
|
+
`CI_CLIENT_ID` (the app client ID or principal ID), and `CI_CREDENTIAL_ID`.
|
|
203
|
+
`--prefix` replaces `CI_`. A rerun keeps the existing secret only when all three
|
|
204
|
+
identity fields match. If no matching secret is saved, use `--rotate`; the CLI
|
|
205
|
+
cannot retrieve a stored secret. Keep these files private.
|
|
206
|
+
|
|
207
|
+
Server Credentials belong to the selected app and its declared Server Roles.
|
|
208
|
+
They are separate from the sign-in credential produced by `ci apps enroll`;
|
|
209
|
+
use separate env files for these two credentials. Organization Admins, Tenant
|
|
210
|
+
Admins, and API keys with `external_apps_manage` can manage Server Credentials.
|
|
211
|
+
API keys belong to an existing service principal selected by its exact FQN;
|
|
212
|
+
only Organization Admins and Tenant Admins can create, rotate or revoke them.
|
|
213
|
+
Backend role and scope checks remain authoritative.
|
|
214
|
+
|
|
109
215
|
## Manage Redirect URIs and Trusted Websites
|
|
110
216
|
|
|
111
217
|
An application accepts every registered redirect URI. A sign-in chooses its
|
|
@@ -174,6 +280,18 @@ downgrades; targeted package and rollback commands remain available separately.
|
|
|
174
280
|
Use `--accept-breaking-changes` only to explicitly acknowledge a breaking change
|
|
175
281
|
under the Organization's authority.
|
|
176
282
|
|
|
283
|
+
A declared service principal with `organization_admin` authority requires
|
|
284
|
+
`--allow-admin-principals` or an affirmative interactive confirmation for each
|
|
285
|
+
such principal. The prompt defaults to refusal; `--non-interactive` never
|
|
286
|
+
prompts and refuses without the flag, naming the principal and parameter.
|
|
287
|
+
For directly declared principals, confirmation happens before publication or
|
|
288
|
+
installation. The Backend also
|
|
289
|
+
checks admin principals in the resolved dependency graph. An interactive run
|
|
290
|
+
prompts when that check reports an admin principal; accepting submits a new
|
|
291
|
+
confirmed operation and saves a new recovery receipt. Refusal leaves the
|
|
292
|
+
original operation unapplied. A non-interactive run requires a fresh deployment
|
|
293
|
+
with `--allow-admin-principals`. This confirmation is independent of `--accept-breaking-changes` and is retained in recovery receipts.
|
|
294
|
+
|
|
177
295
|
JSON mode emits newline-delimited records with `kind: progress`, `result`, or
|
|
178
296
|
`error`. An accepted operation is progress, not success. The command follows
|
|
179
297
|
resumable durable operation streams and exits successfully only after every
|
|
@@ -251,7 +369,7 @@ replay, even for the same Organization, because Backend idempotency is scoped to
|
|
|
251
369
|
the authenticated principal. The token itself is never stored.
|
|
252
370
|
The Backend still authorizes the request; a rejected/expired recovery fails and
|
|
253
371
|
never silently starts another operation. Do not combine `--resume` with
|
|
254
|
-
`--declaration`, inputs, variables, Gateway bindings
|
|
372
|
+
`--declaration`, inputs, variables, Gateway bindings, breaking-change flags or `--allow-admin-principals`.
|
|
255
373
|
A normal deploy without `--resume` always creates a fresh invocation.
|
|
256
374
|
|
|
257
375
|
Receipts are stored under `$XDG_STATE_HOME/ci/deployments`, or
|