@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.
- package/README.md +113 -2
- package/dist/cli.js +43 -33
- 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
|
|
196
|
-
only these grants and returns no
|
|
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
|