@collective-intelligence/cli 0.3.2 → 0.3.4
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 +86 -5
- package/dist/cli.js +52 -44
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -432,7 +432,9 @@ ends with one `{"kind":"result",...}` line, or with one
|
|
|
432
432
|
`archiveId` and `status`. `nextAction` is the command you ran, with all its
|
|
433
433
|
options and with quoting for the shell, plus what it needs to continue: the
|
|
434
434
|
`--archive-id` of an upload that began, or the run to read. A run that does not
|
|
435
|
-
complete is an error; `nextAction` names `--resume` for a stopped run.
|
|
435
|
+
complete is an error; `nextAction` names `--resume` for a stopped run. The
|
|
436
|
+
error line also carries the Failure Signal fields of
|
|
437
|
+
[Errors and diagnostics](#errors-and-diagnostics).
|
|
436
438
|
Persisted and wire values use lower snake_case; flag names use kebab-case.
|
|
437
439
|
|
|
438
440
|
**Ctrl-C.** The first Ctrl-C stops the upload, the download or the follow at
|
|
@@ -558,7 +560,8 @@ JSON mode emits newline-delimited records with `kind: progress`, `result`, or
|
|
|
558
560
|
`error`. An accepted operation is progress, not success. The command follows
|
|
559
561
|
resumable durable operation streams and exits successfully only after every
|
|
560
562
|
required operation succeeds. Failed, blocked or awaiting-continuation outcomes
|
|
561
|
-
exit nonzero with the operation ID and
|
|
563
|
+
exit nonzero with the operation ID and the Failure Signal of
|
|
564
|
+
[Errors and diagnostics](#errors-and-diagnostics). The default
|
|
562
565
|
overall deadline is 300,000 ms; `--timeout-ms <positive-integer>` changes it.
|
|
563
566
|
Timeout errors preserve the operation ID and last observed event sequence;
|
|
564
567
|
rerun the same intent or use `ci package operation reconnect` to follow it.
|
|
@@ -1070,14 +1073,14 @@ ci package promote --backend-url https://ci.example.com \
|
|
|
1070
1073
|
--release release_123 --idempotency-key build-482-promote
|
|
1071
1074
|
|
|
1072
1075
|
ci package releases --backend-url https://ci.example.com \
|
|
1073
|
-
--organization
|
|
1076
|
+
--organization <organization-id> --package acme.analytics
|
|
1074
1077
|
|
|
1075
1078
|
ci package install --backend-url https://ci.example.com \
|
|
1076
|
-
--organization
|
|
1079
|
+
--organization <organization-id> --package acme.analytics \
|
|
1077
1080
|
--release release_123 --idempotency-key org-123-install-release-123
|
|
1078
1081
|
|
|
1079
1082
|
ci package update --backend-url https://ci.example.com \
|
|
1080
|
-
--organization
|
|
1083
|
+
--organization <organization-id> --installation installation_123 \
|
|
1081
1084
|
--release release_456 --idempotency-key org-123-update-release-456
|
|
1082
1085
|
```
|
|
1083
1086
|
|
|
@@ -1121,3 +1124,81 @@ application in the Dashboard External Apps page. The response shows
|
|
|
1121
1124
|
`clientSecret` once; store it server-side immediately, because CI keeps only its
|
|
1122
1125
|
hash. Each rotation invalidates the previous secret. See
|
|
1123
1126
|
[Provision a secret for a package-created application](../../../docs/reference/package-release-cli.md#provision-a-secret-for-a-package-created-application).
|
|
1127
|
+
|
|
1128
|
+
## Errors and diagnostics
|
|
1129
|
+
|
|
1130
|
+
Every `ci` command ends a failure with one Failure Signal: the Summary (what
|
|
1131
|
+
failed), the Cause (the error tag, its reason and identifiers), the Remedy (the
|
|
1132
|
+
steps that remove the Cause), the Retry Class and the Reference. The words
|
|
1133
|
+
follow the CLI Error Signal glossary of the project wiki. A Failure Signal
|
|
1134
|
+
holds only product-authored text and identifiers, never a Raw Message.
|
|
1135
|
+
|
|
1136
|
+
In text mode the failure is one labelled block on stderr:
|
|
1137
|
+
|
|
1138
|
+
```text
|
|
1139
|
+
Error: Skills still use the tool that this change removes.
|
|
1140
|
+
Cause: AiToolInstanceRepositoryError (referenced_by_skills); skillIds: skill-1, skill-2; toolFqn: com.acme.tools.search; toolInstanceId: tool-1
|
|
1141
|
+
Fix: 1. Remove the tool from these skills, or keep it declared in the package.
|
|
1142
|
+
2. Start a new operation after the fix.
|
|
1143
|
+
ci deploy --organization 0190a2b4-7c3e-7d1a-9f00-4b2c8e6d1a01 --declaration ./crm.ts
|
|
1144
|
+
Retry: terminal (the same command fails again until the Cause is fixed)
|
|
1145
|
+
Reference: Operation ID operation-1; Diagnostic ID diag-1
|
|
1146
|
+
```
|
|
1147
|
+
|
|
1148
|
+
- **Retry Class.** `retryable` means that a later attempt can pass. `terminal`
|
|
1149
|
+
means that the same command fails again until the Cause is fixed; a terminal
|
|
1150
|
+
Signal never advises a retry of the same operation.
|
|
1151
|
+
- **Remedy commands.** A Remedy step can carry a Remedy Action. The CLI prints
|
|
1152
|
+
the exact command line for it under the step: `new_operation` repeats your
|
|
1153
|
+
invocation with `--idempotency-key <new-key>` (and `--declaration <module>`
|
|
1154
|
+
in place of `--resume`), `continue_operation` prints
|
|
1155
|
+
`ci package operation continue`, `login` prints `ci login <API URL>`, and
|
|
1156
|
+
`diagnostics` prints `ci diagnostics show <diagnostic-id>`. A `401` reply
|
|
1157
|
+
adds a `ci login` step.
|
|
1158
|
+
- **JSON record.** With `--json`, and always for `ci transfer`, the failure is
|
|
1159
|
+
one record on stdout with `kind: "error"`, `summary`, `cause`, `remedy`
|
|
1160
|
+
(each step with its `command`), `retryClass`, `reference`, `nextAction` (the
|
|
1161
|
+
last Remedy command) and `diagnosticDetail`. The older fields of the
|
|
1162
|
+
`ci deploy`, `ci transfer` and `ci orgs` records stay.
|
|
1163
|
+
- **Exit codes.** A failed command exits `1` and an interrupted command exits
|
|
1164
|
+
`130`, for retryable and terminal failures alike.
|
|
1165
|
+
- **Older Backend.** A Backend that sends no Failure Signal gets a block built
|
|
1166
|
+
from the error, the HTTP status and the reply message.
|
|
1167
|
+
- **Malformed IDs.** `--organization`, `--operation`, `--diagnostic` and the
|
|
1168
|
+
`ci diagnostics show` ID are UUIDs. The CLI refuses another value before any
|
|
1169
|
+
request, for example
|
|
1170
|
+
`--operation must be an Operation ID (a UUID); got 'not-a-uuid'.`, with the
|
|
1171
|
+
Cause `InvalidIdOptionError` and a Remedy that names where to find the ID.
|
|
1172
|
+
- **Invalid request.** A `400` reply that names no reason prints
|
|
1173
|
+
`The backend rejected the request as invalid (HTTP 400): <METHOD> <path>.`
|
|
1174
|
+
and a Remedy step to check the values in the request.
|
|
1175
|
+
|
|
1176
|
+
### Diagnostic Detail
|
|
1177
|
+
|
|
1178
|
+
The Diagnostic Detail is the full failure behind a Diagnostic ID: the Raw
|
|
1179
|
+
Messages, the error chain, the stack and the log annotations. The Backend keeps
|
|
1180
|
+
it for 30 days by default. After a failure with a Diagnostic ID, the CLI reads
|
|
1181
|
+
the Diagnostic Detail with your own credential and prints it in a section under
|
|
1182
|
+
the block (or in `diagnosticDetail` with `--json`). When you cannot read it,
|
|
1183
|
+
the section names who can and the command to run. Read it again later:
|
|
1184
|
+
|
|
1185
|
+
```sh
|
|
1186
|
+
ci diagnostics show <diagnostic-id> [--organization <organization-id>] [--json]
|
|
1187
|
+
```
|
|
1188
|
+
|
|
1189
|
+
The command also accepts `--backend-url` and `--profile`. Without
|
|
1190
|
+
`--organization` it uses the Current Organization of your profile. With
|
|
1191
|
+
`--json` it prints the record.
|
|
1192
|
+
|
|
1193
|
+
The origin of the failure decides who can read its Diagnostic Detail:
|
|
1194
|
+
|
|
1195
|
+
| Failure origin | Readers |
|
|
1196
|
+
| --------------------------------- | ------------------------------------------------------------------ |
|
|
1197
|
+
| Package Operation | `extensions:manage` in the Organization, or `tenant:manage` |
|
|
1198
|
+
| HTTP request in an Organization | `organization:self_manage` in the Organization, or `tenant:manage` |
|
|
1199
|
+
| Tenant route or no signed-in user | `tenant:manage` |
|
|
1200
|
+
|
|
1201
|
+
Every caller sees the Failure Signal. Being the user whose request failed does
|
|
1202
|
+
not grant the Diagnostic Detail. A Host failure keeps its own Diagnostic ID and
|
|
1203
|
+
`ci package diagnostics trace`. See
|
|
1204
|
+
[Failure output and Diagnostic Detail](../../../docs/reference/package-release-cli.md#failure-output-and-diagnostic-detail).
|