@laburen/delta-cli 0.0.0-stage → 0.2.0-canary.10
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/LICENSE +21 -0
- package/README.md +33 -2
- package/dist/bin.d.ts +2 -0
- package/dist/bin.js +20 -0
- package/dist/bin.js.map +1 -0
- package/dist/commands/agent-checks.d.ts +5 -0
- package/dist/commands/agent-checks.js +69 -0
- package/dist/commands/agent-checks.js.map +1 -0
- package/dist/commands/agent-run/body.d.ts +22 -0
- package/dist/commands/agent-run/body.js +88 -0
- package/dist/commands/agent-run/body.js.map +1 -0
- package/dist/commands/agent-run/render.d.ts +50 -0
- package/dist/commands/agent-run/render.js +281 -0
- package/dist/commands/agent-run/render.js.map +1 -0
- package/dist/commands/agent-run.d.ts +10 -0
- package/dist/commands/agent-run.js +243 -0
- package/dist/commands/agent-run.js.map +1 -0
- package/dist/commands/agent-tools/add.d.ts +5 -0
- package/dist/commands/agent-tools/add.js +101 -0
- package/dist/commands/agent-tools/add.js.map +1 -0
- package/dist/commands/agent-tools/remove.d.ts +5 -0
- package/dist/commands/agent-tools/remove.js +126 -0
- package/dist/commands/agent-tools/remove.js.map +1 -0
- package/dist/commands/agent-tools/shared.d.ts +283 -0
- package/dist/commands/agent-tools/shared.js +107 -0
- package/dist/commands/agent-tools/shared.js.map +1 -0
- package/dist/commands/agent-tools.d.ts +5 -0
- package/dist/commands/agent-tools.js +11 -0
- package/dist/commands/agent-tools.js.map +1 -0
- package/dist/commands/auth.d.ts +14 -0
- package/dist/commands/auth.js +171 -0
- package/dist/commands/auth.js.map +1 -0
- package/dist/commands/completion.d.ts +4 -0
- package/dist/commands/completion.js +50 -0
- package/dist/commands/completion.js.map +1 -0
- package/dist/commands/config-sources.d.ts +22 -0
- package/dist/commands/config-sources.js +46 -0
- package/dist/commands/config-sources.js.map +1 -0
- package/dist/commands/config-wizard.d.ts +9 -0
- package/dist/commands/config-wizard.js +332 -0
- package/dist/commands/config-wizard.js.map +1 -0
- package/dist/commands/orgs.d.ts +11 -0
- package/dist/commands/orgs.js +193 -0
- package/dist/commands/orgs.js.map +1 -0
- package/dist/commands/skill-dir.d.ts +18 -0
- package/dist/commands/skill-dir.js +101 -0
- package/dist/commands/skill-dir.js.map +1 -0
- package/dist/commands/token-notice.d.ts +4 -0
- package/dist/commands/token-notice.js +13 -0
- package/dist/commands/token-notice.js.map +1 -0
- package/dist/commands/whoami.d.ts +8 -0
- package/dist/commands/whoami.js +38 -0
- package/dist/commands/whoami.js.map +1 -0
- package/dist/commands/wizards.d.ts +4 -0
- package/dist/commands/wizards.js +210 -0
- package/dist/commands/wizards.js.map +1 -0
- package/dist/completion/bash.d.ts +3 -0
- package/dist/completion/bash.js +60 -0
- package/dist/completion/bash.js.map +1 -0
- package/dist/completion/files.d.ts +35 -0
- package/dist/completion/files.js +178 -0
- package/dist/completion/files.js.map +1 -0
- package/dist/completion/powershell.d.ts +9 -0
- package/dist/completion/powershell.js +83 -0
- package/dist/completion/powershell.js.map +1 -0
- package/dist/completion/tree.d.ts +25 -0
- package/dist/completion/tree.js +53 -0
- package/dist/completion/tree.js.map +1 -0
- package/dist/completion/zsh.d.ts +3 -0
- package/dist/completion/zsh.js +76 -0
- package/dist/completion/zsh.js.map +1 -0
- package/dist/config/auth.d.ts +26 -0
- package/dist/config/auth.js +223 -0
- package/dist/config/auth.js.map +1 -0
- package/dist/config/link.d.ts +16 -0
- package/dist/config/link.js +93 -0
- package/dist/config/link.js.map +1 -0
- package/dist/config/paths.d.ts +3 -0
- package/dist/config/paths.js +20 -0
- package/dist/config/paths.js.map +1 -0
- package/dist/config/settings.d.ts +8 -0
- package/dist/config/settings.js +24 -0
- package/dist/config/settings.js.map +1 -0
- package/dist/confirm.d.ts +35 -0
- package/dist/confirm.js +51 -0
- package/dist/confirm.js.map +1 -0
- package/dist/context.d.ts +29 -0
- package/dist/context.js +16 -0
- package/dist/context.js.map +1 -0
- package/dist/errors.d.ts +54 -0
- package/dist/errors.js +413 -0
- package/dist/errors.js.map +1 -0
- package/dist/generated/commands.d.ts +49 -0
- package/dist/generated/commands.js +52 -0
- package/dist/generated/commands.js.map +1 -0
- package/dist/generated/schemas.d.ts +5 -0
- package/dist/generated/schemas.js +20 -0
- package/dist/generated/schemas.js.map +1 -0
- package/dist/invocation.d.ts +64 -0
- package/dist/invocation.js +341 -0
- package/dist/invocation.js.map +1 -0
- package/dist/mode.d.ts +17 -0
- package/dist/mode.js +22 -0
- package/dist/mode.js.map +1 -0
- package/dist/operations/call.d.ts +6 -0
- package/dist/operations/call.js +17 -0
- package/dist/operations/call.js.map +1 -0
- package/dist/operations/extensions.d.ts +46 -0
- package/dist/operations/extensions.js +29 -0
- package/dist/operations/extensions.js.map +1 -0
- package/dist/operations/json-input.d.ts +7 -0
- package/dist/operations/json-input.js +50 -0
- package/dist/operations/json-input.js.map +1 -0
- package/dist/operations/params.d.ts +17 -0
- package/dist/operations/params.js +106 -0
- package/dist/operations/params.js.map +1 -0
- package/dist/operations/register.d.ts +10 -0
- package/dist/operations/register.js +102 -0
- package/dist/operations/register.js.map +1 -0
- package/dist/operations/run-operation.d.ts +8 -0
- package/dist/operations/run-operation.js +148 -0
- package/dist/operations/run-operation.js.map +1 -0
- package/dist/operations/schema-flag.d.ts +8 -0
- package/dist/operations/schema-flag.js +12 -0
- package/dist/operations/schema-flag.js.map +1 -0
- package/dist/operations/skeleton.d.ts +16 -0
- package/dist/operations/skeleton.js +116 -0
- package/dist/operations/skeleton.js.map +1 -0
- package/dist/operations/tables.d.ts +7 -0
- package/dist/operations/tables.js +131 -0
- package/dist/operations/tables.js.map +1 -0
- package/dist/operations.d.ts +5 -0
- package/dist/operations.js +7 -0
- package/dist/operations.js.map +1 -0
- package/dist/output.d.ts +33 -0
- package/dist/output.js +321 -0
- package/dist/output.js.map +1 -0
- package/dist/pickers.d.ts +51 -0
- package/dist/pickers.js +277 -0
- package/dist/pickers.js.map +1 -0
- package/dist/program.d.ts +31 -0
- package/dist/program.js +260 -0
- package/dist/program.js.map +1 -0
- package/dist/prompter.d.ts +54 -0
- package/dist/prompter.js +129 -0
- package/dist/prompter.js.map +1 -0
- package/dist/session.d.ts +45 -0
- package/dist/session.js +170 -0
- package/dist/session.js.map +1 -0
- package/dist/stdout-policy.d.ts +4 -0
- package/dist/stdout-policy.js +11 -0
- package/dist/stdout-policy.js.map +1 -0
- package/dist/update-check.d.ts +4 -0
- package/dist/update-check.js +60 -0
- package/dist/update-check.js.map +1 -0
- package/docs/SKILL.md +175 -0
- package/docs/references/auth-and-organizations.md +72 -0
- package/docs/references/commands.md +217 -0
- package/docs/references/output-and-errors.md +105 -0
- package/package.json +39 -5
package/docs/SKILL.md
ADDED
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
---
|
|
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".
|
|
4
|
+
metadata:
|
|
5
|
+
package: "@laburen/delta-cli"
|
|
6
|
+
---
|
|
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
|
+
## When to use
|
|
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.
|
|
16
|
+
|
|
17
|
+
## How to use
|
|
18
|
+
|
|
19
|
+
Install and run:
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
npm i -g @laburen/delta-cli
|
|
23
|
+
laburen login
|
|
24
|
+
laburen agents list
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
- 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
|
+
- Every command accepts `--json`, `--org`, `--api-url`, `--global-config`, `--non-interactive`, `--no-non-interactive` and `--no-color`.
|
|
29
|
+
- 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`.
|
|
32
|
+
- 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
|
+
- Exit codes: `0` ok, `1` API or network error, `2` wrong usage.
|
|
34
|
+
|
|
35
|
+
## Discover, then build
|
|
36
|
+
|
|
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.
|
|
40
|
+
- `--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
|
+
- `--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
|
+
- A selector (an agent, a skill, a connection by name) searches by name when the list has more than one page.
|
|
43
|
+
- Interactive `agents create` (after `Configure the first version now?`) and `agents versions create` ask the whole config, with models from `laburen models list` and projects from `laburen knowledge projects list`. Headers of http tools are never asked because they are secrets.
|
|
44
|
+
|
|
45
|
+
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
|
+
|
|
47
|
+
- `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"}`.
|
|
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 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`).
|
|
87
|
+
|
|
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
|
+
```
|
|
113
|
+
|
|
114
|
+
Order of steps: first create what the agent will use and look up ids, then build the agent.
|
|
115
|
+
|
|
116
|
+
```sh
|
|
117
|
+
laburen skills create --name faq --dir ./faq --json
|
|
118
|
+
laburen mcp connections create --name crm --url https://example.com/mcp --json
|
|
119
|
+
laburen knowledge projects list --json
|
|
120
|
+
laburen models list --json
|
|
121
|
+
laburen agents create --name Support --harness-type mastra --config @config.json \
|
|
122
|
+
--skills '[{"skill_id":"<skill_id>"}]' --mcp-connections '[{"connection_id":"<connection_id>"}]' --json
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
`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
|
+
|
|
127
|
+
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
|
+
|
|
129
|
+
`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.
|
|
130
|
+
|
|
131
|
+
## Questions: when the CLI asks and when it never does
|
|
132
|
+
|
|
133
|
+
The CLI asks a question only if all of this is true: no `--non-interactive` (an AI agent without a terminal gets it on its own), no `--json`, no `CI` variable with a non-empty value, and stdin and stderr are terminals. Questions are drawn on stderr. Otherwise it never asks: it fails with a JSON error that says what to pass.
|
|
134
|
+
|
|
135
|
+
Every question has a flag that replaces it, so an agent never needs one:
|
|
136
|
+
|
|
137
|
+
- A missing id (`laburen agents get`): pass the id. Without it the error is `missing_arguments` with `choices`. If the list cannot be fetched there are no `choices`; if you are not logged in the error is `login_required`.
|
|
138
|
+
- 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
|
+
- `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
|
+
- `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).
|
|
141
|
+
- `versions compare`: `--from` and `--to`.
|
|
142
|
+
- `orgs switch`: the organization id. Without it the error is `missing_arguments` with `choices`, like a missing id.
|
|
143
|
+
- `--data -` reads the body from stdin, so the CLI cannot ask anything else in that run: a missing required field fails with `missing_required`.
|
|
144
|
+
|
|
145
|
+
What to do with each error when you are an AI agent:
|
|
146
|
+
|
|
147
|
+
- `confirmation_required` (exit 2, `userActionRequired: true`): something would be deleted or revoked. Ask the user. Only if they approve, run the `next` command: it is the same command with `--yes`. **Never add `--yes` on your own.**
|
|
148
|
+
- `missing_arguments` with `choices` (exit 2, `userActionRequired: true`): show the user the `choices` (`{ id, name }`, the current one with `current: true`) and ask which one. Then run the `next` that has that id. **Do not choose yourself**, even if one looks obvious.
|
|
149
|
+
- `cancelled` (exit 1): the person cancelled a question (Ctrl-C, Esc, Ctrl-D, or No at a confirmation). Nothing changed. Do not retry on your own.
|
|
150
|
+
- `config_required` (exit 2): `agents create` got `--skills`, `--mcp-connections` or `--activate` without `--config`. Add `--config` (the `next` shows where) or drop those flags.
|
|
151
|
+
- `<value>` in a `next` command: the value of a secret flag (`--data`, `--headers`, `--config`, `--tool`, `--token`...) is never copied into `next`, in any error. Put the real value back before running it. `<id>` and `<version_id>` are also placeholders: you get them from a `list` or from the user.
|
|
152
|
+
|
|
153
|
+
Commands an agent can run without any question:
|
|
154
|
+
|
|
155
|
+
```sh
|
|
156
|
+
laburen agents create --name Support --harness-type mastra --config @config.json --json
|
|
157
|
+
laburen tokens create --name worker --kind organization --permissions '["read","write"]' --json
|
|
158
|
+
laburen skills create --name faq --dir ./faq --json
|
|
159
|
+
laburen mcp connections create --name crm --url https://example.com/mcp --headers @headers.json --json
|
|
160
|
+
laburen agents versions compare <agent_id> --from <version_id> --to <version_id> --json
|
|
161
|
+
laburen orgs switch <org_id> --json
|
|
162
|
+
laburen agents delete <agent_id> --json # fails with confirmation_required: ask the user before adding --yes
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
Read the individual reference documents for details.
|
|
166
|
+
|
|
167
|
+
## Run an agent
|
|
168
|
+
|
|
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.
|
|
170
|
+
|
|
171
|
+
### References
|
|
172
|
+
|
|
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`.
|
|
174
|
+
- [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
|
+
- [Output and errors](references/output-and-errors.md) - stdout vs stderr, `--json`, `--paginate`, the error JSON with `next`, exit codes, colors.
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Auth and organizations
|
|
2
|
+
|
|
3
|
+
## Login
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
laburen login
|
|
7
|
+
```
|
|
8
|
+
|
|
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
|
+
|
|
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.
|
|
12
|
+
|
|
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
|
+
|
|
15
|
+
## Where credentials live
|
|
16
|
+
|
|
17
|
+
`auth.json` (`token`, `refresh_token`, `expires_at`, `api_url`; mode `600`, folder `700`) and `config.json` (the saved organization) are in:
|
|
18
|
+
|
|
19
|
+
- Linux: `$XDG_DATA_HOME/laburen` or `~/.local/share/laburen`
|
|
20
|
+
- macOS: `~/Library/Application Support/laburen`
|
|
21
|
+
- Windows: `%APPDATA%\laburen`
|
|
22
|
+
|
|
23
|
+
Change the folder with `--global-config <dir>` or `LABUREN_CONFIG_DIR`. Different folders are separate sessions. The flag wins over the variable. An empty `HOME`, `XDG_DATA_HOME` or `APPDATA` counts as not set.
|
|
24
|
+
|
|
25
|
+
The token renews itself when it is about to expire. Parallel commands do not spend the refresh twice. If the API rejects the saved token because another command renewed it in the meantime, the CLI notices that `auth.json` changed and retries once with the new token (also the list it reads to offer `choices` when it cannot ask); ids already picked are not asked again. While a command waits for another one that is renewing, it says so on stderr after one second. A lock left by a process that no longer exists on this machine is taken right away (the lock records host, pid and a random id). A lock written from another host (a config folder shared over the network or mounted into a container) is only taken once it is older than 60 seconds. If another command holds the renewal lock for more than 70 seconds the CLI fails with `auth_lock_timeout`; `next` gives the lock file to delete if no other `laburen` is running. Known limits: an owner that is still alive but holds the lock for more than 60 seconds (for example a suspended laptop) can lose it to another command; and when a lock is taken by mistake (its owner released it and a new one appeared just then), the CLI puts it back with a rename followed by a link, so for an instant the lock file does not exist and a third command could take it. Only a rejected refresh token (`invalid_grant`, `invalid_token` or `expired_token`) asks you to log in again; a server error leaves your credentials untouched. A broken or half-written `auth.json` counts as "not signed in" (`login_required`).
|
|
26
|
+
|
|
27
|
+
## `LABUREN_TOKEN`
|
|
28
|
+
|
|
29
|
+
With `LABUREN_TOKEN` set, the CLI uses it as the token and does not read or write any credential file. `laburen login` still works but warns that the variable overrides saved credentials; `laburen logout` does nothing and tells you to unset the variable. If the API rejects the token, the error has reason `invalid_token` and `next` is `unset LABUREN_TOKEN` (logging in would not help, the variable wins).
|
|
30
|
+
|
|
31
|
+
## API URL
|
|
32
|
+
|
|
33
|
+
`--api-url`, then `LABUREN_API_URL`, then `https://dashboard.laburen.com/api/platform/v1`.
|
|
34
|
+
|
|
35
|
+
Saved credentials are bound to the URL they were created for. If the current URL is different, the CLI does not send the token and fails with `login_required`. Log in again for that URL: the `next` login command already carries `--api-url` (and `--global-config` if you used one). A trailing `/` in the URL is ignored. `LABUREN_TOKEN` is sent to whatever URL is configured.
|
|
36
|
+
|
|
37
|
+
## Which organization is used
|
|
38
|
+
|
|
39
|
+
First match wins:
|
|
40
|
+
|
|
41
|
+
1. `--org <id>`
|
|
42
|
+
2. `LABUREN_ORG`
|
|
43
|
+
3. `.laburen/link.json`, found in the current folder or any parent
|
|
44
|
+
4. the organization saved with `laburen orgs switch`
|
|
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).
|
|
47
|
+
|
|
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
|
+
|
|
50
|
+
In non-interactive mode, the saved organization (4) is ignored. If 1 to 3 give nothing, the request goes without an organization header and the API decides: a token that belongs to one organization needs none; a token for all organizations fails with `invalid_request`, and the error's `next` says to pass `--org <id>`.
|
|
51
|
+
|
|
52
|
+
`laburen orgs list` and `laburen me organizations list` never send an organization header. They and `laburen orgs switch` keep working with a broken `link.json` or a mismatch: they only use the organization to mark the current one. The current one is the organization resolved by the rules above or, if there is none, the saved one; in non-interactive mode the saved one is also marked, only as information (requests still do not send it).
|
|
53
|
+
|
|
54
|
+
`laburen orgs switch` without an id asks you to pick one from a list (with search when there are more than 15); the current one is preselected and marked `(current)`. If you only have one organization it is picked for you and named on stderr. Ctrl-C, Esc or Ctrl-D cancels (`cancelled`, exit 1). It only asks when stdin and stderr are terminals and there is no `--non-interactive`, `--json` or `CI`; otherwise it fails with `missing_arguments` (exit 2) with `choices` (the current one with `current: true`) and one `next` per organization; ask the user which one. In non-interactive mode it saves the organization and says on stderr `Saved <name> (<id>). Non-interactive runs ignore the saved organization: use --org <id> or laburen link --org <id>.` (no "Now using": that mode does not send it).
|
|
55
|
+
|
|
56
|
+
## `link.json`
|
|
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.
|
|
59
|
+
|
|
60
|
+
## Test against a local dashboard
|
|
61
|
+
|
|
62
|
+
From the repo root, without publishing:
|
|
63
|
+
|
|
64
|
+
```sh
|
|
65
|
+
npm run build -w @laburen/delta-sdk # the CLI imports the SDK build; or build the whole workspace: npm run build
|
|
66
|
+
npm run build -w @laburen/delta-cli
|
|
67
|
+
npm link -w @laburen/delta-cli # or: cd packages/delta-cli && npm link
|
|
68
|
+
LABUREN_API_URL=http://localhost:3000/api/platform/v1 laburen login
|
|
69
|
+
LABUREN_API_URL=http://localhost:3000/api/platform/v1 laburen agents list
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
The approval link comes from the server, so with the local dashboard it points to `localhost:3000/device`. To keep local and production sessions apart, add `LABUREN_CONFIG_DIR=/tmp/laburen-local` (or `--global-config`).
|
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
# Commands
|
|
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`.
|
|
4
|
+
|
|
5
|
+
## Confirmation before deleting
|
|
6
|
+
|
|
7
|
+
Every `delete`, `tokens revoke` and `agents tools remove` asks before it changes anything: `Delete agent <id>?`, `Revoke token <id>?`, `Remove tool <id> of agent <id>?`. `agents tools remove` first reads the latest version, so a tool that does not exist fails with `tool_not_found` without asking; that read needs a session, so without one it fails with `login_required` before asking or failing with `confirmation_required`. The default answer is No; answering No (or Ctrl-C, Esc, Ctrl-D) cancels with `cancelled` (exit 1) and changes nothing. `--yes` (`-y`) skips the question, except when the id was picked from a list (see below): then the CLI always asks. `logout` and `unlink` do not ask.
|
|
8
|
+
|
|
9
|
+
If the CLI cannot ask (`--non-interactive`, `--json`, `CI`, or stdin or stderr is not a terminal) and there is no `--yes`, it fails with `confirmation_required` (exit 2). The error has `userActionRequired: true`, and `next` is the command you ran plus `--yes`, with `when` like `Only after the user approves deleting agent <id>` (`revoking token <id>`, `removing tool <id> of agent <id>`). **If you are an AI agent: ask the user first; run the `next` command only after they say yes.** Secrets are not copied into that command: the value of `--token`, `-t`, `--refresh-token`, `--data`, `--headers`, `--config`, `--tool`, `--files`, `--value`, `--secret` and `--password` becomes `<value>` (for example `--data <value>`), also when the value starts with `-` (`--data -`) or is glued to `-t` (`-tVALUE`); fill it back in before running it. In `--url` only the user and password and the values of the query and the fragment become `<value>`.
|
|
10
|
+
|
|
11
|
+
## Picking a missing id
|
|
12
|
+
|
|
13
|
+
The ids in the commands below are optional, also in `agents tools add` and `agents tools remove`. If one is missing and the CLI can ask (a terminal, no `--json`, no `--non-interactive`, no `CI`), it lists the first 100 items and asks you to pick one: the name is the label, the id is shown next to it (an item without a name shows only its id), and the active version is preselected and marked `(current)`. Versions are shown as `v<number> · <date>`. Several missing ids are asked in order: `laburen agents versions activate` asks for the agent and then for the version.
|
|
14
|
+
|
|
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
|
+
- 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
|
+
- 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>`).
|
|
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
|
+
- `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
|
+
|
|
22
|
+
If the CLI cannot ask, a missing id fails with `missing_arguments` (exit 2), `userActionRequired: true` and `choices` with up to 20 `{ id, name }` (the active version also has `current: true`), plus one `next` per choice: the command you ran with that id (secret values as `<value>`), `when` "Ask the user which one; do not choose yourself". In delete, revoke and remove those commands drop `--yes`, so choosing one still needs the user's approval of the delete. **If you are an AI agent: ask the user which one; never pick it yourself.** If you are not logged in, the error is `login_required` with its `next`. If the list cannot be fetched for another reason, it is the plain `missing_arguments` error. A missing id is checked after the flags: if a required flag is missing too, the error is `missing_required` and its `next` has the id as a placeholder (`laburen agents versions compare <agent_id> --from v1 --to <value>`).
|
|
23
|
+
|
|
24
|
+
## Questions in create
|
|
25
|
+
|
|
26
|
+
If the CLI can ask (same rules as above), these `create` commands ask only for what did not come by flag or `--data`. A flag never turns the questions off: `--name` skips the name question and the rest are still asked. A required field with a single possible value (`harness_type: mastra`) is filled in without asking, also when the CLI cannot ask. `agents create` and `agents versions create` also ask the whole `config` (see below); other JSON fields (`files`...) are not asked: if one is required and missing, it fails with `missing_required` as usual. Ctrl-C, Esc or Ctrl-D cancels with `cancelled` (exit 1) and nothing is created. If the CLI cannot ask, missing required fields fail with `missing_required` (exit 2). With `--data -` stdin is used for the body, so nothing is asked in that run: missing fields fail with `missing_required`.
|
|
27
|
+
|
|
28
|
+
| Command | Question | Flag that replaces it |
|
|
29
|
+
|---|---|---|
|
|
30
|
+
| `agents create` | Agent name (text) | `--name` |
|
|
31
|
+
| | Configure the first version now? (default Yes; not asked if `--config`, `--skills`, `--mcp-connections` or `--activate` came by flag or `--data`) | `--config` |
|
|
32
|
+
| | The config: model (from `models list`), then the optional fields you choose to set, down to each tool; headers of http tools are not asked | `--config` |
|
|
33
|
+
| | Skills for the agent (pick several from `skills list`; skipped if there are none) | `--skills` |
|
|
34
|
+
| | MCP connections for the agent (pick several from `mcp connections list`; skipped if there are none) | `--mcp-connections` |
|
|
35
|
+
| | Activate the first version now? (default Yes) | `--activate` / `--no-activate` |
|
|
36
|
+
| `agents versions create` | The config (as in `agents create`), then skills and MCP connections (same questions); the new version is not activated | `--config`, `--skills`, `--mcp-connections` |
|
|
37
|
+
| `tokens create` | Token name (text) | `--name` |
|
|
38
|
+
| | Token kind (`personal` or `organization`) | `--kind` |
|
|
39
|
+
| | Token permissions (pick at least one of `query`, `read`, `write`, `admin`) | `--permissions` |
|
|
40
|
+
| `skills create` | Skill name (text) | `--name` |
|
|
41
|
+
| | Folder with the skill files (text; read like `--dir`; a folder that cannot be read, is empty or has a binary file is asked again, with the reason on stderr) | `--dir` or `--files` |
|
|
42
|
+
| `mcp connections create` | Connection name (text) | `--name` |
|
|
43
|
+
| | MCP server URL (text) | `--url` |
|
|
44
|
+
|
|
45
|
+
- Answering No to `Configure the first version now?` creates the agent without a version, so it does not ask for skills, MCP connections or activate. Add them later with `laburen agents update <agent_id> --config @config.json` or `laburen agents versions create <agent_id> --config @config.json`.
|
|
46
|
+
- `agents create` with `--skills`, `--mcp-connections` or `--activate` (by flag or in `--data`) and without `--config` fails with `config_required` (exit 2) and nothing is created, because the API would drop them without a version. `next` is your command plus `--config <value>`. If the CLI can ask, it does not fail: it goes straight to the config questions.
|
|
47
|
+
- An optional text left blank in the config questions is not sent.
|
|
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
|
+
- 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`).
|
|
51
|
+
|
|
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
|
+
|
|
54
|
+
## Agents
|
|
55
|
+
|
|
56
|
+
```sh
|
|
57
|
+
laburen agents list # --limit, --after-id, --before-id, --paginate, --search <name>
|
|
58
|
+
laburen agents get <agent_id>
|
|
59
|
+
laburen agents create --name Support --harness-type mastra
|
|
60
|
+
laburen agents create --data @agent.json # name, harness_type, config...
|
|
61
|
+
laburen agents update <agent_id> --name "Support v2"
|
|
62
|
+
laburen agents update <agent_id> --config @config.json --change-message "new prompt"
|
|
63
|
+
laburen agents delete <agent_id> # needs the admin permission
|
|
64
|
+
```
|
|
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
|
+
```
|
|
74
|
+
|
|
75
|
+
Versions:
|
|
76
|
+
|
|
77
|
+
```sh
|
|
78
|
+
laburen agents versions list <agent_id>
|
|
79
|
+
laburen agents versions get <agent_id> <version_id>
|
|
80
|
+
laburen agents versions create <agent_id> --config @config.json --change-message "new prompt"
|
|
81
|
+
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)..."
|
|
83
|
+
laburen agents versions delete <agent_id> <version_id>
|
|
84
|
+
laburen agents versions compare <agent_id> --from <version_id> --to <version_id>
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Without `--json`, `compare` prints one difference per line, with the same rule as in [Output and errors](output-and-errors.md): a string longer than 120 characters, or a list of only text blocks (the prompt), shows its first 60 characters (`"You are a…" (N chars)`); any other list or object is summarized (`<list, N items>`, `<object, N keys>`) only when its JSON is longer than 120 characters, and a shorter one is printed whole. Use `--json` for the full values. For MCP connections the compared field is `url_host` (the `url` is always `[REDACTED]`).
|
|
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
|
+
Tools (reads the latest version, changes `config.tools`, and creates a new version; the new version is not active unless you pass `--activate`):
|
|
94
|
+
|
|
95
|
+
```sh
|
|
96
|
+
laburen agents tools add <agent_id> --tool '{"type":"send_files"}'
|
|
97
|
+
laburen agents tools add <agent_id> --tool @tool.json
|
|
98
|
+
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
|
|
101
|
+
laburen agents tools add --schema # JSON Schema of a tool and of the response; no login, no API call
|
|
102
|
+
```
|
|
103
|
+
|
|
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.
|
|
105
|
+
|
|
106
|
+
## Run an agent
|
|
107
|
+
|
|
108
|
+
```sh
|
|
109
|
+
laburen agents run <agent_id> "Do you have the XR 150 in stock?"
|
|
110
|
+
echo "Hello" | laburen agents run <agent_id> # no message argument: reads stdin when it is not a terminal
|
|
111
|
+
laburen agents run <agent_id> --thread <thread_id> "And in red?"
|
|
112
|
+
laburen agents run <agent_id> --file https://example.com/menu.pdf "Summarize this"
|
|
113
|
+
laburen agents run <agent_id> --version-id <version_id> --context "The user is a VIP" "Hi"
|
|
114
|
+
laburen agents run <agent_id> "Hi" --json # waits for the end and prints the final JSON
|
|
115
|
+
```
|
|
116
|
+
|
|
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.
|
|
120
|
+
|
|
121
|
+
| Flag | Body field | Note |
|
|
122
|
+
|---|---|---|
|
|
123
|
+
| `[message]` or stdin | `messages` | With `--file`, the message has a text part and one `file` part per URL; with only `--file` the message is just the files |
|
|
124
|
+
| `--thread <id>` | `memory.thread` | Continues a previous conversation |
|
|
125
|
+
| `--resource <id>` | `memory.resource` | Your own id for the end user |
|
|
126
|
+
| `--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
|
+
| `--instructions <text\|@file>` | `instructions` | Replaces the prompt for this run. Needs `write` permission (the API rejects it otherwise) |
|
|
128
|
+
| `--model <id>` | `model` | Same permission |
|
|
129
|
+
| `--reasoning <level>` | `model_settings.reasoning` | `off`, `low`, `medium`, `high` or `max`; same permission |
|
|
130
|
+
| `--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 |
|
|
132
|
+
| `--context <text>` (repeatable) | `context[]` | Extra text for the model |
|
|
133
|
+
| `--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
|
+
| `--verbose` | | Shows the result of each tool in full instead of cut to one line |
|
|
135
|
+
| `--json` | | Uses `/generate`: prints the final JSON on stdout and nothing else |
|
|
136
|
+
|
|
137
|
+
The message comes from the argument; if there is none, from `--file` or the `messages` of `--data`; only if none of those exist and stdin is not a terminal is stdin read. Without any message it fails with `missing_required` (exit 2).
|
|
138
|
+
|
|
139
|
+
Ctrl+C stops reading and exits with `130`: the turn keeps running on the server and is billed. stderr says so and, if the thread was already known, prints the `continue:` command. If the turn fails midway, what was already printed stays, and the error goes to stderr (exit 1); its `next` is the `continue:` command of the thread, not `--help`. If stdout is closed (`| head -1`) the CLI stops quietly and still prints the `continue:` line on stderr; a closed stderr also stops it quietly. A turn that takes more than 10 minutes fails with `turn_deadline_exceeded`.
|
|
140
|
+
|
|
141
|
+
## Skills
|
|
142
|
+
|
|
143
|
+
There is no `skills update`: to change a skill, create a version.
|
|
144
|
+
|
|
145
|
+
```sh
|
|
146
|
+
laburen skills list # --search <name>
|
|
147
|
+
laburen skills get <skill_id>
|
|
148
|
+
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
|
|
150
|
+
laburen skills versions create <skill_id> --dir ./my-skill --change-message "fix steps"
|
|
151
|
+
laburen skills versions list <skill_id>
|
|
152
|
+
laburen skills versions get <skill_id> <version_id>
|
|
153
|
+
laburen skills versions activate <skill_id> <version_id>
|
|
154
|
+
laburen skills versions restore <skill_id> <version_id>
|
|
155
|
+
laburen skills versions delete <skill_id> <version_id>
|
|
156
|
+
laburen skills versions compare <skill_id> --from <version_id> --to <version_id>
|
|
157
|
+
```
|
|
158
|
+
|
|
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
|
+
`--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
|
+
|
|
163
|
+
## MCP connections
|
|
164
|
+
|
|
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
|
+
```sh
|
|
168
|
+
laburen mcp connections list # --search <name>
|
|
169
|
+
laburen mcp connections get <connection_id>
|
|
170
|
+
laburen mcp connections create --name crm --url https://example.com/mcp --headers @headers.json
|
|
171
|
+
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
|
|
173
|
+
laburen mcp connections versions create <connection_id> --url https://example.com/mcp
|
|
174
|
+
laburen mcp connections tools list <connection_id>
|
|
175
|
+
laburen mcp connections versions list <connection_id>
|
|
176
|
+
laburen mcp connections versions get <connection_id> <version_id>
|
|
177
|
+
laburen mcp connections versions activate <connection_id> <version_id>
|
|
178
|
+
laburen mcp connections versions restore <connection_id> <version_id>
|
|
179
|
+
laburen mcp connections versions delete <connection_id> <version_id>
|
|
180
|
+
laburen mcp connections versions compare <connection_id> --from <version_id> --to <version_id>
|
|
181
|
+
```
|
|
182
|
+
|
|
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
|
+
## Tokens
|
|
190
|
+
|
|
191
|
+
```sh
|
|
192
|
+
laburen tokens list # --search <name>; revoked tokens stay listed
|
|
193
|
+
laburen tokens create --name worker --data @token.json # token.json: kind, permissions...
|
|
194
|
+
laburen tokens update <token_id> --description "worker prod"
|
|
195
|
+
laburen tokens update <token_id> --description null # clears the description
|
|
196
|
+
laburen tokens revoke <token_id>
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
`tokens create` prints the token `value` once. Without `--json` it also warns on stderr that the value will not be shown again.
|
|
200
|
+
|
|
201
|
+
## Account and organization
|
|
202
|
+
|
|
203
|
+
```sh
|
|
204
|
+
laburen login
|
|
205
|
+
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
|
+
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": [ ... ] }`)
|
|
211
|
+
laburen orgs switch [<id>] # saves it; without id it asks (in a terminal) or fails with choices
|
|
212
|
+
laburen link --org <id> # writes .laburen/link.json
|
|
213
|
+
laburen unlink # deletes .laburen/link.json
|
|
214
|
+
laburen me organizations list # same data as `orgs list`, raw
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
See [auth-and-organizations.md](auth-and-organizations.md).
|