@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.
Files changed (3) hide show
  1. package/README.md +121 -3
  2. package/dist/cli.js +41 -25
  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,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 or breaking-change flags.
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