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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/dist/bin.js +2 -6
  2. package/dist/bin.js.map +1 -1
  3. package/dist/commands/agent-checks.d.ts +1 -3
  4. package/dist/commands/agent-checks.js +2 -35
  5. package/dist/commands/agent-checks.js.map +1 -1
  6. package/dist/commands/agent-run/render.d.ts +5 -15
  7. package/dist/commands/agent-run/render.js +15 -25
  8. package/dist/commands/agent-run/render.js.map +1 -1
  9. package/dist/commands/agent-run.js +17 -55
  10. package/dist/commands/agent-run.js.map +1 -1
  11. package/dist/commands/agent-tools/add.js +5 -26
  12. package/dist/commands/agent-tools/add.js.map +1 -1
  13. package/dist/commands/agent-tools/remove.js +2 -2
  14. package/dist/commands/agent-tools/remove.js.map +1 -1
  15. package/dist/commands/agent-tools/shared.d.ts +9 -16
  16. package/dist/commands/agent-tools/shared.js +12 -25
  17. package/dist/commands/agent-tools/shared.js.map +1 -1
  18. package/dist/commands/auth.js +2 -12
  19. package/dist/commands/auth.js.map +1 -1
  20. package/dist/commands/completion.js +4 -4
  21. package/dist/commands/completion.js.map +1 -1
  22. package/dist/commands/orgs.js +2 -16
  23. package/dist/commands/orgs.js.map +1 -1
  24. package/dist/commands/skill-dir.js +0 -4
  25. package/dist/commands/skill-dir.js.map +1 -1
  26. package/dist/commands/whoami.js +1 -1
  27. package/dist/commands/whoami.js.map +1 -1
  28. package/dist/completion/files.d.ts +0 -2
  29. package/dist/completion/files.js +0 -7
  30. package/dist/completion/files.js.map +1 -1
  31. package/dist/config/link.js +8 -27
  32. package/dist/config/link.js.map +1 -1
  33. package/dist/context.d.ts +0 -2
  34. package/dist/context.js +0 -1
  35. package/dist/context.js.map +1 -1
  36. package/dist/errors.js +20 -249
  37. package/dist/errors.js.map +1 -1
  38. package/dist/generated/commands.d.ts +0 -2
  39. package/dist/generated/commands.js +7 -7
  40. package/dist/generated/commands.js.map +1 -1
  41. package/dist/generated/schemas.js +9 -11
  42. package/dist/generated/schemas.js.map +1 -1
  43. package/dist/invocation.js +1 -17
  44. package/dist/invocation.js.map +1 -1
  45. package/dist/operations/call.js +1 -4
  46. package/dist/operations/call.js.map +1 -1
  47. package/dist/operations/extensions.d.ts +1 -1
  48. package/dist/operations/params.js +2 -13
  49. package/dist/operations/params.js.map +1 -1
  50. package/dist/operations/run-operation.js +7 -9
  51. package/dist/operations/run-operation.js.map +1 -1
  52. package/dist/operations/schema-flag.d.ts +1 -1
  53. package/dist/operations/schema-flag.js.map +1 -1
  54. package/dist/operations/tables.d.ts +1 -5
  55. package/dist/operations/tables.js +2 -81
  56. package/dist/operations/tables.js.map +1 -1
  57. package/dist/output.d.ts +1 -12
  58. package/dist/output.js +10 -162
  59. package/dist/output.js.map +1 -1
  60. package/dist/program.js +3 -12
  61. package/dist/program.js.map +1 -1
  62. package/docs/SKILL.md +7 -74
  63. package/docs/references/auth-and-organizations.md +3 -3
  64. package/docs/references/commands.md +17 -48
  65. package/docs/references/output-and-errors.md +9 -27
  66. package/package.json +2 -2
  67. package/dist/stdout-policy.d.ts +0 -4
  68. package/dist/stdout-policy.js +0 -11
  69. package/dist/stdout-policy.js.map +0 -1
package/docs/SKILL.md CHANGED
@@ -5,11 +5,6 @@ metadata:
5
5
  package: "@laburen/delta-cli"
6
6
  ---
7
7
 
8
- ## Read this first
9
-
10
- - There is no `stream` command: `laburen agents run` already streams the turn, and `--json` waits for the full answer and prints it as one JSON object.
11
- - Knowledge projects are created and loaded in the dashboard, not with the CLI (it only lists them: `laburen knowledge projects list`).
12
-
13
8
  ## When to use
14
9
 
15
10
  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.
@@ -27,16 +22,14 @@ laburen agents list
27
22
  - Run `laburen login` once. It prints a URL and a code; the person approves it in the browser. In CI or a server, set `LABUREN_TOKEN` instead.
28
23
  - Every command accepts `--json`, `--org`, `--api-url`, `--global-config`, `--non-interactive`, `--no-non-interactive` and `--no-color`.
29
24
  - Without a terminal the saved organization (`orgs switch`) is ignored: pass `--org <id>` or set `LABUREN_ORG=<id>` (or use `laburen link --org <id>` in the folder). A token that belongs to one organization needs none.
30
- - Run `laburen <command> --help` for the flags of any command; every subcommand help also lists the global options. `--org ""` fails with `invalid_flag_value`.
31
- - Tab completion for zsh, bash and PowerShell (on Windows, run it from PowerShell, or from Git Bash/WSL for bash): run `laburen completion --install` once and open a new terminal. It refreshes itself after the CLI is updated. `laburen completion zsh|bash|powershell` prints the script instead; `laburen completion` with no shell takes it from `$SHELL`.
25
+ - Run `laburen <command> --help` for the flags of any command.
26
+ - Tab completion for zsh, bash and PowerShell (on Windows, run it from PowerShell, or from Git Bash/WSL for bash): run `laburen completion --install` once and open a new terminal. It refreshes itself after the CLI is updated. `laburen completion zsh|bash|powershell` prints the script instead.
32
27
  - If you are an AI agent with no terminal, the CLI is non-interactive: it never asks questions, and errors come as JSON on stdout with a `next` list of commands that fix them (and `issues` with the invalid fields, when the API sends them). Run the command in `next`: it is the command you ran with what was missing added.
33
28
  - Exit codes: `0` ok, `1` API or network error, `2` wrong usage.
34
29
 
35
30
  ## Discover, then build
36
31
 
37
- - Without `--json`, list tables show a few columns and cut long text to the width of a terminal (the ID column is never cut; piped output is not cut). `get` (or `--json`) shows every field: use it when you need a value that a table hides.
38
- - `laburen whoami` shows who you are, the organization and the credential (`laburen me get` is the same call, raw). With an organization token the user line reads `none (organization credential)`.
39
- - Several organizations and no human to ask: pass `--org <id>` explicitly (the ids are in `laburen orgs list`). If you do not know which one is meant, stop and report it; do not pick one.
32
+ - `laburen whoami` shows who you are, the organization and the credential.
40
33
  - `--schema` on any command with a body prints the command, its positionals and the JSON Schemas of the body and the response. It needs no login and calls no API.
41
34
  - `--skeleton` (on `agents create` and `agents versions create`) prints a config JSON with the required fields, the fields that have a published default, an empty `prompt` block (`[{"type":"text","content":""}]`), `"tools": []` and a `"$schema"` pointing to `<api-url>/schemas/agent-config.json` (nothing else is invented: no `reasoning_effort`). The available tool types go to stderr (`tool types: ... → see --schema`); stdout stays pure JSON. Edit it and send it with `--config @config.json`: the `$schema` is sent as is and the API ignores it.
42
35
  - A selector (an agent, a skill, a connection by name) searches by name when the list has more than one page.
@@ -45,71 +38,11 @@ laburen agents list
45
38
  Tool rules the API enforces (the wizard and `--schema` already follow them): every tool type except `http` can appear only once in `config.tools` (the schema marks them with `x-single: true`); `reasoning_effort` must be one of the model's levels (`laburen models list` shows them in REASONING) and a model without reasoning takes none; a `thinking` tool is only for models that do not reason, or with `reasoning_effort: "off"`. `laburen agents tools add --schema` prints the schema of a tool, with no login.
46
39
 
47
40
  - `laburen models list` shows each model's default effort in REASONING, for example `low,medium,high (default: medium)`; it is used when `reasoning_effort` is omitted. A model that reasons and has no `off` level can never use a `thinking` tool.
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
- - 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"}`.
41
+ - Items of the http tool's `headers`, `body`, `query_parameters` and `path_variables` are `{ "key", "value", "description"? }`, for example `{"key":"Authorization","value":"Bearer xyz"}`.
50
42
  - `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 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
- ### Facts that are easy to get wrong
54
-
55
- - **MCP headers are an object**: `--headers '{"Authorization":"Bearer x"}'` (name to value). The http tool's headers are a different shape, a list of `{ "key", "value" }`. `mcp connections versions create` without `--headers` keeps the headers of the latest version; `--headers '{}'` removes them. Without `--url` it keeps the url of the latest version too (the url is always `[REDACTED]`, so this is how you change only the headers); a connection with no version yet fails with `invalid_request` on `url`.
56
- - **Reasoning**: in a version it lives at `config.model.reasoning_effort` (for example `{"model":{"id":"<model_id>","reasoning_effort":"high"}}`). Per run it is `--reasoning <level>` (`model_settings.reasoning`).
57
- - **`agents get` has no config.** Read it with `laburen agents versions get <agent_id> <active_version_id>` (the active version id is in `agents get`).
58
- - **Switching to a model that always reasons** (no `off` level) fails if the version has the `thinking` tool. Do it in ONE new version: read the current tools with `laburen agents versions get <agent_id> <version_id>`, then send the model and the whole `tools` list without `thinking` (`tools` replaces the list, so every tool you keep must be in it):
59
-
60
- ```sh
61
- laburen agents update <agent_id> --config '{"model":{"id":"<reasoning model>"},"tools":[<all current tools except thinking>]}' --activate
62
- ```
63
-
64
- Removing `thinking` first with `agents tools remove` and changing the model after also works, but makes two versions.
65
- - **`--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 and MCP connections needs `admin`; `insufficient_permissions` means the token lacks one.
67
- - **`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
- - **`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
- - **`issues[].field`** points to the exact place, like `config.tools[3].url`. When the error names a field (`details.field`), `issues[]` has it too.
70
- - **`tools: []` on an assigned MCP connection means all of its tools** (the same as leaving `tools` out). To limit the agent, list the tool names.
71
- - **The MCP `url` is always `[REDACTED]`** (it can carry secrets), in every response. `url_host` shows the host so you can recognize the server. Header values are `[REDACTED]` too.
72
- - **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
- - **`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
- - **`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`**: the first request with that `Idempotency-Key` is still running. 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
- `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
- 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. An `invalid_skill` caused by a disallowed path or a NUL character in a file (`forbidden_path`, `invalid_character`) has `details.field` with its path (`files["notes.txt"]`), so `issues[]` names it; other file errors do not.
80
-
81
- ### Change an agent: `update` vs `versions create`
82
-
83
- Both create a new version and neither activates it unless you ask. They differ in what they do with the config:
84
-
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 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`).
43
+ - `laburen tokens create` returns the secret once, in `value`. Save it right away.
87
44
 
88
- 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. Pass `--activate` to activate it right away.
89
-
90
- ```sh
91
- laburen agents update <agent_id> --config '{"model":{"id":"<model_id>"}}' --change-message "switch model" --activate
92
- laburen agents versions create <agent_id> --config @config.json --change-message "full rewrite"
93
- ```
94
-
95
- ### Defaults
96
-
97
- - `skills create`, `mcp connections create` and `agents create --config` activate their first version unless you pass `--no-activate`. Every `versions create` leaves the new version inactive, and so does `agents update` unless you pass `--activate`; `versions restore` activates the copy unless `--no-activate`.
98
- - A skill or MCP connection assigned to an agent uses `strategy: "pin"` by default: the agent keeps the version that was active when you assigned it. `"latest"` follows the active version. Set it per item: `--skills '[{"skill_id":"<id>","strategy":"latest"}]'`.
99
- - Renaming an MCP connection (`mcp connections update --name`) changes the names of its tools for the agents (the connection name is their prefix): review prompts that mention them.
100
- - Knowledge projects and Composio apps are created and loaded in the dashboard. The CLI only lists the projects (`laburen knowledge projects list`); put their ids in `config.knowledge.project_ids`.
101
-
102
- ### Skill format
103
-
104
- `skills create` has no `--description`: the description comes from the `description` in the frontmatter of `SKILL.md`. `--dir` (or `--files`) accepts only `SKILL.md` and files under `references/`; any other path fails with `invalid_skill`. `SKILL.md` starts with a frontmatter with `name` (it must equal the skill's name) and `description`:
105
-
106
- ```md
107
- ---
108
- name: faq
109
- description: Answers questions about shipping and returns. Use when the user asks about an order.
110
- ---
111
- Steps and rules for the agent...
112
- ```
45
+ `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. There is no flag for `null`: use `--data`, for example `--data '{"config":{...},"base_version_id":null}'`.
113
46
 
114
47
  Order of steps: first create what the agent will use and look up ids, then build the agent.
115
48
 
@@ -166,7 +99,7 @@ Read the individual reference documents for details.
166
99
 
167
100
  ## Run an agent
168
101
 
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.
102
+ `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. A run costs credits, and Ctrl+C does not stop the turn on the server.
170
103
 
171
104
  ### References
172
105
 
@@ -8,7 +8,7 @@ laburen login
8
8
 
9
9
  Prints a URL and a confirmation code on stderr, tries to open the browser (it does not when `CI` is set), and waits for the person to approve. If you are an AI agent in non-interactive mode, it always adds "Please ask the user to visit the URL above and approve the login." (opening the browser does not prove anyone can see it). Show the URL to the user. Ctrl-C cancels (exit 1).
10
10
 
11
- If the server takes more than 1 second to answer the first request, stderr says `Waiting for the server…` before the URL appears. On success it saves `auth.json` and prints "You are now signed in." Network errors while waiting do not cancel the login.
11
+ On success it saves `auth.json` and prints "You are now signed in." Network errors while waiting do not cancel the login.
12
12
 
13
13
  `laburen logout` revokes the saved tokens (both at once, waiting at most 5 seconds) and deletes `auth.json`. If the server does not answer, it still deletes the file.
14
14
 
@@ -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` or `laburen link --org <that id>`; for `--org`, the same command without `--org` or `laburen link --org <that id>`. An empty `--org` fails with `invalid_flag_value` (exit 2).
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` or `laburen link --org <that id>`; for `--org`, the same command without `--org` or `laburen link --org <that id>`. An empty `--org` fails with 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
 
@@ -55,7 +55,7 @@ In non-interactive mode, the saved organization (4) is ignored. If 1 to 3 give n
55
55
 
56
56
  ## `link.json`
57
57
 
58
- `laburen link --org <id>` writes `.laburen/link.json` with `{ "organization_id": "..." }`. It checks you are a member first (`organization_not_found` otherwise). Without `--org` it uses the organization already resolved by the rules above (a healthy `link.json` in the folder wins over the saved organization; a broken one fails with `invalid_link`). With `--org` the existing file is replaced without being read; if the `link.json` the CLI would use is broken and lives in a parent folder, that one is rewritten (not a new one in the current folder), and stderr prints its path. The file holds only the id, so commit it: whoever clones the repo works against that organization. `laburen unlink` deletes the `link.json` the CLI would use (the one in the current folder or the nearest parent), and the `.laburen` folder if it is left empty, and prints its path; with none it prints "No linked folder found." and exits 0. A `link.json` that exists but is not valid fails with `invalid_link` (exit 2) instead of being skipped; `laburen link --org <id>` rewrites it and `laburen unlink` removes it. If `.laburen` is a file, `laburen link` and `laburen unlink` fail with `invalid_link` (exit 2) and `next` says which file to remove; the CLI does not look for the `link.json` of a parent folder in that case, and the other commands fail the same way.
58
+ `laburen link --org <id>` writes `.laburen/link.json` with `{ "organization_id": "..." }`. It checks you are a member first (`organization_not_found` otherwise). Without `--org` it uses the organization already resolved by the rules above (a healthy `link.json` in the folder wins over the saved organization; a broken one fails with `invalid_link`). With `--org` the existing file is replaced without being read; if the `link.json` the CLI would use is broken and lives in a parent folder, that one is rewritten (not a new one in the current folder), and stderr prints its path. The file holds only the id, so commit it: whoever clones the repo works against that organization. `laburen unlink` deletes the `link.json` the CLI would use (the one in the current folder or the nearest parent), and the `.laburen` folder if it is left empty, and prints its path; with none it prints "No linked folder found." and exits 0. A `link.json` that exists but is not valid fails with `invalid_link` (exit 2) instead of being skipped; `laburen link --org <id>` rewrites it and `laburen unlink` removes it. If `.laburen` is a file, `laburen link` fails with `invalid_link` (exit 2) and `next` says which file to remove.
59
59
 
60
60
  ## Test against a local dashboard
61
61
 
@@ -1,6 +1,6 @@
1
1
  # Commands
2
2
 
3
- Every command accepts the global flags `--json`, `--org <id>`, `--api-url <url>`, `--global-config <dir>`, `--non-interactive`, `--no-non-interactive` and `--no-color`; each subcommand's `--help` lists them under "Global Options". `--org ""` fails with `invalid_flag_value`. Commands that create or edit also accept `--data <json|@file|->` with the whole body; individual flags override `--data`. JSON flags take a JSON string or `@file`.
3
+ Every command accepts the global flags `--json`, `--org <id>`, `--api-url <url>`, `--global-config <dir>`, `--non-interactive`, `--no-non-interactive` and `--no-color`. Commands that create or edit also accept `--data <json|@file|->` with the whole body; individual flags override `--data`. JSON flags take a JSON string or `@file`.
4
4
 
5
5
  ## Confirmation before deleting
6
6
 
@@ -15,7 +15,7 @@ The ids in the commands below are optional, also in `agents tools add` and `agen
15
15
  - Revoked and expired tokens are left out of the list (and of `choices`). The token of your own CLI session is not marked: the API does not say which one it is. Two items with the same name show the id in the label too (`ci (tok_1)`).
16
16
  - In a delete, the active version is still marked `(current)` but the first one that is not active is preselected (the active one cannot be deleted).
17
17
  - One item: it is picked for you and stderr says which one. Delete, revoke and remove still ask, even with one item.
18
- - No items: fails with `no_results` (exit 1) and `next` is the command that creates one, with its required flags as `<value>` (`laburen agents versions create <agent_id> --config <value>`).
18
+ - No items: fails with `no_results` (exit 1) and `next` is the command that creates one, with its required flags as `<value>` (`laburen mcp connections versions create <connection_id> --url <value>`).
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
 
@@ -47,30 +47,23 @@ If the CLI can ask (same rules as above), these `create` commands ask only for w
47
47
  - An optional text left blank in the config questions is not sent.
48
48
  - Headers of an http tool are not asked because they are secrets; stderr says to set them with `laburen agents tools add --tool @tool.json`.
49
49
  - Picked skills and connections are sent as `{ "skill_id": ... }` and `{ "connection_id": ... }`. Picking none sends nothing.
50
- - `mcp connections create` never asks for headers because they are secrets. Pass them with `--headers @headers.json`; in an interactive session stderr reminds you when they are missing (the reminder does not show in non-interactive mode or with `--json`).
50
+ - `mcp connections create` never asks for headers because they are secrets. Pass them with `--headers @headers.json`; stderr reminds you when they are missing.
51
51
 
52
52
  Ids and values below are placeholders. Run `laburen <command> --help` for the exact flags: it marks the required ones with `(required)` and lists the accepted values (`one of: ...`) when the contract defines them. A required field with only one accepted value shows `(default: <value>)` (for example `--harness-type`, `(default: mastra)`) and is filled in for you. A value outside the accepted list (by flag or in `--data`) fails with `invalid_flag_value` (exit 2) before calling the API, and the message lists the accepted values. `--data -` reads the body from stdin; if stdin is a terminal it says so on stderr (end the input with Ctrl-D).
53
53
 
54
54
  ## Agents
55
55
 
56
56
  ```sh
57
- laburen agents list # --limit, --after-id, --before-id, --paginate, --search <name>
57
+ laburen agents list # --limit, --after-id, --before-id, --paginate
58
58
  laburen agents get <agent_id>
59
59
  laburen agents create --name Support --harness-type mastra
60
60
  laburen agents create --data @agent.json # name, harness_type, config...
61
61
  laburen agents update <agent_id> --name "Support v2"
62
62
  laburen agents update <agent_id> --config @config.json --change-message "new prompt"
63
- laburen agents delete <agent_id> # needs the admin permission
63
+ laburen agents delete <agent_id>
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: ...`.
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).
69
-
70
- ```sh
71
- laburen agents update <agent_id> --config '{"prompt":[{"type":"text","content":"Be brief."}]}' --change-message "shorter answers" # the rest of the config stays
72
- laburen agents versions create <agent_id> --config @full-config.json --skills '[{"skill_id":"<skill_id>"}]' # everything the version has comes from here
73
- ```
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`.
74
67
 
75
68
  Versions:
76
69
 
@@ -79,29 +72,22 @@ laburen agents versions list <agent_id>
79
72
  laburen agents versions get <agent_id> <version_id>
80
73
  laburen agents versions create <agent_id> --config @config.json --change-message "new prompt"
81
74
  laburen agents versions activate <agent_id> <version_id>
82
- laburen agents versions restore <agent_id> <version_id> # with --no-activate: prints "Created version N (not active)..."
75
+ laburen agents versions restore <agent_id> <version_id>
83
76
  laburen agents versions delete <agent_id> <version_id>
84
77
  laburen agents versions compare <agent_id> --from <version_id> --to <version_id>
85
78
  ```
86
79
 
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]`).
88
-
89
- `--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
-
91
- `agents get` does not include the config. To read the model, prompt and tools: `laburen agents versions get <agent_id> <active_version_id>` (the active version id is in `agents get`). In a version, reasoning is `config.model.reasoning_effort`; for one run use `agents run --reasoning <level>`. Moving to a model that always reasons (no `off` level) fails if the config has the `thinking` tool. Fix it in one version: read the tools with `agents versions get`, then `laburen agents update <agent_id> --config '{"model":{"id":"<reasoning model>"},"tools":[<all current tools except thinking>]}' --activate` (`tools` replaces the whole list).
92
-
93
80
  Tools (reads the latest version, changes `config.tools`, and creates a new version; the new version is not active unless you pass `--activate`):
94
81
 
95
82
  ```sh
96
83
  laburen agents tools add <agent_id> --tool '{"type":"send_files"}'
97
84
  laburen agents tools add <agent_id> --tool @tool.json
98
85
  laburen agents tools remove <agent_id> <tool_id>
99
- laburen agents tools add <agent_id> --tool @tool.json --activate --change-message "add send_files"
100
- laburen agents tools remove <agent_id> <tool_id> --change-message "drop thinking" --no-activate
86
+ laburen agents tools add <agent_id> --tool @tool.json --activate
101
87
  laburen agents tools add --schema # JSON Schema of a tool and of the response; no login, no API call
102
88
  ```
103
89
 
104
- `tools add` and `tools remove` take `--change-message <text>` (stored with the new version). On an agent with no versions `tools add` fails with `agent_has_no_version` (exit 1): there is no config to add the tool to, so create the first version with a config (`next` is `laburen agents versions create <agent_id> --config @config.json`, as you can type it) and then add the tool. `--tool` is required: without it `tools add` fails with `missing_required` and `next` is your command plus `--tool <value>`. `laburen agents tools add --help` shows the tool types and an example `http` tool with `headers`, `body` and `query_parameters` (lists of `{ key, value?, description?, is_user_provided?, required?, accepted_values?, type? }`). `--activate` activates the new version (it sends `activate: true`); without it the version stays inactive and stderr says `Created version <n> (not active). Activate it with: laburen agents versions activate <agent_id> <version_id>`. If the CLI can ask and you passed neither `--activate` nor `--no-activate`, it asks "Activate the new version?" (default No), after the delete confirmation in `tools remove`; `--yes` does not answer it. Without `<agent_id>` both commands pick the agent from `agents list` (see "Picking a missing id"). Without `<tool_id>`, `tools remove` picks from the tools of the latest version (name, or type if it has none, with the id next to it); if it has none it fails with `no_results` and `next` is `tools add`. When the CLI cannot ask, the missing tool fails with `missing_arguments` and `choices` like any other id. A tool or agent picked from a list is always confirmed, even with `--yes`. `tools remove` matches the tool by its `id`. If no tool has it, it fails with `tool_not_found` (exit 1, like any resource that does not exist). Redacted header values (`[REDACTED]`) are sent back as they came; the server keeps the stored secret.
90
+ `--tool` is required: without it `tools add` fails with `missing_required` and `next` is your command plus `--tool <value>`. `laburen agents tools add --help` shows the tool types and an example `http` tool with `headers`, `body` and `query_parameters` (lists of `{ key, value?, is_user_provided?, description?, required? }`). `--activate` activates the new version (it sends `activate: true`); without it the version stays inactive and stderr says `Created version <n> (not active). Activate it with: laburen agents versions activate <agent_id> <version_id>`. If the CLI can ask and you passed neither `--activate` nor `--no-activate`, it asks "Activate the new version?" (default No), after the delete confirmation in `tools remove`; `--yes` does not answer it. Without `<agent_id>` both commands pick the agent from `agents list` (see "Picking a missing id"). Without `<tool_id>`, `tools remove` picks from the tools of the latest version (name, or type if it has none, with the id next to it); if it has none it fails with `no_results` and `next` is `tools add`. When the CLI cannot ask, the missing tool fails with `missing_arguments` and `choices` like any other id. A tool or agent picked from a list is always confirmed, even with `--yes`. `tools remove` matches the tool by its `id`. If no tool has it, it fails with `tool_not_found` (exit 1, like any resource that does not exist). Redacted header values (`[REDACTED]`) are sent back as they came; the server keeps the stored secret.
105
91
 
106
92
  ## Run an agent
107
93
 
@@ -114,9 +100,7 @@ laburen agents run <agent_id> --version-id <version_id> --context "The user is a
114
100
  laburen agents run <agent_id> "Hi" --json # waits for the end and prints the final JSON
115
101
  ```
116
102
 
117
- 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
-
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.
103
+ 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, a line says so.
120
104
 
121
105
  | Flag | Body field | Note |
122
106
  |---|---|---|
@@ -128,7 +112,7 @@ Runs one turn and shows it live. stdout gets only the text of the answer; reason
128
112
  | `--model <id>` | `model` | Same permission |
129
113
  | `--reasoning <level>` | `model_settings.reasoning` | `off`, `low`, `medium`, `high` or `max`; same permission |
130
114
  | `--max-steps <n>` | `max_steps` | Same permission |
131
- | `--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 |
115
+ | `--version-id <version_id>` | `versions.agents[<agent_id>].version_id` | Runs that version instead of the active one |
132
116
  | `--context <text>` (repeatable) | `context[]` | Extra text for the model |
133
117
  | `--data <json\|@file\|->` | the whole body | Flags override what `--data` brings; `--file` replaces its `messages` and warns on stderr (`Warning: --file replaces the messages of --data.`) |
134
118
  | `--verbose` | | Shows the result of each tool in full instead of cut to one line |
@@ -143,10 +127,10 @@ Ctrl+C stops reading and exits with `130`: the turn keeps running on the server
143
127
  There is no `skills update`: to change a skill, create a version.
144
128
 
145
129
  ```sh
146
- laburen skills list # --search <name>
130
+ laburen skills list
147
131
  laburen skills get <skill_id>
148
132
  laburen skills create --name my-skill --dir ./my-skill
149
- laburen skills delete <skill_id> # needs admin; resource_in_use if agents still use it
133
+ laburen skills delete <skill_id>
150
134
  laburen skills versions create <skill_id> --dir ./my-skill --change-message "fix steps"
151
135
  laburen skills versions list <skill_id>
152
136
  laburen skills versions get <skill_id> <version_id>
@@ -156,22 +140,17 @@ laburen skills versions delete <skill_id> <version_id>
156
140
  laburen skills versions compare <skill_id> --from <version_id> --to <version_id>
157
141
  ```
158
142
 
159
- A skill has only `SKILL.md` and files under `references/` (anything else fails with `invalid_skill`); `SKILL.md` needs a frontmatter with `name` (the same as the skill's name) and `description`. The first version is active unless you pass `--no-activate`; `versions create` never activates and prints `Created version <n> (not active). Activate it with: ...` on stderr, like `agents`. `--schema` works here like in every command with a body.
160
-
161
143
  `--dir <folder>` reads every file under the folder (relative paths with `/`, skipping `.git` and `node_modules`) and sends them as `files`. Do not combine it with `--files` or with a `--data` that has `files`; a `--data` without `files` (for example `{"name":"my-skill"}`) is combined with the folder. Only UTF-8 text is sent: a file with a NUL byte or invalid UTF-8 fails with exit 2 naming the file, and nothing is sent. Hidden files and folders (`.env`, `.DS_Store`...) and symbolic links are skipped, with a notice on stderr for each one.
162
144
 
163
145
  ## MCP connections
164
146
 
165
- The first version is active unless `--no-activate`; the agent assignment defaults to `strategy: "pin"`. Knowledge projects are created in the dashboard (`laburen knowledge projects list` only lists them, with the ids for `config.knowledge.project_ids`).
166
-
167
147
  ```sh
168
- laburen mcp connections list # --search <name>
148
+ laburen mcp connections list
169
149
  laburen mcp connections get <connection_id>
170
150
  laburen mcp connections create --name crm --url https://example.com/mcp --headers @headers.json
171
151
  laburen mcp connections update <connection_id> --name crm-prod
172
- laburen mcp connections delete <connection_id> # needs admin; resource_in_use if agents still use it
152
+ laburen mcp connections delete <connection_id>
173
153
  laburen mcp connections versions create <connection_id> --url https://example.com/mcp
174
- laburen mcp connections tools list <connection_id>
175
154
  laburen mcp connections versions list <connection_id>
176
155
  laburen mcp connections versions get <connection_id> <version_id>
177
156
  laburen mcp connections versions activate <connection_id> <version_id>
@@ -180,19 +159,12 @@ laburen mcp connections versions delete <connection_id> <version_id>
180
159
  laburen mcp connections versions compare <connection_id> --from <version_id> --to <version_id>
181
160
  ```
182
161
 
183
- `mcp connections versions create` without `--url` (or without `--headers`) keeps the value of the latest version; with neither, it writes `Warning: no --url or --headers given: the new version copies the latest one unchanged.` on stderr and still creates the copy; the response shows `[REDACTED]` as always. It also prints the `Created version <n> (not active)...` notice, and `mcp connections versions list` has columns HOST (`url_host`) and MESSAGE (`change_message`). The `url` of a version is always `[REDACTED]`. `tools: []` in an assigned connection (`--mcp-connections`) means all of its tools.
184
-
185
- `mcp connections tools list <connection_id>` connects to the server and lists the tools it offers (their `name` is what `--mcp-connections` takes in `tools`). A tool's name for the agent is the connection name as a prefix plus the tool name, so `mcp connections update --name` renames the tools agents see.
186
-
187
- 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
-
189
162
  ## Tokens
190
163
 
191
164
  ```sh
192
- laburen tokens list # --search <name>; revoked tokens stay listed
165
+ laburen tokens list
193
166
  laburen tokens create --name worker --data @token.json # token.json: kind, permissions...
194
167
  laburen tokens update <token_id> --description "worker prod"
195
- laburen tokens update <token_id> --description null # clears the description
196
168
  laburen tokens revoke <token_id>
197
169
  ```
198
170
 
@@ -203,11 +175,8 @@ laburen tokens revoke <token_id>
203
175
  ```sh
204
176
  laburen login
205
177
  laburen logout
206
- laburen whoami # user, organization, credential kind and permissions (an organization token shows `user none (organization credential)`)
207
- laburen me get # the same call, raw
208
- laburen completion [zsh|bash|powershell] # no shell: taken from $SHELL; --install saves it
209
178
  laburen orgs list # marks the current one
210
- laburen models list # table: NAME, ID, REASONING (levels and the default effort), IMAGES (native, described) and PDF (native, text + page image, transcribed), CACHE, CONTEXT, IN $/M, OUT $/M, CACHE READ $/M (all pages; --json also fetches all pages and prints one `{ "data": [ ... ] }`)
179
+ laburen models list # table: NAME, ID, REASONING (levels and the default effort), IMAGES (native, described) and PDF (native, text + page image, transcribed), CACHE, CONTEXT, IN $/M, OUT $/M, CACHE READ $/M (all pages; --json keeps the API shape)
211
180
  laburen orgs switch [<id>] # saves it; without id it asks (in a terminal) or fails with choices
212
181
  laburen link --org <id> # writes .laburen/link.json
213
182
  laburen unlink # deletes .laburen/link.json
@@ -6,9 +6,9 @@
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
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).
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. Nested objects appear as one-line JSON and lists of strings as `a,b`. 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
- 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).
11
+ If stdout is closed early (for example `laburen agents list | head -2`), the CLI exits quietly.
12
12
 
13
13
  ## `--json`
14
14
 
@@ -18,7 +18,7 @@ Prints the API response as JSON on stdout, nothing else. When the response is em
18
18
 
19
19
  ## `--paginate`
20
20
 
21
- List commands return one page by default (`--limit`, `--after-id`, `--before-id`). When there are more, stderr says `More results: use --paginate or --after-id <last_id>`. With `--paginate` the CLI fetches all pages. With `--json` it prints `{ "data": [ ... ] }`. `models list` always fetches all pages (with `--json` too, as one `{ "data": [ ... ] }`, no "More results" notice).
21
+ List commands return one page by default (`--limit`, `--after-id`, `--before-id`). When there are more, stderr says `More results: use --paginate or --after-id <last_id>`. With `--paginate` the CLI fetches all pages. With `--json` it prints `{ "data": [ ... ] }`.
22
22
 
23
23
  ## Errors
24
24
 
@@ -45,14 +45,14 @@ With `--json` or in non-interactive mode, the error goes to stdout as JSON:
45
45
  ```
46
46
 
47
47
  - `reason`: the API `code` when the API failed, otherwise one of the CLI reasons below. `request_id` is only present for API errors (the key is omitted otherwise).
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`).
48
+ - `issues`: only when the API sent them, as it sent them: `[{ "field": "...", "message": "..." }]`.
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
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.
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
 
55
- CLI reasons: `login_required`, `login_cancelled`, `cancelled`, `missing_arguments`, `invalid_arguments`, `missing_required`, `invalid_flag_value`, `config_required`, `agent_has_no_version`, `invalid_shell`, `invalid_link`, `invalid_token`, `organization_mismatch`, `organization_not_found`, `tool_not_found`, `confirmation_required`, `no_results`, `auth_lock_timeout`, `network_error`, `unexpected_error`.
55
+ CLI reasons: `login_required`, `login_cancelled`, `cancelled`, `missing_arguments`, `invalid_arguments`, `missing_required`, `invalid_flag_value`, `config_required`, `invalid_link`, `invalid_token`, `organization_mismatch`, `organization_not_found`, `tool_not_found`, `confirmation_required`, `no_results`, `auth_lock_timeout`, `network_error`, `unexpected_error`.
56
56
 
57
57
  - `login_required`: no saved session for this API URL, or the session expired. `next` keeps the `--api-url` and `--global-config` you used.
58
58
  - `invalid_token`: `LABUREN_TOKEN` was rejected; `next` is `unset LABUREN_TOKEN`.
@@ -63,37 +63,19 @@ CLI reasons: `login_required`, `login_cancelled`, `cancelled`, `missing_argument
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
- - `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
- - `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).
66
+ - `invalid_link`: `.laburen/link.json` is broken, or `.laburen` exists and is not a folder.
68
67
  - `auth_lock_timeout`: another `laburen` held the credentials lock too long; `next` is `rm "<lock file>"`.
69
68
  - `network_error`: the API could not be reached (or did not answer in time).
70
69
 
71
- Other reasons you may meet (API codes):
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`.
74
- - `conversation_not_found`: the `memory.thread` does not exist or belongs to another organization or agent.
75
- - `thread_resource_mismatch`: `memory.resource` is not the one that owns the `memory.thread`; send the same resource the thread started with.
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.
77
- - `invalid_request`/`invalid_agent_config` on `config.knowledge.project_ids`: a project id does not exist in this organization; `next` is `laburen knowledge projects list`.
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
- - `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
- - `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.
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
- - `internal_invariant_violation` (500): a bug on the server; keep the `request_id` and report it.
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
- - `insufficient_permissions`: the token lacks a permission. They are independent (`query`, `read`, `write`, `admin`); deleting agents, skills and MCP connections needs `admin`.
86
- - `invalid_shell` (CLI, exit 2): `laburen completion` got a shell it does not support; the message lists them.
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`.
70
+ Some API errors come with `next` too: `organization_access_denied` → `laburen orgs list`; `insufficient_permissions` → `laburen tokens list` (the token you used lacks the permission); `skill_name_taken` → `laburen skills list`; `mcp_connection_name_taken` → `laburen mcp connections list --search <value>`; `resource_in_use` → `laburen <command> --help` (the API only says how many agent versions use the resource, not which); `*_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`.
89
71
 
90
72
  ## Exit codes
91
73
 
92
74
  | Code | Meaning |
93
75
  |---|---|
94
76
  | `0` | ok (also `--help` and `--version`) |
95
- | `1` | the API or the network failed, login or a question cancelled, a resource that does not exist (as in the API: `*_not_found` from the API, `tool_not_found`, `organization_not_found`), nothing to pick from (`no_results`), an agent with no version to add a tool to (`agent_has_no_version`) |
96
- | `2` | wrong usage: missing argument, unknown command, invalid flag value (also an empty `--org`, reason `invalid_flag_value`), `--data` that is not a JSON object or a missing `@file`, a `--dir` with a file that is not UTF-8 text (no request is sent), organization mismatch, broken `link.json` |
77
+ | `1` | the API or the network failed, login or a question cancelled, a resource that does not exist (as in the API: `*_not_found` from the API, `tool_not_found`, `organization_not_found`), nothing to pick from (`no_results`) |
78
+ | `2` | wrong usage: missing argument, unknown command, invalid flag value (also an empty `--org`), `--data` that is not a JSON object or a missing `@file`, a `--dir` with a file that is not UTF-8 text (no request is sent), organization mismatch, broken `link.json` |
97
79
  | `130` | Ctrl+C during `agents run` (the turn keeps running on the server) |
98
80
 
99
81
  ## Non-interactive mode
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.9",
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.9",
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
- /** Un comando que sigue útil por stderr con stdout cerrado (el turno en vivo de `agents run`, C24) pide no salir. */
2
- export declare function keepRunningIfStdoutCloses(): void;
3
- /** Si el proceso tiene que salir al cerrarse stdout: sí, salvo que un comando haya pedido seguir. */
4
- export declare function shouldExitOnStdoutClose(): boolean;
@@ -1,11 +0,0 @@
1
- /** Qué hace el proceso cuando quien lee stdout cierra el pipe (`| head`). */
2
- let keepRunning = false;
3
- /** Un comando que sigue útil por stderr con stdout cerrado (el turno en vivo de `agents run`, C24) pide no salir. */
4
- export function keepRunningIfStdoutCloses() {
5
- keepRunning = true;
6
- }
7
- /** Si el proceso tiene que salir al cerrarse stdout: sí, salvo que un comando haya pedido seguir. */
8
- export function shouldExitOnStdoutClose() {
9
- return !keepRunning;
10
- }
11
- //# sourceMappingURL=stdout-policy.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"stdout-policy.js","sourceRoot":"","sources":["../src/stdout-policy.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,IAAI,WAAW,GAAG,KAAK,CAAC;AAExB,qHAAqH;AACrH,MAAM,UAAU,yBAAyB;IACxC,WAAW,GAAG,IAAI,CAAC;AACpB,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,uBAAuB;IACtC,OAAO,CAAC,WAAW,CAAC;AACrB,CAAC"}