@laburen/delta-cli 0.2.0-canary.10 → 0.2.0-canary.11

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.
@@ -19,7 +19,7 @@ The ids in the commands below are optional, also in `agents tools add` and `agen
19
19
  - More than 100: stderr says so and shows the command you ran with `<id>` placeholders; pass the id to use one that is not in the list.
20
20
  - `agents versions compare` (and the skills and MCP connections ones) without `--from` or `--to` always asks for the missing versions, even with only two; the second list leaves out the first one. With fewer than two versions it fails with `no_results`.
21
21
 
22
- If the CLI cannot ask, a missing id fails with `missing_arguments` (exit 2), `userActionRequired: true` and `choices` with up to 20 `{ id, name }` (the active version also has `current: true`), plus one `next` per choice: the command you ran with that id (secret values as `<value>`), `when` "Ask the user which one; do not choose yourself". In delete, revoke and remove those commands drop `--yes`, so choosing one still needs the user's approval of the delete. **If you are an AI agent: ask the user which one; never pick it yourself.** If you are not logged in, the error is `login_required` with its `next`. If the list cannot be fetched for another reason, it is the plain `missing_arguments` error. A missing id is checked after the flags: if a required flag is missing too, the error is `missing_required` and its `next` has the id as a placeholder (`laburen agents versions compare <agent_id> --from v1 --to <value>`).
22
+ If the CLI cannot ask, a missing id fails with `missing_arguments` (exit 2), `userActionRequired: true` and `choices` with up to 20 `{ id, name }` (the active version also has `current: true`), plus one `next` per choice: the command you ran with that id (secret values as `<value>`), `when` "Ask the user which one; do not choose yourself". In delete, revoke and remove those commands drop `--yes`, so choosing one still needs the user's approval of the delete. **If you are an AI agent: ask the user which one; never pick it yourself.** If you are not logged in, the error is `login_required` with its `next`. If the API rejects the list (for example, no organization in non-interactive mode, or no permission), you get that API error with its `next` (`--org <id>`, `laburen orgs list`); if the API cannot be reached, it is the plain `missing_arguments` error. A missing id is checked after the flags: if a required flag is missing too, the error is `missing_required` and its `next` has the id as a placeholder (`laburen agents versions compare <agent_id> --from v1 --to <value>`).
23
23
 
24
24
  ## Questions in create
25
25
 
@@ -63,9 +63,9 @@ laburen agents update <agent_id> --config @config.json --change-message "new pro
63
63
  laburen agents delete <agent_id> # needs the admin permission
64
64
  ```
65
65
 
66
- `agents update` creates a new version only with `--config`, `--skills` or `--mcp-connections`; without them it only edits the name and description, and `--change-message` is not saved (it says so on stderr and goes on). The new version is not activated unless you pass `--activate`; if it stays inactive, stderr says `Created version <n> (not active). Activate it with: ...`.
66
+ `agents update` creates a new version only with `--config`, `--skills` or `--mcp-connections`; without them it only edits the name and description, and `--change-message` is not saved (it says so on stderr and goes on). The new version is not activated unless you pass `--activate`; if it stays inactive, stderr says `Created version <n> (not active). Activate it with: ...`, also with `--json` (stdout keeps only the JSON).
67
67
 
68
- `agents update --config` **edits**: the new version is the latest one with only the config keys you send replaced. `agents versions create --config` **writes the whole version**: omitted keys go back to their defaults, there are no skills or MCP connections unless you send `--skills` and `--mcp-connections`, and it never activates (it prints the same notice).
68
+ `agents update --config` **edits**: the new version is the latest one with only the config keys you send replaced. Each top-level key is replaced whole, with no deep merge: `--config '{"knowledge":{"project_ids":[]}}'` drops `knowledge.mode`, so send every field of a key you change. `agents versions create --config` **writes the whole version**: omitted keys are not stored and take their default value on each turn (no `history`: 5 exchanges without tool calls; no `knowledge`: no knowledge search), so `versions get` does not show them and `compare` shows them as `null`; if a default changes later, a version without that key runs with the new one, there are no skills or MCP connections unless you send `--skills` and `--mcp-connections`, and it never activates (it prints the same notice).
69
69
 
70
70
  ```sh
71
71
  laburen agents update <agent_id> --config '{"prompt":[{"type":"text","content":"Be brief."}]}' --change-message "shorter answers" # the rest of the config stays
@@ -84,7 +84,9 @@ laburen agents versions delete <agent_id> <version_id>
84
84
  laburen agents versions compare <agent_id> --from <version_id> --to <version_id>
85
85
  ```
86
86
 
87
- Without `--json`, `compare` prints one difference per line, with the same rule as in [Output and errors](output-and-errors.md): a string longer than 120 characters, or a list of only text blocks (the prompt), shows its first 60 characters (`"You are a…" (N chars)`); any other list or object is summarized (`<list, N items>`, `<object, N keys>`) only when its JSON is longer than 120 characters, and a shorter one is printed whole. Use `--json` for the full values. For MCP connections the compared field is `url_host` (the `url` is always `[REDACTED]`).
87
+ A new version gets the highest `version_number` that exists plus one. Deleting the latest version frees its number: the next version reuses it (delete version 5 of 5 and the next one is 5 again). The same goes for skill and MCP connection versions.
88
+
89
+ Without `--json`, `compare` prints one difference per line, with the same rule as in [Output and errors](output-and-errors.md): a string longer than 120 characters, or a list of only text blocks (the prompt), shows its first 60 characters (`"You are a…" (N chars)`); any other list or object is summarized (`<list, N items>`, `<object, N keys>`) only when its JSON is longer than 120 characters, and a shorter one is printed whole. When both values are objects and one of them is that long, the line names the top-level keys that changed instead (`tree: changed SKILL.md; added references/b.md; removed references/a.md`), up to 5 keys per group and then `(+N more)`. When both values are non-empty lists and one of them is that long, the line names the items that changed, were added or were removed (`tools: changed tool_b, tool_d; added tool_x`), with the same limit: each item is named by its `id` (or `skill_id`, `connection_id`, `name`, `type`) when every item has one and none repeats, and by its position otherwise (`changed [1]; added [2]`); same items in another order show as `same items, reordered`. Use `--json` for the full values. For MCP connections the compared field is `url_host` (the `url` is always `[REDACTED]`).
88
90
 
89
91
  `--base-version-id <id>` makes the call fail with `409 base_version_mismatch` if that is not the latest version; `--base-version-id null` sends `null` (the resource has no versions yet; on a resource that already has versions it fails with `409 base_version_mismatch`). In a flag that takes a string and not null (`--name null`) `null` is just the text. The only string flag where `null` means "clear" is `tokens update --description null`.
90
92
 
@@ -92,6 +94,8 @@ Without `--json`, `compare` prints one difference per line, with the same rule a
92
94
 
93
95
  Tools (reads the latest version, changes `config.tools`, and creates a new version; the new version is not active unless you pass `--activate`):
94
96
 
97
+ > **Warning:** `tools add` and `tools remove` start from the **latest** version, not the active one (so does `agents update --config`). If the latest version is a draft that is not active, the new version keeps the draft's tools and drops whatever only the active version had. Check `laburen agents versions list <agent_id>` first; if the latest is not the active one, activate or delete the draft before you change tools.
98
+
95
99
  ```sh
96
100
  laburen agents tools add <agent_id> --tool '{"type":"send_files"}'
97
101
  laburen agents tools add <agent_id> --tool @tool.json
@@ -108,6 +112,7 @@ laburen agents tools add --schema # JSON Schema of a tool and of the response;
108
112
  ```sh
109
113
  laburen agents run <agent_id> "Do you have the XR 150 in stock?"
110
114
  echo "Hello" | laburen agents run <agent_id> # no message argument: reads stdin when it is not a terminal
115
+ slow-command | laburen agents run <agent_id> - # - waits for stdin until it ends
111
116
  laburen agents run <agent_id> --thread <thread_id> "And in red?"
112
117
  laburen agents run <agent_id> --file https://example.com/menu.pdf "Summarize this"
113
118
  laburen agents run <agent_id> --version-id <version_id> --context "The user is a VIP" "Hi"
@@ -116,17 +121,17 @@ laburen agents run <agent_id> "Hi" --json # waits for the end and prints
116
121
 
117
122
  When a delete fails with `resource_in_use`, `details.agent_versions` lists the versions that still assign the skill or MCP connection (or pin one of its versions) as `[{ agent_id, version_id, is_active }]`, without repeats (`details.agent_ids` lists the agents); versions are immutable. The CLI `next` has one command per entry: (1) for `is_active: true`, make the agent stop using the resource: `laburen agents update <agent_id> --skills '[]' --activate` (or `--mcp-connections '[]'`, or the list without that resource); (2) `laburen agents versions delete <agent_id> <version_id>` for each `is_active: false` entry, and also for the version that was active before step 1 (it is inactive now and still assigns the resource; the new active version cannot be deleted); (3) retry the delete. Or delete the agent. Deleting agents, skills and MCP connections needs the `admin` permission, and permissions are independent: a token with only `admin` cannot read.
118
123
 
119
- Runs one turn and shows it live. stdout gets only the text of the answer; reasoning, tool calls and results, sources and the footer go to stderr, so `laburen agents run ... > answer.txt` saves just the answer. The footer has the `thread`, tokens, credits (when the API reports a cost), the duration and the command to continue (`continue: laburen agents run <agent_id> --thread <thread_id> "…"`). If the agent handed the conversation to a human, the footer says `handed off to a human; the AI is off in this thread`: continuing that thread fails with `ai_disabled_for_conversation`. If the turn stopped at the step limit without a final answer, stderr says `Warning: The run stopped at the step limit (max_steps N) before a final answer.` (N is `--max-steps` or the default); the warning does not appear when the turn ended with text.
124
+ Runs one turn and shows it live. stdout gets only the text of the answer; reasoning, tool calls and results, sources and the footer go to stderr, so `laburen agents run ... > answer.txt` saves just the answer. The footer has the `thread`, tokens, credits (when the API reports a cost), the duration and the command to continue (`continue: laburen agents run <agent_id> --thread <thread_id> <message>`; put your next message instead of `<message>`). If the agent handed the conversation to a human, the footer says `handed off to a human; the AI is off in this thread`: continuing that thread fails with `ai_disabled_for_conversation`. If the turn stopped at the step limit without a final answer, stderr says `Warning: The run stopped at the step limit (max_steps N) before a final answer.` (N is `--max-steps` or the default); the warning does not appear when the turn ended with text.
120
125
 
121
126
  | Flag | Body field | Note |
122
127
  |---|---|---|
123
- | `[message]` or stdin | `messages` | With `--file`, the message has a text part and one `file` part per URL; with only `--file` the message is just the files |
128
+ | `[message]`, `-` or stdin | `messages` | With `--file`, the message has a text part and one `file` part per URL; with only `--file` the message is just the files |
124
129
  | `--thread <id>` | `memory.thread` | Continues a previous conversation |
125
130
  | `--resource <id>` | `memory.resource` | Your own id for the end user |
126
131
  | `--file <url>` (repeatable) | `messages[0].parts[]` | The media type comes from the URL extension; if it is unknown it fails with `invalid_flag_value` and you send the part with `--data` |
127
132
  | `--instructions <text\|@file>` | `instructions` | Replaces the prompt for this run. Needs `write` permission (the API rejects it otherwise) |
128
133
  | `--model <id>` | `model` | Same permission |
129
- | `--reasoning <level>` | `model_settings.reasoning` | `off`, `low`, `medium`, `high` or `max`; same permission |
134
+ | `--reasoning <level>` | `model_settings.reasoning` | `off`, `low`, `medium`, `high` or `max`; same permission. Only for models with reasoning: on a model without it any level, `off` included, fails with `model_settings.reasoning is not allowed`. `laburen models list` shows which models reason and their levels |
130
135
  | `--max-steps <n>` | `max_steps` | Same permission |
131
136
  | `--version-id <version_id>` | `versions.agents[<agent_id>].version_id` | Runs that version instead of the active one; the `continue:` line of the footer repeats it |
132
137
  | `--context <text>` (repeatable) | `context[]` | Extra text for the model |
@@ -134,13 +139,38 @@ Runs one turn and shows it live. stdout gets only the text of the answer; reason
134
139
  | `--verbose` | | Shows the result of each tool in full instead of cut to one line |
135
140
  | `--json` | | Uses `/generate`: prints the final JSON on stdout and nothing else |
136
141
 
137
- The message comes from the argument; if there is none, from `--file` or the `messages` of `--data`; only if none of those exist and stdin is not a terminal is stdin read. Without any message it fails with `missing_required` (exit 2).
142
+ With `--data` you send the body yourself. `messages` is a string or a list of user messages (`role` is always `user`; each part is `{ "type": "text", "text" }` or `{ "type": "file", "url", "media_type", "filename"? }`). `contact` (`first_name`, `last_name`, `email`, `phone_number`, all optional) is used only when `memory.resource` creates a new contact:
143
+
144
+ ```sh
145
+ laburen agents run <agent_id> --data @run.json --json
146
+ ```
147
+
148
+ ```json
149
+ {
150
+ "messages": [{ "role": "user", "parts": [{ "type": "text", "text": "Do you have the XR 150 in stock?" }] }],
151
+ "memory": { "resource": "customer-42" },
152
+ "contact": { "first_name": "Ana", "last_name": "Perez", "email": "ana@example.com" }
153
+ }
154
+ ```
155
+
156
+ `"messages": "Do you have the XR 150 in stock?"` is the same message as a string. `laburen agents run --schema` prints the whole body schema.
157
+
158
+ Things to know when you run turns:
159
+
160
+ - `contact` is not shown to the model: it only fills in the profile of the contact that `memory.resource` creates. To give the model data about the user, use `--context`.
161
+ - The `continue:` line does not repeat `--resource`: the thread already knows its resource, and the server uses it.
162
+ - There is no command to list threads or to read the messages of a conversation: the history is seen in the dashboard. Keep the `memory.thread` of each run if you want to continue it.
163
+ - The contacts that `--resource` (or `memory.resource` with `contact` in `--data`) creates cannot be deleted with the CLI.
164
+ - A turn that stopped at `--max-steps` and is continued with `--thread`: by default the agent keeps no tool calls in its history (`config.history.tool_calls.mode` is `off`), so the results of the tools of the cut turn are not in the history and the model may call those tools again. To keep them, set the mode on the agent: `laburen agents update <agent_id> --config '{"history":{"tool_calls":{"mode":"all"}}}' --activate` (or `{"mode":"recent","turns":<n>}`; `exclude_tools` leaves some tools out). `history` is replaced whole, so send `exchanges` and `reasoning` too if you had changed them.
165
+ - `--version-id` needs only the `query` permission, also for a version that is not active: that is on purpose (the API contract says so), so a token that can only run agents can try a version before it is activated.
166
+
167
+ The message comes from the argument; if there is none, from `--file` or the `messages` of `--data`; only if none of those exist and stdin is not a terminal is stdin read. In that case the CLI waits at most 500 ms for stdin to start sending: if nothing arrives (an open stdin that sends nothing, as when an AI agent runs the CLI), it does not wait any longer and fails with `missing_required` (exit 2); once data starts, it reads until stdin ends. Pass `-` as the message to read stdin until it ends with no time limit (for a slow command in the pipe); if stdin is a terminal, stderr says `Reading the message from stdin (end with Ctrl-D)...`. `-` together with `--data -` fails with `invalid_flag_value`: there is only one stdin. Without any message it fails with `missing_required` (exit 2).
138
168
 
139
- Ctrl+C stops reading and exits with `130`: the turn keeps running on the server and is billed. stderr says so and, if the thread was already known, prints the `continue:` command. If the turn fails midway, what was already printed stays, and the error goes to stderr (exit 1); its `next` is the `continue:` command of the thread, not `--help`. If stdout is closed (`| head -1`) the CLI stops quietly and still prints the `continue:` line on stderr; a closed stderr also stops it quietly. A turn that takes more than 10 minutes fails with `turn_deadline_exceeded`.
169
+ Ctrl+C stops reading and exits with `130`: the turn keeps running on the server and is billed. stderr says so and, if the thread was already known, prints the `continue:` command. If the turn fails midway, what was already printed stays, and the error goes to stderr (exit 1); its `next` is not `--help`. A failed turn may not have been saved, so its thread may not exist: in a new conversation the `next` is the same command again (it starts a new conversation), and only when you passed `--thread` (or `memory.thread` in `--data`) is the `next` the `continue:` command of that thread. If stdout is closed (`| head -1`) the CLI stops quietly and still prints the `continue:` line on stderr; a closed stderr also stops it quietly. A turn that takes more than 10 minutes fails with `turn_deadline_exceeded`.
140
170
 
141
171
  ## Skills
142
172
 
143
- There is no `skills update`: to change a skill, create a version.
173
+ There is no `skills update`: to change a skill, create a version. A skill has a `description` (from the `SKILL.md` frontmatter of its active version or, with none active, of its latest one; `null` if it has no versions): `skills list` shows it as a column and `skills get` as a field.
144
174
 
145
175
  ```sh
146
176
  laburen skills list # --search <name>
@@ -4,9 +4,9 @@
4
4
 
5
5
  - stdout: the data, and the error JSON (see below).
6
6
  - stderr: notices, the login URL, the version notice, and errors for humans. `agents run` without `--json` writes all its errors to stderr (as JSON in non-interactive mode), including usage errors such as a missing `<agent_id>`, so stdout keeps only the text of the turn.
7
- - `Warning: <message>` on stderr for each item of `warnings` in an API response, read from the top-level `warnings` and from a nested `version.warnings` (as in `agents create` and `agents update`) (also with `--json`, where stdout stays the untouched JSON).
7
+ - `Warning: <message>` on stderr for each item of `warnings` in an API response, read from the top-level `warnings` and from a nested `version.warnings` (as in `agents create` and `agents update`) (also with `--json`, where stdout stays the untouched JSON). Without `--json`, the card on stdout does not repeat those `warnings`: each one is shown once, on stderr; use `--json` to read their other fields (such as `code`).
8
8
 
9
- Without `--json`, lists print as a table and single items as `key: value` lines (an empty `changed_fields` shows as `changed_fields: []`; an empty `warnings` list and empty objects are hidden). Lists of agents, versions, skills and the like show a few columns and cut long text to the width of a terminal (the ID column is never cut, and piped output is not cut); `get` or `--json` shows every field. In a `get` card, nested objects are indented under their key; in a table cell they are one-line JSON. Lists of strings appear as `a,b`. `versions compare` prints one difference per line with one rule for every resource: a string longer than 120 characters, or a list of only text blocks (the prompt), shows its first 60 characters: `"<first 60 chars>…" (N chars)`; any other list or object is summarized as `<list, N items>` or `<object, N keys>` only when its JSON is longer than 120 characters, and a shorter one is printed whole (`[{"skill_id":"…","strategy":"pin"}] → […"latest"]`); use `--json` for the full values. `--json` is never changed by any of this. Table columns follow the order in which keys appear, including columns that are `null` in every row. Control characters in values from the server (`\n`, `\t`, `ESC`...) are printed escaped (`\n`, `\x1b`), never raw: in tables, cards, errors, `next` lines and the labels of the questions. An empty list prints `No results.`
9
+ Without `--json`, lists print as a table and single items as `key: value` lines (an empty `changed_fields` shows as `changed_fields: []`; an empty `warnings` list and empty objects are hidden). Lists of agents, versions, skills and the like show a few columns and cut long text to the width of a terminal (the ID column is never cut, and piped output is not cut); `get` or `--json` shows every field. In a `get` card, nested objects are indented under their key; in a table cell they are one-line JSON. Lists of strings appear as `a,b` in a table cell; in a card they go one `- item` per line under their key, also with a single item, so a list never looks like a single value. `versions compare` prints one difference per line with one rule for every resource: a string longer than 120 characters, or a list of only text blocks (the prompt), shows its first 60 characters: `"<first 60 chars>…" (N chars)`; any other list or object is summarized as `<list, N items>` or `<object, N keys>` only when its JSON is longer than 120 characters, and a shorter one is printed whole (`[{"skill_id":"…","strategy":"pin"}] → […"latest"]`). When both values are objects and one of them is that long, the line names the top-level keys that changed instead (`tree: changed SKILL.md; added references/b.md; removed references/a.md`), up to 5 keys per group and then `(+N more)`. When both values are non-empty lists and one of them is that long, the line names the items that changed, were added or were removed (`tools: changed tool_b, tool_d; added tool_x`), with the same limit: each item is named by its `id` (or `skill_id`, `connection_id`, `name`, `type`) when every item has one and none repeats, and by its position otherwise (`changed [1]; added [2]`); same items in another order show as `same items, reordered`. Use `--json` for the full values. `--json` is never changed by any of this. Table columns follow the order in which keys appear, including columns that are `null` in every row. Control characters in values from the server (`\n`, `\t`, `ESC`...) are printed escaped (`\n`, `\x1b`), never raw: in tables, cards, errors, `next` lines and the labels of the questions. An empty list prints `No results.`
10
10
 
11
11
  If stdout is closed early (for example `laburen agents list | head -2`), the CLI exits quietly. The exception is `agents run`: it keeps going and still writes the footer and the `continue:` line on stderr (a closed stderr also stops it quietly).
12
12
 
@@ -48,7 +48,7 @@ With `--json` or in non-interactive mode, the error goes to stdout as JSON:
48
48
  - `issues`: a validation error that names a field (`details.field`) has them too, as the API sends them: `[{ "field": "...", "message": "..." }]`. `field` is the exact place, for example `config.tools[3].url`; an unknown key gets one issue per key, with the key's name in `field` (`harness_type`).
49
49
  - `choices`: only when an id is missing and the CLI cannot ask: up to 20 `[{ "id": "...", "name": "..." }]`, with one `next` per choice. The current one (the active version, the organization in use) also has `"current": true`.
50
50
  - `details`: only when there are any: the API `details`, or for `network_error` the `cause` reported by the SDK.
51
- - `next`: commands that fix the error, each with `command` and `when`. They are the real command you ran (path, ids and flags) with what is missing added, so you can run them as they are once the placeholders are filled in. A placeholder is a word in angle brackets: `<value>` is a value you type (a required flag that was missing, or a secret that was not copied), and `<id>`, `<version_id>` or `<agent_id>` is an id you get from a `list` or from the user. The value of a secret flag (`--token`, `-t`, `--refresh-token`, `--data`, `--headers`, `--config`, `--tool`, `--files`, `--value`, `--secret`, `--password`) is never copied, in any `next` or notice: it becomes `<value>` (for example `--headers <value>`), so fill it back in before running the command. In `--url` only the user and password and the values of the query and the fragment become `<value>` (`https://u:<value>@host/path?key=<value>#tok=<value>`); the rest stays so the command still points to the right server. When `npx` runs the CLI (`npx @laburen/delta-cli ...`), commands in `next`, and a `run laburen ...` inside `when`, start with `npx @laburen/delta-cli` instead of `laburen`. A `laburen` installed globally keeps `laburen` even when the program that runs it was started with npx. Every suggested command (in `next` and in notices) keeps the global flags you passed (`--org`, `--api-url`, `--global-config`, `--json`) unless it already has them, so it runs against the same API, folder and organization; a `--help` command does not get them, and the `next` that reruns a command without `--org` (after `organization_mismatch`) leaves `--org` out on purpose.
51
+ - `next`: commands that fix the error, each with `command` and `when`. They are the real command you ran (path, ids and flags) with what is missing added, so you can run them as they are once the placeholders are filled in. A placeholder is a word in angle brackets: `<value>` is a value you type (a required flag that was missing, or a secret that was not copied), and `<id>`, `<version_id>` or `<agent_id>` is an id you get from a `list` or from the user. The value of a secret flag (`--token`, `-t`, `--refresh-token`, `--data`, `--headers`, `--config`, `--tool`, `--files`, `--value`, `--secret`, `--password`) is never copied, in any `next` or notice: it becomes `<value>` (for example `--headers <value>`), so fill it back in before running the command. In `--url` only the user and password and the values of the query and the fragment become `<value>` (`https://u:<value>@host/path?key=<value>#tok=<value>`); the rest stays so the command still points to the right server. When `npx` runs the CLI (`npx @laburen/delta-cli ...`), commands in `next`, and a `run laburen ...` inside `when`, start with `npx @laburen/delta-cli` instead of `laburen`. A `laburen` installed globally keeps `laburen` even when the program that runs it was started with npx. Every suggested command (in `next` and in notices) keeps the global flags you passed (`--org`, `--api-url`, `--global-config`, `--json`) unless it already has them, so it runs against the same API, folder and organization; a `--help` command does not get them, the `Created version <n> (not active)` notice leaves `--json` out (it only changes how this run printed), and the `next` that reruns a command without `--org` (after `organization_mismatch`) leaves `--org` out on purpose.
52
52
 
53
53
  A usage error from the argument parser (`unknown option ...`) never repeats a flag value, secret or not: `--any-flag=x` is shown as `--any-flag=<value>`.
54
54
 
@@ -59,18 +59,18 @@ CLI reasons: `login_required`, `login_cancelled`, `cancelled`, `missing_argument
59
59
  - `cancelled`: Ctrl-C, Esc or Ctrl-D at a question, or No at a confirmation (exit 1). Nothing was changed and there is no `next`.
60
60
  - `login_cancelled`: Ctrl-C while `laburen login` waits for the approval in the browser (exit 1). It is a reason of its own, not `cancelled`: nothing was saved, and the next step is to run `laburen login` again.
61
61
  - `confirmation_required`: a delete or revoke needs approval and the CLI cannot ask (exit 2). The JSON also has `"userActionRequired": true`; `next` is the same command with `--yes`. Ask the user and run it only if they approve; never add `--yes` on your own.
62
- - `missing_arguments`: an id is missing. When the CLI could list them, the JSON has `"userActionRequired": true` and `choices`; ask the user which one and run its `next`. Do not choose yourself. In a delete or revoke, those `next` have no `--yes`: running one asks for (or fails with) `confirmation_required`.
62
+ - `missing_arguments`: an id is missing. When the CLI could list them, the JSON has `"userActionRequired": true` and `choices`; ask the user which one and run its `next`. If the API rejects the list (no organization, no permission) you get that API error instead, with its `next`. Do not choose yourself. In a delete or revoke, those `next` have no `--yes`: running one asks for (or fails with) `confirmation_required`.
63
63
  - `no_results`: an id was missing and there is nothing to pick from (exit 1); `next` creates one, with the required flags of the `create` as `<value>`.
64
64
  - `missing_required`: lists every required option that is missing. A missing id in the same command shows up in `next` as a placeholder (`<agent_id>`).
65
65
  - `config_required`: `agents create` got `skills`, `mcp_connections` or `activate` without `config` (exit 2). Nothing is created; `next` is your command plus `--config <value>`.
66
66
  - `agent_has_no_version` (exit 1): `agents tools add` on an agent with no versions; there is no config to add the tool to. `next` is `agents versions create <agent_id> --config @config.json` (a file name to create; the CLI does not mask it as `<value>`).
67
67
  - `invalid_link`: `.laburen/link.json` is broken, or `.laburen` exists and is not a folder (in that case no command falls back to the `link.json` of a parent folder).
68
68
  - `auth_lock_timeout`: another `laburen` held the credentials lock too long; `next` is `rm "<lock file>"`.
69
- - `network_error`: the API could not be reached (or did not answer in time).
69
+ - `network_error`: the API could not be reached (or did not answer in time). The network timeout is fixed: there is no flag or environment variable to change it. Each request waits 30 seconds per attempt; a GET, or a call that carries an `Idempotency-Key`, is retried up to 2 times. `agents run` waits up to 630 seconds (10.5 minutes) for the API to answer, and without `--json` it also fails if the live stream sends nothing for 45 seconds.
70
70
 
71
71
  Other reasons you may meet (API codes):
72
72
 
73
- - `invalid_skill`: the skill does not follow the format; `details.reason` is `forbidden_path` (only `SKILL.md` and `references/**`), `invalid_character`, `invalid_frontmatter`, `name_mismatch` (frontmatter `name` differs from the skill name), `limit_exceeded` or `no_active_version`.
73
+ - `invalid_skill`: the skill does not follow the format; `details.reason` is `forbidden_path` (only `SKILL.md` and `references/**`), `invalid_character`, `invalid_frontmatter`, `missing_skill_md` (no `SKILL.md` among the files), `name_mismatch` (frontmatter `name` differs from the skill name), `limit_exceeded` or `no_active_version`.
74
74
  - `conversation_not_found`: the `memory.thread` does not exist or belongs to another organization or agent.
75
75
  - `thread_resource_mismatch`: `memory.resource` is not the one that owns the `memory.thread`; send the same resource the thread started with.
76
76
  - `ai_disabled_for_conversation`: a human took over the conversation, so the turn does not run. `next` is the same command without `--thread`: start a new conversation.
@@ -78,14 +78,14 @@ Other reasons you may meet (API codes):
78
78
  - An attachment that could not be downloaded says the HTTP status or network error and the host; the url must be public and downloadable without logging in.
79
79
  - `mcp_server_unreachable` (400): the API could not connect to the MCP server when listing its tools; `details.connection_id` says which connection. Saving an agent `tools` filter with a MCP that is down does not fail with it: it saves and returns a `mcp_tools_unverified` warning. It is not retried automatically; check the URL and headers and run it again. It is raised only by the management API: a turn with a MCP that is down does not fail with it. `next` is `mcp connections versions list <connection_id>` (its HOST column shows where each version points).
80
80
  - `resource_in_use`: a skill or MCP connection that agent versions still assign (or pin a version of); `details.agent_versions` lists them as `[{ agent_id, version_id, is_active }]` (no repeats), `details.agent_ids` the agents and `details.versions_count` how many versions. Versions are immutable: update the agent so the active version stops using it, delete the inactive versions that still assign it (never the active one), then retry (recipe in SKILL.md).
81
- - `idempotency_key_in_progress`: the first request with that idempotency key is still running and may finish. Do not rerun the command as it is: a rerun sends a new request (a new key) and can duplicate what the first one does. Wait, then check with `list`/`get` that it did not apply, and only then run it again. The `next` is that `list` (for a create or update); `agents run` has none, because the CLI cannot show a turn in progress.
81
+ - `idempotency_key_in_progress`: the CLI only gets it on its own retry: the first attempt failed or took too long (a timeout), the CLI retried it with the same key, and the server is still processing that first request, which may finish and apply. The message says so. Do not rerun the command as it is: a rerun sends a new request (a new key) and can duplicate what the first one does. Wait, then check with `list`/`get` that it did not apply, and only then run it again. The `next` is that `list` (for a create or update); `agents run` has none, because the CLI cannot show a turn in progress.
82
82
  - `model_provider_auth_failed`: the model provider rejected the platform's credentials, even after the platform tried its fallback models; not retryable and not caused by your request. If it persists, contact support.
83
83
  - `internal_invariant_violation` (500): a bug on the server; keep the `request_id` and report it.
84
84
  - In the SDK, an error that arrives inside the `agents.stream` stream carries its HTTP `status` and `shouldRetry`, like any `LaburenApiError`. The CLI error JSON has no HTTP status and no `retryable` (`agents run --json` uses `generate`, not the stream).
85
85
  - `insufficient_permissions`: the token lacks a permission. They are independent (`query`, `read`, `write`, `admin`); deleting agents, skills and MCP connections needs `admin`.
86
86
  - `invalid_shell` (CLI, exit 2): `laburen completion` got a shell it does not support; the message lists them.
87
87
 
88
- Some API errors come with `next` too: `organization_access_denied` → `laburen orgs list` (without the bad `--org`); `insufficient_permissions` → `laburen whoami` (shows the permissions of the token you used); `idempotency_key_in_progress` → the `list` of the resource the command creates or edits, to check before running again (none for `agents run`); a model or reasoning level the API does not offer (`invalid_request`/`invalid_agent_config` on `model`, `config.model.id` or `reasoning`, with a message that says it is not offered) → `laburen models list`; a run where the version has the `thinking` tool and the model reasons (`invalid_request`, `model_settings.reasoning`) → the same command with `--reasoning off` (only if the model can turn it off) and `laburen agents versions list <agent_id>` (run a version without the tool with `--version-id`); `skill_name_taken` → `laburen skills list`; `mcp_connection_name_taken` → `laburen mcp connections list --search <name>` (the `--name` you passed); `resource_in_use` → with `details.agent_versions`, one `laburen agents versions delete <agent_id> <version_id>` per inactive version and one `agents versions get` per active one (never a delete of the active version); without it, one `laburen agents versions list <agent_id>` per id in `details.agent_ids`; `*_not_found` → the `list` of that resource (with the parent id filled in); `version_in_use` → `versions activate` of another version; a missing organization header (`invalid_request`) → `laburen orgs list` and the command you ran with `--org <id>`. Any other request the API rejects as invalid (`invalid_request_error`) without its own `next` gets `laburen <command> --help`.
88
+ Some API errors come with `next` too: `organization_access_denied` → `laburen orgs list` (without the bad `--org`); `insufficient_permissions` → `laburen whoami` (shows the permissions of the token you used); `idempotency_key_in_progress` → the `list` of the resource the command creates or edits, to check before running again (none for `agents run`); a model or reasoning level the API does not offer (`invalid_request`/`invalid_agent_config` on `model`, `config.model.id` or `reasoning`, with a message that says it is not offered) → `laburen models list`; a run where the version has the `thinking` tool and the model reasons (`invalid_request`, `model_settings.reasoning`) → the same command with `--reasoning off` (only if the model can turn it off) and `laburen agents versions list <agent_id>` (run a version without the tool with `--version-id`); `skill_name_taken` → `laburen skills list`; `mcp_connection_name_taken` → `laburen mcp connections list --search <name>` (the `--name` you passed); `resource_in_use` → with `details.agent_versions`, one `laburen agents versions delete <agent_id> <version_id>` per inactive version and one `agents versions get` per active one (never a delete of the active version); without it, one `laburen agents versions list <agent_id>` per id in `details.agent_ids`; `*_not_found` → the `list` of that resource (with the parent id filled in); `version_in_use` → `versions activate` of another version; a missing organization header (`invalid_request`) → `laburen orgs list` and the command you ran with `--org <id>`. Any other request the API rejects as invalid (`invalid_request_error`, such as `invalid_agent_config` or `invalid_request` with `issues`) without its own `next` gets the command you ran, with your ids and values (secrets as `<value>`), to fix the fields in `issues` and run again, plus `laburen <command> --schema` when the command has a request body (`--help` when it does not).
89
89
 
90
90
  ## Exit codes
91
91
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@laburen/delta-cli",
3
- "version": "0.2.0-canary.10",
3
+ "version": "0.2.0-canary.11",
4
4
  "description": "Laburen CLI to manage agents from the terminal",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -27,7 +27,7 @@
27
27
  },
28
28
  "dependencies": {
29
29
  "@clack/prompts": "1.8.1",
30
- "@laburen/delta-sdk": "1.5.0-canary.10",
30
+ "@laburen/delta-sdk": "1.5.0-canary.11",
31
31
  "@vercel/detect-agent": "1.2.7",
32
32
  "commander": "14.0.3",
33
33
  "picocolors": "1.1.1"