@collective-intelligence/cli 0.1.28 → 0.1.29

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 +113 -2
  2. package/dist/cli.js +43 -33
  3. package/package.json +8 -8
package/README.md CHANGED
@@ -192,8 +192,9 @@ scopes accept comma- or space-separated values and can repeat. The scopes are
192
192
  `knowledge_read`, `knowledge_manage`, `documents_read`, `documents_manage`,
193
193
  `datasets_read`, `datasets_manage`, `automations_invoke`,
194
194
  `benchmark_judge_invoke`, `organization_users_manage`,
195
- `organization_settings_manage` and `external_apps_manage`. A rerun updates
196
- only these grants and returns no secret.
195
+ `organization_settings_manage`, `external_apps_manage` and
196
+ `organization_transfer`. A rerun updates only these grants and returns no
197
+ secret.
197
198
  `upsert --rotate` explicitly rotates an existing credential; creating a missing
198
199
  credential already issues its first secret. Rotation retains the previous secret
199
200
  for the backend's grace period; revocation ends both secrets immediately.
@@ -260,6 +261,116 @@ ci apps origins remove <your.app.fqn> https://<your-app-host>
260
261
  - These commands refuse package-owned applications; change those through their
261
262
  Extension Package.
262
263
 
264
+ ## Move Data Between Organizations
265
+
266
+ `ci transfer` exports Knowledge, Documents and Datasets of one Organization into
267
+ a Transfer Archive and imports it into another Organization. It calls the same
268
+ HTTP endpoints as the Dashboard wizard. It needs the `organization_transfer`
269
+ permission: an Organization Admin session, or an API key with the
270
+ `organization_transfer` scope. An import also writes data, so the API key needs
271
+ the `knowledge_manage`, `documents_manage` and `datasets_manage` scopes too, and
272
+ its principal must be allowed to manage each domain that the archive holds. A
273
+ refused request prints the HTTP status (for example 403) and the backend reason.
274
+
275
+ ```sh
276
+ # Count what a Selection picks and see how many relations leave it. Starts no run.
277
+ ci transfer export --preview --domain knowledge --boundary-mode clear
278
+
279
+ # Export, wait for the run and save the archive as a zip.
280
+ ci transfer export --domain documents --out ./acme.zip
281
+
282
+ # A zip holds at most 4 GiB and 65535 files. For a larger archive, save the
283
+ # finished run into a folder instead of exporting again.
284
+ ci transfer export --run <export-run-id> --out ./acme --format folder
285
+
286
+ # Import in two steps: upload and plan, read the Plan, then apply it.
287
+ ci transfer import --plan --archive ./acme.zip --policy update
288
+ ci transfer import --apply --plan-run <plan-run-id> --policy update
289
+
290
+ # Undo an applied import, and manage runs.
291
+ ci transfer rollback --source-run <import-run-id>
292
+ ci transfer runs
293
+ ci transfer runs --run <run-id> --report
294
+ ```
295
+
296
+ **Export.** `--domain` (repeatable: `knowledge`, `documents`, `datasets`) or
297
+ `--selection <file>` (a JSON Selection with per-unit filters) picks the data.
298
+ `--boundary-mode reference|clear|include_referenced`, `--depth`,
299
+ `--max-dependency-items` and `--identity-field <unit>=<field,...>` set the
300
+ Relation Boundary. `--out <path>` saves the archive after the run completes,
301
+ as a zip (`--format zip`, the default) or a folder (`--format folder`). `--run
302
+ <export-run-id>` skips the export and saves the archive of a finished run.
303
+
304
+ **Import.** `--plan` takes `--archive <folder|zip>` and uploads it file by file
305
+ with signed URLs, then runs the Plan. `--archive-id <id>` names the archive in
306
+ the target Organization: pass the id that an interrupted upload printed to
307
+ resume it (files that are already there are skipped), or pass it alone to plan
308
+ an archive that is already uploaded. `--apply` needs `--plan-run <id>`; it takes
309
+ the archive of that Plan run. Send the same import options on both steps; the
310
+ backend refuses an apply whose options differ from the Plan. `--confirm-replace`
311
+ belongs to `--apply` and is required when the Plan removes Dataset rows.
312
+
313
+ | Option | Values |
314
+ | ----------------------------------------------- | ------------------------------------------------------------------------------------ |
315
+ | `--policy` | `create_only`, `skip_existing` (default), `update`, `fill_blanks` |
316
+ | `--unresolved-reference` | `fail` (default), `continue`, `skip_item` |
317
+ | `--join-user`, `--join-group` | comma-separated join fields: user `email`, `name`, `id`; group `name`, `slug`, `fqn` |
318
+ | `--connector-instance <source-id>=<target-id>` | repeatable; binds a source connector instance to a target instance |
319
+ | `--max-errors <n>` | stop after this many failed items |
320
+ | `--no-import-origin` | do not record the Import Origin |
321
+ | `--events` | let the imported writes start automations and events |
322
+ | `--unit <domain>:<unit>` | repeatable; import only the listed units, for example `datasets:orders` |
323
+ | `--dataset-mode <unit>=append\|upsert\|replace` | repeatable; the unit must also be named by `--unit`, written the same way |
324
+ | `--force <unit>` | repeatable; import a Dataset unit again; the unit must also be named by `--unit` |
325
+
326
+ A unit has a domain (`knowledge`, `documents` or `datasets`), and two domains
327
+ can hold a unit of one name. Write `--unit <domain>:<unit>`. A bare `--unit
328
+ <unit>` works when the archive (for `--plan`) or the Plan run (for `--apply`)
329
+ holds one unit of that name; if it holds none or several, the command lists the
330
+ choices and stops before it uploads anything. The server refuses a unit that is
331
+ not in the archive with HTTP 422 and says which. `--dataset-mode` and `--force`
332
+ name the unit as `--unit` does.
333
+
334
+ After a Plan, the CLI writes one line on stderr for each unit that is blocked
335
+ (`write_permission_denied`, `unit_incomplete`, `unit_ambiguous`) and for each
336
+ warning (`no_match_key_or_origin`, `forced_duplicates`, `earlier_run_committed`,
337
+ `already_imported`). The Plan itself stays in the JSON result on stdout.
338
+
339
+ **Runs.** `ci transfer runs` lists the latest runs (`--limit <n>` sets how many).
340
+ `--run <id>` reads that run directly, however old it is, and with `--report`,
341
+ `--cancel`, `--resume` or `--purge` it reads the Run Report, cancels, resumes
342
+ (and follows) or purges the files of that run. `--limit` with `--run` is refused.
343
+
344
+ **Output.** Every line on stdout is one JSON object. Commands that start a run
345
+ print one `{"kind":"progress","step":"run",...}` line per run event, and upload
346
+ and download print `step: "upload"` and `step: "download"` lines. The command
347
+ ends with one `{"kind":"result",...}` line, or with one
348
+ `{"kind":"error","message":...}` line and exit status 1. An error line can carry
349
+ `code` (for example `archive_zip_limit`, `run_failed`, `upload_failed`,
350
+ `zip_malformed`), `nextAction` (the command that continues), `runId`,
351
+ `archiveId` and `status`. `nextAction` is the command you ran, with all its
352
+ options and with quoting for the shell, plus what it needs to continue: the
353
+ `--archive-id` of an upload that began, or the run to read. A run that does not
354
+ complete is an error; `nextAction` names `--resume` for a stopped run.
355
+ Persisted and wire values use lower snake_case; flag names use kebab-case.
356
+
357
+ **Ctrl-C.** The first Ctrl-C stops the upload, the download or the follow at
358
+ once and ends the command with a `{"kind":"error","code":"interrupted",...}`
359
+ line and exit status 130. A run that was already started keeps running on the
360
+ backend; the error line names it and the command that reads it. An interrupted
361
+ upload names its archive, and `nextAction` resumes it with `--archive-id`.
362
+ `--out` writes `<out>.partial` and replaces `<out>` only when the download is
363
+ whole; a failed or interrupted download leaves the file that was there and
364
+ removes its own partial file.
365
+
366
+ **Zip files.** The CLI reads a zip by byte range (it needs a seekable file), so a
367
+ file that holds the bytes of a zip record does not break the import. A damaged
368
+ or encrypted zip ends with the code `zip_malformed`. The writer has no Zip64: a
369
+ zip, counting its headers and central directory, holds at most 4 GiB and 65535
370
+ files, and a larger export fails with `archive_zip_limit`; use `--format folder`.
371
+ The reader does not check the CRC-32 of an entry; the Plan run verifies the
372
+ SHA-256 of every file.
373
+
263
374
  ## Deploy an Exact Release
264
375
 
265
376
  `ci deploy` builds and validates one declaration, resolves its exact immutable