@laburen/delta-cli 0.2.0-canary.10 → 0.2.0-canary.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.
- package/dist/commands/agent-run/render.js +1 -1
- package/dist/commands/agent-run/render.js.map +1 -1
- package/dist/commands/agent-run.js +80 -18
- package/dist/commands/agent-run.js.map +1 -1
- package/dist/commands/agent-tools/shared.d.ts +1 -1
- package/dist/commands/agent-tools/shared.js +3 -3
- package/dist/commands/agent-tools/shared.js.map +1 -1
- package/dist/commands/secret-notice.d.ts +4 -0
- package/dist/commands/secret-notice.js +21 -0
- package/dist/commands/secret-notice.js.map +1 -0
- package/dist/errors.d.ts +2 -0
- package/dist/errors.js +44 -4
- package/dist/errors.js.map +1 -1
- package/dist/generated/commands.js +7 -1
- package/dist/generated/commands.js.map +1 -1
- package/dist/generated/schemas.js +8 -6
- package/dist/generated/schemas.js.map +1 -1
- package/dist/invocation.d.ts +2 -0
- package/dist/invocation.js +2 -0
- package/dist/invocation.js.map +1 -1
- package/dist/operations/tables.js +9 -0
- package/dist/operations/tables.js.map +1 -1
- package/dist/output.js +140 -9
- package/dist/output.js.map +1 -1
- package/dist/pickers.d.ts +1 -1
- package/dist/pickers.js +8 -2
- package/dist/pickers.js.map +1 -1
- package/dist/program.js +2 -2
- package/dist/program.js.map +1 -1
- package/dist/session.js +10 -2
- package/dist/session.js.map +1 -1
- package/docs/SKILL.md +23 -10
- package/docs/references/auth-and-organizations.md +1 -1
- package/docs/references/commands.md +81 -11
- package/docs/references/output-and-errors.md +8 -8
- package/package.json +2 -2
- package/dist/commands/token-notice.d.ts +0 -4
- package/dist/commands/token-notice.js +0 -13
- package/dist/commands/token-notice.js.map +0 -1
package/docs/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: laburen-cli
|
|
3
|
-
description: Use the `laburen` CLI to create, run and operate Laburen agents, skills, MCP connections and API tokens from the terminal, without the dashboard. Use when a task says "create an agent", "run or test an agent", "add a tool", "upload a skill", "connect an MCP", "version or activate an agent", or "create the worker token".
|
|
3
|
+
description: Use the `laburen` CLI to create, run and operate Laburen agents, skills, MCP connections, website chat widgets and API tokens from the terminal, without the dashboard. Use when a task says "create an agent", "run or test an agent", "add a tool", "upload a skill", "connect an MCP", "version or activate an agent", "put the agent on a website", "add a chat widget", or "create the worker token".
|
|
4
4
|
metadata:
|
|
5
5
|
package: "@laburen/delta-cli"
|
|
6
6
|
---
|
|
@@ -12,7 +12,7 @@ metadata:
|
|
|
12
12
|
|
|
13
13
|
## When to use
|
|
14
14
|
|
|
15
|
-
Use this skill when you need to manage Laburen resources from a terminal or from an AI agent: agents and their versions, skills, MCP connections, API tokens, and which organization you are working in.
|
|
15
|
+
Use this skill when you need to manage Laburen resources from a terminal or from an AI agent: agents and their versions, skills, MCP connections, website chat widgets, API tokens, and which organization you are working in.
|
|
16
16
|
|
|
17
17
|
## How to use
|
|
18
18
|
|
|
@@ -48,6 +48,7 @@ Tool rules the API enforces (the wizard and `--schema` already follow them): eve
|
|
|
48
48
|
- Fields of each tool (`--schema` prints them): `http` takes `url` (required), `method`, `name`, `description`, `headers`, `body`, `query_parameters`, `path_variables` and `with_approval` (`true` = a person must approve each call); `thinking` takes `instructions` and `max_thoughts` (an integer, at least 1); `send_files` and `request_human` take nothing besides `type` and an optional `id`. Any other key fails with `invalid_request` (one issue per unknown key, with its name in `field`). `agents tools add --json` and `agents tools remove --json` print the agent with its new `version` inside.
|
|
49
49
|
- Items of the http tool's `headers`, `body`, `query_parameters` and `path_variables` are `{ "key", "value"?, "description"?, "is_user_provided"?, "required"?, "accepted_values"?, "type"? }` (only `key` is required), for example `{"key":"Authorization","value":"Bearer xyz"}`.
|
|
50
50
|
- `agents tools remove <agent_id> <tool_id>` takes the tool's `id` from `config.tools[]`; read it with `laburen agents versions get <agent_id> <version_id>` (or the latest version). Without a TTY it is required; with a TTY a picker lists the tools.
|
|
51
|
+
- `laburen agents widgets create <agent_id> --name <name>` puts the agent on a website: the response has the snippet ready to paste (`web_widget_script`), an `embed_iframe` and a `standalone_url` to try it. It also returns `identity_secret` **once** (same for `agents widgets rotate`): save it for the site's backend, which signs the visitor identity token with it. Details, flags and identifying visitors: [Commands](references/commands.md#widgets).
|
|
51
52
|
- `laburen tokens create` returns the secret once, in `value`. Save it right away. Revoked tokens stay in `tokens list` (there is no `tokens delete`). `tokens update <token_id> --description null` clears the description.
|
|
52
53
|
|
|
53
54
|
### Facts that are easy to get wrong
|
|
@@ -63,7 +64,7 @@ Tool rules the API enforces (the wizard and `--schema` already follow them): eve
|
|
|
63
64
|
|
|
64
65
|
Removing `thinking` first with `agents tools remove` and changing the model after also works, but makes two versions.
|
|
65
66
|
- **`--search <text>`** filters by name (case-insensitive) on `agents list`, `skills list`, `mcp connections list`, `knowledge projects list` and `tokens list`.
|
|
66
|
-
- **Permissions are independent**: `query`, `read`, `write` and `admin` do not include each other. A token with only `admin` cannot read. Deleting agents, skills
|
|
67
|
+
- **Permissions are independent**: `query`, `read`, `write` and `admin` do not include each other. A token with only `admin` cannot read. Deleting agents, skills, MCP connections and widgets needs `admin`; `insufficient_permissions` means the token lacks one.
|
|
67
68
|
- **`resource_in_use`** (deleting a skill or MCP connection that agents still use): `details.agent_versions` lists the blocking agent versions, `[{ agent_id, version_id, is_active }]` (no repeats); `details.agent_ids` lists their agents. Versions are immutable, so they are not edited. Recipe: (1) for an `is_active: true` entry, 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 entry with `is_active: false`, 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. The CLI `next` has one `agents versions delete` per inactive version and an `agents versions get` for the active one (after step 1, delete that one too, then retry).
|
|
68
69
|
- **`mcp_server_unreachable`** (exit 1, API code `400`): the API could not connect to the MCP server when you listed its tools (`details.connection_id` says which connection). Saving an agent `tools` filter with a MCP that is down does not fail: it saves and the response carries a `mcp_tools_unverified` warning. It is not retried automatically: check the URL and headers (`mcp connections versions list <connection_id>` shows the host of each version), then run it again. A run whose agent uses a MCP that is down does not fail with this error.
|
|
69
70
|
- **`issues[].field`** points to the exact place, like `config.tools[3].url`. When the error names a field (`details.field`), `issues[]` has it too.
|
|
@@ -72,20 +73,22 @@ Tool rules the API enforces (the wizard and `--schema` already follow them): eve
|
|
|
72
73
|
- **A run fails with `invalid_request` on `model_settings.reasoning` and a message about the `thinking` tool**: the version has the `thinking` tool and the model reasons. Run again with `--reasoning off` (only if the model can turn it off) or run a version without the tool with `--version-id`.
|
|
73
74
|
- **`model_provider_auth_failed`**: the model provider rejected the platform's credentials, even after the platform tried its fallback models. It is not your request and not retryable; if it persists, contact support.
|
|
74
75
|
- **`internal_invariant_violation`**: a bug on the server (500). Keep the `request_id` and report it; changing the request does not fix it.
|
|
75
|
-
- **`idempotency_key_in_progress`**:
|
|
76
|
+
- **`idempotency_key_in_progress`**: it comes after a slow or failed first attempt that the CLI retried: that first request is still running on the server and may still apply. Do not rerun the command as it is: a rerun sends a new request (a new key) and can duplicate. Wait, then check with `list`/`get` that the first one did not apply (the `next` is that `list` for a create or update; `agents run` has none), and only then run it again.
|
|
76
77
|
|
|
77
78
|
`base_version_id` guards against a concurrent change: if it is not the latest version the API answers `409 base_version_mismatch`; omit it to skip the check. Send `base_version_id: null` to say the resource has no versions yet. `--base-version-id null` sends `null`: on a resource that already has versions it fails with `409 base_version_mismatch` (use it only for the first version).
|
|
78
79
|
|
|
79
|
-
The body of `agents run` (`generate`/`stream`) rejects unknown keys: a typo such as `max_step` is a `400 invalid_request`, with one `issues[]` entry per key, and the turn does not run. A `versions create` that is identical to the latest version still creates the version, and the response carries a `no_changes` warning (`Warning: ...` on stderr): for an agent it is `{ code: "no_changes" }`, for a skill the text `The new version is identical to the latest one.`; check `changed_fields` to see what changed.
|
|
80
|
+
The body of `agents run` (`generate`/`stream`) rejects unknown keys: a typo such as `max_step` is a `400 invalid_request`, with one `issues[]` entry per key, and the turn does not run. A `versions create` that is identical to the latest version still creates the version, and the response carries a `no_changes` warning (`Warning: ...` on stderr): for an agent it is `{ code: "no_changes" }`, for a skill the text `The new version is identical to the latest one.`; check `changed_fields` to see what changed. Every `invalid_skill` has `details.field`, so `issues[]` names the file: its path (`files["notes.txt"]`) for a disallowed path or a NUL character (`forbidden_path`, `invalid_character`), and `files["SKILL.md"]` for the rest (frontmatter, limits, missing `SKILL.md`, a different `name`).
|
|
80
81
|
|
|
81
82
|
### Change an agent: `update` vs `versions create`
|
|
82
83
|
|
|
83
84
|
Both create a new version and neither activates it unless you ask. They differ in what they do with the config:
|
|
84
85
|
|
|
85
|
-
- `agents update <agent_id> --config @patch.json` **edits**: it starts from the latest version and replaces only the config keys you send (`{"prompt":[{"type":"text","content":"New prompt"}]}` changes the prompt and keeps the model, tools and the rest). `--skills` and `--mcp-connections` replace the whole list and also create a version. With only `--name` or `--description` no version is created.
|
|
86
|
+
- `agents update <agent_id> --config @patch.json` **edits**: it starts from the latest version and replaces only the config keys you send (`{"prompt":[{"type":"text","content":"New prompt"}]}` changes the prompt and keeps the model, tools and the rest). Each top-level key is replaced whole, with no deep merge: `{"knowledge":{"project_ids":[]}}` drops `knowledge.mode`. `--skills` and `--mcp-connections` replace the whole list and also create a version. With only `--name` or `--description` no version is created.
|
|
86
87
|
- `agents versions create <agent_id> --config @config.json` **writes the whole version**: a key you omit goes back to its default, and there are no skills or MCP connections unless you send them. Use it with a full config (start from `--skeleton`).
|
|
87
88
|
|
|
88
|
-
|
|
89
|
+
**Warning:** `agents update --config`, `agents tools add` and `agents tools remove` start from the **latest** version, not the active one. If the latest is an inactive draft, the new version keeps the draft's tools and loses what only the active version had: check `agents versions list` first. Deleting the latest version frees its number, and the next version reuses it (the number is the highest that exists plus one).
|
|
90
|
+
|
|
91
|
+
When the new version stays inactive, both print `Created version <n> (not active). Activate it with: laburen agents versions activate <agent_id> <version_id>` on stderr, also with `--json`. Pass `--activate` to activate it right away.
|
|
89
92
|
|
|
90
93
|
```sh
|
|
91
94
|
laburen agents update <agent_id> --config '{"model":{"id":"<model_id>"}}' --change-message "switch model" --activate
|
|
@@ -124,6 +127,16 @@ laburen agents create --name Support --harness-type mastra --config @config.json
|
|
|
124
127
|
|
|
125
128
|
`config.json` only takes the model (`model.id`), `knowledge.project_ids`, the prompt, the tools and the other settings of the version. Skills and MCP connections do not go in it: pass them in the body with `--skills` and `--mcp-connections` (or in `--data`), on `agents create` or `agents versions create`.
|
|
126
129
|
|
|
130
|
+
```json
|
|
131
|
+
{
|
|
132
|
+
"model": { "id": "<model id>" },
|
|
133
|
+
"knowledge": { "mode": "vector", "project_ids": ["<project id>"] },
|
|
134
|
+
"prompt": [{ "type": "text", "content": "You answer questions about shipping and returns." }]
|
|
135
|
+
}
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
`knowledge.mode` is optional and its only value is `"vector"`: omit it or send `"vector"`, never `null` or `""` (the API rejects them). `--skeleton` leaves `knowledge` out because it has no published default; add it by hand.
|
|
139
|
+
|
|
127
140
|
Each item of `--mcp-connections` accepts `"tools": ["<tool name>"]` to limit the agent to those tools of the connection (absent = all of them); discover the names with `laburen mcp connections tools list <connection_id>` (the `name` field). The API validates them when it saves: an unknown name fails with `400 invalid_request` on `mcp_connections[i].tools[j]`. If the response carries a `mcp_tools_unverified` warning, the server could not be reached and the filter was not checked; the CLI prints it to stderr as `Warning: ...`. The interactive wizards ask it per connection, with every tool preselected.
|
|
128
141
|
|
|
129
142
|
`agents tools add` and `agents tools remove` send `base_version_id` and retry once by themselves. If you get `409 base_version_mismatch` from any other command, someone created a version meanwhile: read again and retry.
|
|
@@ -134,7 +147,7 @@ The CLI asks a question only if all of this is true: no `--non-interactive` (an
|
|
|
134
147
|
|
|
135
148
|
Every question has a flag that replaces it, so an agent never needs one:
|
|
136
149
|
|
|
137
|
-
- A missing id (`laburen agents get`): pass the id. Without it the error is `missing_arguments` with `choices`. If
|
|
150
|
+
- A missing id (`laburen agents get`): pass the id. Without it the error is `missing_arguments` with `choices`. If you are not logged in the error is `login_required`; if the API rejects the list (for example, no organization in non-interactive mode), you get that error with its `next` (`--org <id>`); if the API cannot be reached there are no `choices`.
|
|
138
151
|
- A delete, `tokens revoke` or `agents tools remove`: the confirmation is skipped with `--yes` (`-y`). `agents tools remove` reads the agent first (so it never asks about a tool that does not exist): it needs a session, and without one it fails with `login_required` before `confirmation_required`.
|
|
139
152
|
- `agents create`, `tokens create`, `skills create`, `mcp connections create`: each question is a flag (`--name`, `--kind`, `--permissions`, `--dir`, `--url`, `--skills`, `--mcp-connections`, `--activate`). The full table is in [Commands](references/commands.md#questions-in-create).
|
|
140
153
|
- `agents tools add` and `agents tools remove`: whether to activate the new version is `--activate` or `--no-activate` (without either, the version stays inactive and stderr prints the `agents versions activate` command).
|
|
@@ -166,10 +179,10 @@ Read the individual reference documents for details.
|
|
|
166
179
|
|
|
167
180
|
## Run an agent
|
|
168
181
|
|
|
169
|
-
`laburen agents run <agent_id> "<message>"` runs one turn. stdout gets the answer text only; tool calls, sources and the footer go to stderr. Add `--json` to wait for the end and read one JSON object (`text`, `memory.thread`, `cost`, `tool_calls`...) on stdout: use it when you are an AI agent. To continue the conversation, pass `--thread <memory.thread>`. `--instructions`, `--model`, `--reasoning` and `--max-steps` replace the agent's settings for that run and need `write` permission. `laburen agents run --schema` prints the body schema (`<agent_id>` is optional only there). If the turn ends at the step limit without an answer, stderr says `Warning: The run stopped at the step limit (max_steps N) before a final answer.`: raise `--max-steps` or ask for less. After a handoff to a human, the footer says `handed off to a human; the AI is off in this thread`: that thread cannot be continued (`ai_disabled_for_conversation`); start a new one (the `next` is the same command without `--thread`). A `--thread` belongs to one `--resource`: sending another `memory.resource` with an existing thread fails with `thread_resource_mismatch`; reuse the resource the thread started with. A run costs credits, and Ctrl+C does not stop the turn on the server. If stdout is closed (`| head -1`), the turn keeps running and the footer and the `continue:` line still go to stderr.
|
|
182
|
+
`laburen agents run <agent_id> "<message>"` runs one turn. Always pass the message as an argument: without it the CLI reads stdin only if it starts sending within 500 ms (otherwise `missing_required`), and `-` reads stdin until it ends. stdout gets the answer text only; tool calls, sources and the footer go to stderr. Add `--json` to wait for the end and read one JSON object (`text`, `memory.thread`, `cost`, `tool_calls`...) on stdout: use it when you are an AI agent. To continue the conversation, pass `--thread <memory.thread>`. `--instructions`, `--model`, `--reasoning` and `--max-steps` replace the agent's settings for that run and need `write` permission. `laburen agents run --schema` prints the body schema (`<agent_id>` is optional only there). If the turn ends at the step limit without an answer, stderr says `Warning: The run stopped at the step limit (max_steps N) before a final answer.`: raise `--max-steps` or ask for less. Continuing that thread does not bring back the tool results of the cut turn unless the agent keeps tool calls in its history (`config.history.tool_calls.mode`, `off` by default; see [Commands](references/commands.md#run-an-agent)). `contact` in `--data` is not shown to the model. After a handoff to a human, the footer says `handed off to a human; the AI is off in this thread`: that thread cannot be continued (`ai_disabled_for_conversation`); start a new one (the `next` is the same command without `--thread`). A `--thread` belongs to one `--resource`: sending another `memory.resource` with an existing thread fails with `thread_resource_mismatch`; reuse the resource the thread started with. There is no command to list threads or read the messages of a conversation (the history is in the dashboard), and the contacts that `--resource` creates cannot be deleted with the CLI. A run costs credits, and Ctrl+C does not stop the turn on the server. If stdout is closed (`| head -1`), the turn keeps running and the footer and the `continue:` line still go to stderr.
|
|
170
183
|
|
|
171
184
|
### References
|
|
172
185
|
|
|
173
|
-
- [Commands](references/commands.md) - every command with one example, `agents run`, the confirmation before deleting, picking a missing id and the questions of each `create`.
|
|
186
|
+
- [Commands](references/commands.md) - every command with one example, `agents run`, widgets (install code, `identity_secret`, identifying visitors), the confirmation before deleting, picking a missing id and the questions of each `create`.
|
|
174
187
|
- [Auth and organizations](references/auth-and-organizations.md) - login, `LABUREN_TOKEN`, which organization is used, `link.json`, API URL, separate sessions, testing against a local dashboard.
|
|
175
188
|
- [Output and errors](references/output-and-errors.md) - stdout vs stderr, `--json`, `--paginate`, the error JSON with `next`, exit codes, colors.
|
|
@@ -43,7 +43,7 @@ First match wins:
|
|
|
43
43
|
3. `.laburen/link.json`, found in the current folder or any parent
|
|
44
44
|
4. the organization saved with `laburen orgs switch`
|
|
45
45
|
|
|
46
|
-
If `--org` or `LABUREN_ORG` differs from `link.json`, the command fails with `organization_mismatch` (exit 2). For `LABUREN_ORG`, `next` is `unset LABUREN_ORG
|
|
46
|
+
If `--org` or `LABUREN_ORG` differs from `link.json`, the command fails with `organization_mismatch` (exit 2). For `LABUREN_ORG`, `next` is `unset LABUREN_ORG`; for `--org`, the same command without `--org`. In both cases it also offers `laburen orgs list` and `laburen link --org <id>` with a placeholder: the CLI does not check that the id you passed exists, so pick one from `orgs list` before linking (`link` with an id that is not yours fails with `organization_not_found`), and `laburen unlink`. An empty `--org` fails with `invalid_flag_value` (exit 2).
|
|
47
47
|
|
|
48
48
|
In non-interactive mode (and in any script or CI), set the organization with `--org <id>` or `LABUREN_ORG=<id>`: `laburen orgs switch <id>` saves it but the saved one is ignored there.
|
|
49
49
|
|
|
@@ -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
|
|
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
|
|
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
|
-
|
|
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>
|
|
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]
|
|
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
|
-
|
|
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
|
+
```
|
|
138
155
|
|
|
139
|
-
|
|
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).
|
|
168
|
+
|
|
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>
|
|
@@ -186,6 +216,46 @@ laburen mcp connections versions compare <connection_id> --from <version_id> --t
|
|
|
186
216
|
|
|
187
217
|
Headers of an MCP connection are an object, name to value: `--headers '{"Authorization":"Bearer x"}'` or `@headers.json` (not the list of `{ key, value }` of the http tool). `mcp connections versions create` without `--headers` keeps the headers of the latest version; `--headers '{}'` removes them. If the server cannot be reached, listing its tools fails with `mcp_server_unreachable` (400); check the URL and headers. Saving an `--mcp-connections` item with `tools` does not fail: it saves and warns with `mcp_tools_unverified`.
|
|
188
218
|
|
|
219
|
+
## Widgets
|
|
220
|
+
|
|
221
|
+
A widget puts an agent on a website as a chat. It belongs to an agent (an agent can have several, for example one per site) and the visitor talks to the agent's **active version**.
|
|
222
|
+
|
|
223
|
+
```sh
|
|
224
|
+
laburen agents widgets create <agent_id> --name "Acme site" --allowed-domains '["acme.com","*.acme.com"]'
|
|
225
|
+
laburen agents widgets list <agent_id> # table: ID, NAME, ENABLED, DOMAINS, ANONYMOUS, UPDATED; newest first
|
|
226
|
+
laburen agents widgets get <agent_id> <widget_id>
|
|
227
|
+
laburen agents widgets update <agent_id> <widget_id> --no-enabled # turn it off; --enabled turns it on
|
|
228
|
+
laburen agents widgets rotate <agent_id> <widget_id> # new identity_secret; the old one stops working
|
|
229
|
+
laburen agents widgets delete <agent_id> <widget_id> # needs admin; the snippet stops working, conversations stay
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
Every response carries the code to install it, with the public token and the URL already set: `web_widget_script` (the `<script>` of the chat bubble: paste it in the site's `<head>` or before `</body>`), `embed_iframe` (an `<iframe>` that shows the chat inside a page, 400×600 by default: change `width`/`height`) and `standalone_url` (a chat page of its own; open it to try the widget). Without `--json` the snippet is printed with its line breaks escaped (`\n`), so do not copy it from there: read it with `--json`, for example `laburen agents widgets get <agent_id> <widget_id> --json | jq -r .web_widget_script`. `token` is public (it goes in the snippet).
|
|
233
|
+
|
|
234
|
+
`create` and `rotate` also return `identity_secret`, **only in that response**: without `--json`, stderr says "Save the `identity_secret` now: it will not be shown again." It is what your site's backend uses to sign the visitor's identity token (below); it never goes in the browser. `create` and `rotate` are sent once, never retried (they are not idempotent); `rotate` does not ask for confirmation.
|
|
235
|
+
|
|
236
|
+
Flags of `create` and `update` (`update` changes only what you pass; `--data` takes the whole body):
|
|
237
|
+
|
|
238
|
+
| Flag | Default | What it does |
|
|
239
|
+
|---|---|---|
|
|
240
|
+
| `--name` | (required in `create`) | Name of the widget, 1 to 100 characters |
|
|
241
|
+
| `--enabled` / `--no-enabled` | on | `--no-enabled` turns it off: the chat answers `widget_not_found`, as if it did not exist |
|
|
242
|
+
| `--allowed-domains` | `[]` | JSON list of sites that can embed it (up to 50); empty = any site. Full host (`www.acme.com` does not include `acme.com`), wildcard only at the start (`*.acme.com` covers subdomains, not `acme.com`), optional port (1 to 65535). A wildcard cannot cover a whole public suffix (`*.com`, `*.com.ar`, `*.co.uk`, `*.github.io`: the list is the Public Suffix List) or an IP. Stored in lowercase, without scheme, path or repeats. `localhost` and its subdomains are rejected: use `127.0.0.1`. An invalid one fails with `invalid_request` on `allowed_domains[i]` |
|
|
243
|
+
| `--allows-anonymous` / `--no-allows-anonymous` | on | `--no-allows-anonymous`: a visitor your site did not identify cannot chat (`identity_required`) |
|
|
244
|
+
| `--max-attachments-per-message` | `5` | Files per visitor message, 1 to 10 |
|
|
245
|
+
| `--visitor-rate-limit` | `null` | JSON `{"max_messages":20,"interval_seconds":60}` (up to 100000 messages and 30 days): cap per visitor; `null` removes it |
|
|
246
|
+
| `--limit-reached-message` | `null` | Text the visitor sees at the cap (1 to 500 characters); `--limit-reached-message null` goes back to the default text |
|
|
247
|
+
| `--appearance` | `{}` | JSON with `widget_color` (`#rrggbb`), `welcome_title` (up to 100), `welcome_tagline` (up to 200), `position` (`left`/`right`), `theme` (`light`/`dark`/`auto`), `launcher_icon_url` (https). `update --appearance` replaces the whole object: send every field you want to keep |
|
|
248
|
+
|
|
249
|
+
`allowed_domains` limits who can **embed** the chat (a `Content-Security-Policy: frame-ancestors` header), not who calls the API. Each domain is allowed over `https://`, except `127.0.0.1` and `0.0.0.0`, which use `http://`: a page served over `http` on a public domain (a staging without a certificate) cannot embed the chat.
|
|
250
|
+
|
|
251
|
+
When changes show: the chat reads the widget on every message, so `--no-enabled` or `delete` stops it right away (`widget_not_found`). The widget **page** (`standalone_url` and the iframe's page) keeps the domains for up to 60 seconds, so a new `--allowed-domains`, turning the widget off or deleting it can take up to a minute to show there.
|
|
252
|
+
|
|
253
|
+
The widget answers with the agent's active version. If the agent has none, the widget is created anyway, but every visitor message fails with `invalid_agent_config` ("has no active version") until you activate one (`laburen agents versions activate`).
|
|
254
|
+
|
|
255
|
+
**Identify visitors (optional).** Without it every browser is an anonymous visitor. If the site has its own login, its backend signs an identity token with the `identity_secret` for the logged-in user (for example from an endpoint the page calls with `fetch`), and the page passes it to the widget with `window.$laburen.identify({ token })` (it can run right after the snippet: the snippet queues the call until the widget script loads); the visitor is then linked to a contact of the organization (found or created by `user_id`). The token is a JWT HS256: the key is the UTF-8 bytes of `identity_secret`; `user_id` (non-empty string) and `exp` are required; `email`, `name`, `phone` and `custom_attributes` (an object of strings) are optional. In a Worker or Node backend, `signIdentityToken({ secret, userId, expiresIn? })` from `@laburen/delta-sdk/platform` builds it (see `docs/platform/guide.md` of `@laburen/delta-sdk`, section 14). A bad, expired or incomplete token makes the chat fail with `invalid_identity_token`. The CLI has no command to sign one: signing happens in the site's backend. Other snippet calls: `$laburen.reset()` (on logout), `$laburen.toggle(open?)` and `$laburen.setAttributes(text)` (up to 1000 characters of unverified context sent with the visitor's messages).
|
|
256
|
+
|
|
257
|
+
The CLI and the API do not read or answer the widget's conversations (that is in the dashboard), and the API the chat itself uses in the browser is internal.
|
|
258
|
+
|
|
189
259
|
## Tokens
|
|
190
260
|
|
|
191
261
|
```sh
|
|
@@ -196,7 +266,7 @@ laburen tokens update <token_id> --description null # clears the description
|
|
|
196
266
|
laburen tokens revoke <token_id>
|
|
197
267
|
```
|
|
198
268
|
|
|
199
|
-
`tokens create` prints the token `value` once. Without `--json` it also warns on stderr that the value will not be shown again.
|
|
269
|
+
`tokens create` prints the token `value` once. Without `--json` it also warns on stderr that the value will not be shown again (`agents widgets create` and `rotate` do the same for `identity_secret`).
|
|
200
270
|
|
|
201
271
|
## Account and organization
|
|
202
272
|
|
|
@@ -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
|
|
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
|
|
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.
|
|
3
|
+
"version": "0.2.0-canary.12",
|
|
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.
|
|
30
|
+
"@laburen/delta-sdk": "1.5.0-canary.12",
|
|
31
31
|
"@vercel/detect-agent": "1.2.7",
|
|
32
32
|
"commander": "14.0.3",
|
|
33
33
|
"picocolors": "1.1.1"
|
|
@@ -1,4 +0,0 @@
|
|
|
1
|
-
import type { Command } from "commander";
|
|
2
|
-
import type { CliContext } from "../context.js";
|
|
3
|
-
/** Después de `tokens create` (sin --json) avisa en stderr que el `value` no se vuelve a mostrar. */
|
|
4
|
-
export declare function registerTokenNotice(program: Command, _ctx: CliContext): void;
|
|
@@ -1,13 +0,0 @@
|
|
|
1
|
-
import { extendOperation } from "../operations.js";
|
|
2
|
-
import { notice } from "../output.js";
|
|
3
|
-
/** Después de `tokens create` (sin --json) avisa en stderr que el `value` no se vuelve a mostrar. */
|
|
4
|
-
export function registerTokenNotice(program, _ctx) {
|
|
5
|
-
extendOperation(program, ["tokens", "create"], {
|
|
6
|
-
afterResult: (ctx, mode) => {
|
|
7
|
-
if (mode.json)
|
|
8
|
-
return;
|
|
9
|
-
notice(ctx, mode, "Save the token `value` now: it will not be shown again.");
|
|
10
|
-
},
|
|
11
|
-
});
|
|
12
|
-
}
|
|
13
|
-
//# sourceMappingURL=token-notice.js.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"token-notice.js","sourceRoot":"","sources":["../../src/commands/token-notice.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC,qGAAqG;AACrG,MAAM,UAAU,mBAAmB,CAAC,OAAgB,EAAE,IAAgB;IACrE,eAAe,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE;QAC9C,WAAW,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;YAC1B,IAAI,IAAI,CAAC,IAAI;gBAAE,OAAO;YACtB,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,yDAAyD,CAAC,CAAC;QAC9E,CAAC;KACD,CAAC,CAAC;AACJ,CAAC"}
|