Manage the full Managed Agent lifecycle from the terminal: deploy Agents as infrastructure-as-code, initialize and build local projects, manage sessions and state, and directly operate Agents, Environments, Skills, Vaults, Deployments, Sessions, Files, Memory Stores, and Webhooks in AgentStudio. Query, create, and run resources by resource type. The create commands for Agent, Environment, Skill, Vault, Deployment, and Memory Store can generate resource declarations from parameters; add --yes to confirm, write them to the configuration, and create the resources.
Managed Agent capabilities are currently available only to China site (aliyun.com) accounts.
Append --help to any command for full parameter details, e.g. bl managed-agent apply --help. Command details on this page are verified against bl 2.5.1.
bl managed-agent skill-list is equivalent to bl managed-agent skill list; bl managed-agent session events is equivalent to bl managed-agent session event list. The aliases exist for backward compatibility with older scripts.
Global flags
The following flags are available to all bl managed-agent subcommands and are not repeated in the command sections. Commands that require API Key authentication also support --api-key and --base-url.
| Parameter | Type | Description |
|---|
--output <format> | string | Output format: text, json |
--timeout <seconds> | number | Request timeout (seconds) |
--quiet | switch | Suppress non-essential output |
--verbose | switch | Print HTTP request and response details |
--dry-run | switch | Dry run mode |
--config <name> | string | Use a config profile for this command |
--help | switch | Show help |
--api-key <key> | string | API Key; credentials resolve in the order --api-key > DASHSCOPE_API_KEY env var > bl auth login (active config profile) |
--base-url <url> | string | API Base URL |
Lifecycle
bl managed-agent init
Create an agents.yaml template. No authentication required.
Usage
bl managed-agent init [--agent-name <name>] [--file <path>] [--force]
| Parameter | Type | Required | Description |
|---|
--agent-name <name> | string | no | Name of the first agent (default: assistant) |
--file <path> | string | no | Output config path (default: agents.yaml) |
--force | switch | no | Overwrite an existing config file |
bl managed-agent init --agent-name assistant
bl managed-agent validate
Validate an agents.yaml configuration (offline). No authentication required.
Usage
bl managed-agent validate [--file <path>]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
bl managed-agent validate --file agents.yaml
bl managed-agent plan
Show what changes would be applied to agent infrastructure. Requires API Key authentication.
Usage
bl managed-agent plan [--file <path>] [--no-refresh] [--refresh-only]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--no-refresh | switch | no | Skip refreshing state from remote before planning |
--refresh-only | switch | no | Refresh state and show drift without planning remote mutations |
bl managed-agent plan --no-refresh
- --no-refresh and --dry-run plan offline from local config and state: no remote requests, no state writes, provider keys are not checked.
bl managed-agent apply
Apply planned changes to create/update/delete agent resources. Requires API Key authentication.
Usage
bl managed-agent apply [--file <path>] [--concurrency <n>]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--no-refresh | switch | no | Skip refreshing state from remote before planning |
--concurrency <n> | number | no | Max independent resources to apply in parallel (default 6, max 10) |
--yes | switch | no | Confirm this high-risk operation |
This applies the current plan and may create, update, or delete remote managed Agent resources.
bl managed-agent apply --yes
bl managed-agent destroy
Destroy all managed agent resources tracked in state. Requires API Key authentication.
Usage
bl managed-agent destroy [--file <path>] [--cascade]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--cascade | switch | no | Auto-delete dependent resources (e.g. sessions referencing an environment) |
--yes | switch | no | Confirm this high-risk operation |
This deletes every managed Agent resource tracked in state; --cascade may also delete dependent resources.
bl managed-agent destroy --yes
Local resource state
bl managed-agent state list
List resources tracked in agents state. No authentication required.
Usage
bl managed-agent state list [--file <path>]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
bl managed-agent state list --file agents.yaml
bl managed-agent state show
Show details of a resource in agents state. No authentication required.
Usage
bl managed-agent state show --address <provider.type.name> [--file <path>]
| Parameter | Type | Required | Description |
|---|
--address <provider.type.name> | string | yes | Resource state address |
--file <path> | string | no | Config file path (default: agents.yaml) |
bl managed-agent state show --address bailian.agent.assistant
bl managed-agent state import
Import an existing remote resource into agents state. Requires API Key authentication.
Usage
bl managed-agent state import --address <bailian.type.name> --remote-id <id> [--resource-version <n>] [--file <path>]
| Parameter | Type | Required | Description |
|---|
--address <bailian.type.name> | string | yes | Resource state address |
--remote-id <id> | string | yes | Existing remote resource ID to import |
--resource-version <n> | number | no | Resource version (for versioned resources like agents) |
--file <path> | string | no | Config file path (default: agents.yaml) |
bl managed-agent state import --address bailian.agent.assistant --remote-id agent-abc123
bl managed-agent state rm
Remove a resource from state without destroying it remotely. No authentication required.
Usage
bl managed-agent state rm --address <provider.type.name> [--file <path>]
| Parameter | Type | Required | Description |
|---|
--address <provider.type.name> | string | yes | Resource state address |
--file <path> | string | no | Config file path (default: agents.yaml) |
--yes | switch | no | Confirm this high-risk operation |
This removes the resource from local state without deleting it remotely, so this project will no longer track it.
bl managed-agent state rm --address bailian.agent.assistant --yes
Session preview
bl managed-agent playground
Launch a Session Preview for an agents.yaml Agent. Requires API Key authentication.
Usage
bl managed-agent playground [--file <path>] [--agent <id>] [--port <n>] [--no-open]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--port <n> | number | no | Local port (default: 4848) |
--no-open | switch | no | Do not open a browser automatically |
--agent <id> | string | no | Agent to preview (required when the project declares multiple Agents) |
bl managed-agent playground --agent assistant
- Session Preview requires Node.js 22+ and keeps using an agents.yaml source. Directory Workbench is available under managed-agent project workbench.
Project init
bl managed-agent project init
Create a directory project or convert the local agents.yaml. No authentication required.
Usage
bl managed-agent project init [--project <directory>]
| Parameter | Type | Required | Description |
|---|
--project <directory> | string | no | Directory project root (default: ./managed-agent under the current directory) |
bl managed-agent project init --project ./my-agent
- Without --project, creates a managed-agent/ subdirectory. Enter it before running other project commands. Use --project . to initialize in place or convert the current agents.yaml; existing project files are not overwritten.
- New projects include Skill, File, Vault, and Environment examples under each resource directory's _examples/. They are not referenced by agent.json and are excluded from Build/Publish. Copy an example outside _examples/ to enable it, then configure its Agent reference.
Project validation
bl managed-agent project validate
Validate a directory Agent project. No authentication required.
Usage
bl managed-agent project validate [--project <directory>]
| Parameter | Type | Required | Description |
|---|
--project <directory> | string | no | Directory project root (default: current directory) |
bl managed-agent project validate --project ./my-agent
Project build
bl managed-agent project build
Organize directory source and generate the immutable Publish Build. No authentication required.
Usage
bl managed-agent project build [--project <directory>]
| Parameter | Type | Required | Description |
|---|
--project <directory> | string | no | Directory project root (default: current directory) |
bl managed-agent project build --dry-run
- Build writes local project files without confirmation, including inferred resource associations and migration of plaintext Vault secrets into .env. Use --dry-run to preview without writing. Publish still requires explicit confirmation before remote changes.
Project publish
bl managed-agent project publish
Publish the current directory-project Build and record a version. Requires API Key authentication.
Usage
bl managed-agent project publish [--project <directory>] [--no-refresh] [--concurrency <n>]
| Parameter | Type | Required | Description |
|---|
--project <directory> | string | no | Directory project root (default: current directory) |
--no-refresh | switch | no | Skip remote refresh before planning |
--concurrency <n> | number | no | Maximum parallel resource operations |
--yes | switch | no | Confirm this high-risk operation |
This publishes the current directory-project Build and may create, update, or delete remote managed Agent resources.
bl managed-agent project publish --yes
Project workbench
bl managed-agent project workbench
Launch the directory project Workbench. Requires API Key authentication.
Usage
bl managed-agent project workbench [--project <directory>] [--port <n>] [--no-open]
| Parameter | Type | Required | Description |
|---|
--project <directory> | string | no | Directory project root (default: current directory) |
--port <n> | number | no | Local port (default: 4848) |
--no-open | switch | no | Do not open a browser |
bl managed-agent project workbench --project ./my-agent --no-open
Project versions
bl managed-agent project version list
List directory project versions. No authentication required.
Usage
bl managed-agent project version list [--project <directory>] [--limit <n>] [--cursor <cursor>]
| Parameter | Type | Required | Description |
|---|
--project <directory> | string | no | Directory project root (default: current directory) |
--limit <n> | number | no | Maximum versions to return |
--cursor <cursor> | string | no | Pagination cursor |
bl managed-agent project version list --limit 20 --output json
bl managed-agent project version enable
Enable directory project versions. No authentication required.
Usage
bl managed-agent project version enable [--project <directory>]
| Parameter | Type | Required | Description |
|---|
--project <directory> | string | no | Directory project root (default: current directory) |
bl managed-agent project version enable --project ./my-agent
bl managed-agent project version disable
Disable directory project versions. No authentication required.
Usage
bl managed-agent project version disable [--project <directory>]
| Parameter | Type | Required | Description |
|---|
--project <directory> | string | no | Directory project root (default: current directory) |
bl managed-agent project version disable --project ./my-agent
bl managed-agent project version status
Show directory project version status. No authentication required.
Usage
bl managed-agent project version status [--project <directory>]
| Parameter | Type | Required | Description |
|---|
--project <directory> | string | no | Directory project root (default: current directory) |
bl managed-agent project version status --project ./my-agent --output json
bl managed-agent project version preview
Preview a directory project version. No authentication required.
Usage
bl managed-agent project version preview --version-id <full-version> [--project <directory>]
| Parameter | Type | Required | Description |
|---|
--project <directory> | string | no | Directory project root (default: current directory) |
--version-id <full-version> | string | yes | Full project version ID |
bl managed-agent project version preview --version-id <full-version>
bl managed-agent project version restore
Restore a version to the project working directory. No authentication required.
Usage
bl managed-agent project version restore --version-id <full-version> [--project <directory>]
| Parameter | Type | Required | Description |
|---|
--project <directory> | string | no | Directory project root (default: current directory) |
--version-id <full-version> | string | yes | Full project version ID |
--yes | switch | no | Confirm this high-risk operation |
This restores the full directory source to the working tree. Version history and remote State will not move.
bl managed-agent project version restore --version-id <full-version>
Agent
bl managed-agent agent create
Declare and create one Managed Agent through an isolated YAML apply. Requires API Key authentication.
Usage
bl managed-agent agent create --name <name> --model <model> --instructions <text|path> [--description <text>] [--skill <id>...] [--type custom|official] [--skill-dir <path>...] [--tool <name>...] [--environment <yaml-key>] [--vault <yaml-key>] [--mcp <server-code>...] [--file <path>] [--yes]
| Parameter | Type | Required | Description |
|---|
--name <name> | string | yes | Remote Agent display name; the YAML key is generated automatically |
--model <model> | string | yes | Model ID |
--instructions <text|path> | string | yes | Inline instructions or a ./, ../, or absolute file path |
--description <text> | string | no | Agent description |
--skill <id> | array | no | Existing remote Skill ID (repeatable) |
--skill-dir <path> | array | no | Local Skill directory or ZIP to declare, upload, and attach through the same scoped create (repeatable) |
--type <custom|official> | string | no | Type applied to every --skill value (default: custom) |
--tool <name> | array | no | Builtin tool name (repeatable) |
--environment <yaml-key> | string | no | Existing Environment key from agents.yaml, used as the default environment for Sessions and Deployments |
--vault <yaml-key> | string | no | Existing Vault key from agents.yaml, used as the default vault for Sessions and Deployments |
--mcp <server-code> | array | no | MCP market server code; all of its tools are enabled (repeatable) |
--file <path> | string | no | Config file path (default: agents.yaml) |
--yes | switch | no | Write YAML and run the scoped remote create |
bl managed-agent agent create --name assistant --model qwen3.8-max --instructions "You are helpful."
- Without --yes, previews the generated YAML key and scoped plan. --dry-run stays offline. Unrelated resources are not refreshed or drift-checked.
- --skill writes an external Skill reference directly into the Agent declaration. --type defaults to custom; use --type official for platform Skills. These Skills are not managed through the top-level skills map.
- --skill-dir accepts a local Skill directory or ZIP, writes it as a top-level custom Skill declaration, and writes its generated YAML key into the Agent skills list. Skill and Agent are created together in dependency order. --type applies only to --skill IDs.
- --environment and --vault write existing YAML keys into the Agent declaration as default runtime bindings for Sessions and Deployments; they are not sent to the Agent API. The referenced Environment and Vault must already be created.
- --mcp accepts MCP market server codes (see
bl mcp list) and enables all of their tools. To toggle individual tools, edit tools.mcp in YAML and run a full apply.
bl managed-agent agent list
List Managed Agents. Requires API Key authentication.
Usage
bl managed-agent agent list [--limit <n>] [--page <cursor>] [--all] [--include-archived] [--file <path>]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--limit <n> | number | no | Page size (1-100) |
--page <cursor> | string | no | Opaque page cursor returned by a previous request |
--all | switch | no | Fetch all pages by following opaque cursors |
--include-archived | switch | no | Include archived resources |
bl managed-agent agent list --limit 50
bl managed-agent agent get
Get a Managed Agent. Requires API Key authentication.
Usage
bl managed-agent agent get --agent-id <id> [--agent-version <n>] [--file <path>]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--agent-id <id> | string | yes | Agent ID |
--agent-version <n> | number | no | Specific agent version |
bl managed-agent agent get --agent-id agent_abc
bl managed-agent agent search
Search Managed Agents. Requires API Key authentication.
Usage
bl managed-agent agent search --query <text> [--limit <n>] [--page-limit <n>] [--include-archived]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--limit <n> | number | no | Page size (1-100) |
--query <text> | string | yes | Case-insensitive text to find in IDs, names, and descriptions |
--page-limit <n> | number | no | Maximum pages to scan for client-side search (default: 10) |
--include-archived | switch | no | Include archived resources |
bl managed-agent agent search --query assistant
bl managed-agent agent versions
List Managed Agent versions. Requires API Key authentication.
Usage
bl managed-agent agent versions --agent-id <id> [--limit <n>] [--page <cursor>] [--all]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--limit <n> | number | no | Page size (1-100) |
--page <cursor> | string | no | Opaque page cursor returned by a previous request |
--all | switch | no | Fetch all pages by following opaque cursors |
--agent-id <id> | string | yes | Agent ID |
bl managed-agent agent versions --agent-id agent_abc
Environment
bl managed-agent environment list
List Managed Agent environments. Requires API Key authentication.
Usage
bl managed-agent environment list [--limit <n>] [--page <cursor>] [--all] [--include-archived]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--limit <n> | number | no | Page size (1-100) |
--page <cursor> | string | no | Opaque page cursor returned by a previous request |
--all | switch | no | Fetch all pages by following opaque cursors |
--include-archived | switch | no | Include archived resources |
bl managed-agent environment list --all --output json
bl managed-agent environment get
Get a Managed Agent environment. Requires API Key authentication.
Usage
bl managed-agent environment get --environment-id <id>
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--environment-id <id> | string | yes | Environment ID |
bl managed-agent environment get --environment-id env_abc
bl managed-agent environment search
Search Managed Agent environments. Requires API Key authentication.
Usage
bl managed-agent environment search --query <text> [--limit <n>] [--page-limit <n>] [--include-archived]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--limit <n> | number | no | Page size (1-100) |
--query <text> | string | yes | Case-insensitive text to find in IDs, names, and descriptions |
--page-limit <n> | number | no | Maximum pages to scan for client-side search (default: 10) |
--include-archived | switch | no | Include archived resources |
bl managed-agent environment search --query sandbox
bl managed-agent environment create
Declare and create one Managed Agent Environment through a scoped YAML apply. Requires API Key authentication.
Usage
bl managed-agent environment create --name <name> [--description <text>] [--metadata <key=value>...] [--apt <package>...] [--pip <package>...] [--npm <package>...] [--cargo <package>...] [--gem <package>...] [--go <package>...] [--file <path>] [--yes]
| Parameter | Type | Required | Description |
|---|
--name <name> | string | yes | Remote Environment display name; the YAML key is generated automatically |
--description <text> | string | no | Environment description |
--metadata <key=value> | array | no | Metadata entry (repeatable) |
--apt <package> | array | no | APT package (repeatable) |
--pip <package> | array | no | pip package (repeatable) |
--npm <package> | array | no | npm package (repeatable) |
--cargo <package> | array | no | Cargo package (repeatable) |
--gem <package> | array | no | Ruby gem package (repeatable) |
--go <package> | array | no | Go package (repeatable) |
--file <path> | string | no | Config file path (default: agents.yaml) |
--yes | switch | no | Write YAML and run the scoped remote create |
bl managed-agent environment create --name Development
- Creates a cloud Environment with unrestricted networking. Without --yes, only previews the generated YAML key and scoped plan.
Skill
bl managed-agent skill list
List Managed Agent skills. Requires API Key authentication.
Usage
bl managed-agent skill list [--source custom|official|all] [--limit <n>] [--page <cursor>] [--all]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--limit <n> | number | no | Page size (1-100) |
--page <cursor> | string | no | Opaque page cursor returned by a previous request |
--all | switch | no | Fetch all pages by following opaque cursors |
--source <source> | string | no | Skill catalog: custom (default), official, or all |
bl managed-agent skill list --source official
- --source all combines one page from each catalog, or every page with --all; it does not accept --page.
bl managed-agent skill get
Get a Managed Agent skill. Requires API Key authentication.
Usage
bl managed-agent skill get --skill-id <id>
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--skill-id <id> | string | yes | Skill ID |
bl managed-agent skill get --skill-id skill_abc
bl managed-agent skill search
Search Managed Agent skills. Requires API Key authentication.
Usage
bl managed-agent skill search --query <text> [--source custom|official|all] [--limit <n>] [--page-limit <n>]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--limit <n> | number | no | Page size (1-100) |
--query <text> | string | yes | Case-insensitive text to find in IDs, names, and descriptions |
--page-limit <n> | number | no | Maximum pages to scan for client-side search (default: 10) |
--source <source> | string | no | Skill catalog: custom (default), official, or all |
bl managed-agent skill search --query browser --source official
bl managed-agent skill create
Declare and create one custom Managed Agent Skill from a local source. Requires API Key authentication.
Usage
bl managed-agent skill create --source <directory|zip|SKILL.md> [--file <path>] [--yes]
| Parameter | Type | Required | Description |
|---|
--source <directory|zip|SKILL.md> | string | yes | Local Skill directory, ZIP archive, or single SKILL.md |
--file <path> | string | no | Config file path (default: agents.yaml) |
--yes | switch | no | Write YAML and upload the Skill through the scoped create |
bl managed-agent skill create --source ./skills/code-review
- The YAML key is derived from SKILL.md frontmatter name. Remote URLs remain available through handwritten YAML plus full apply.
bl managed-agent skill versions
List Managed Agent skill versions. Requires API Key authentication.
Usage
bl managed-agent skill versions --skill-id <id> [--limit <n>] [--page <cursor>] [--all]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--skill-id <id> | string | yes | Skill ID |
--limit <n> | number | no | Page size (1-100) |
--page <cursor> | string | no | Opaque page cursor returned by a previous request |
--all | switch | no | Fetch all pages by following opaque cursors |
bl managed-agent skill versions --skill-id skill_abc
bl managed-agent skill download
Download a Managed Agent skill version. Requires API Key authentication.
Usage
bl managed-agent skill download --skill-id <id> --skill-version <version> --output-file <path> [--force]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--skill-id <id> | string | yes | Skill ID |
--skill-version <version> | string | yes | Skill version |
--output-file <path> | string | yes | Destination ZIP path |
--force | switch | no | Overwrite an existing output file |
bl managed-agent skill download --skill-id skill_abc --skill-version 3 --output-file ./skill.zip
Vault
bl managed-agent vault list
List Managed Agent vaults. Requires API Key authentication.
Usage
bl managed-agent vault list [--limit <n>] [--page <cursor>] [--all] [--include-archived]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--limit <n> | number | no | Page size (1-100) |
--page <cursor> | string | no | Opaque page cursor returned by a previous request |
--all | switch | no | Fetch all pages by following opaque cursors |
--include-archived | switch | no | Include archived resources |
bl managed-agent vault list --all --output json
bl managed-agent vault get
Get a Managed Agent vault. Requires API Key authentication.
Usage
bl managed-agent vault get --vault-id <id>
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--vault-id <id> | string | yes | Vault ID |
bl managed-agent vault get --vault-id vault_abc
bl managed-agent vault search
Search Managed Agent vaults. Requires API Key authentication.
Usage
bl managed-agent vault search --query <text> [--limit <n>] [--page-limit <n>] [--include-archived]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--limit <n> | number | no | Page size (1-100) |
--query <text> | string | yes | Case-insensitive text to find in IDs, names, and descriptions |
--page-limit <n> | number | no | Maximum pages to scan for client-side search (default: 10) |
--include-archived | switch | no | Include archived resources |
bl managed-agent vault search --query github
bl managed-agent vault create
Declare and create one empty Managed Agent Vault through a scoped YAML apply. Requires API Key authentication.
Usage
bl managed-agent vault create --name <name> [--metadata <key=value>...] [--file <path>] [--yes]
| Parameter | Type | Required | Description |
|---|
--name <name> | string | yes | Remote Vault display name; the YAML key is generated automatically |
--metadata <key=value> | array | no | Metadata entry (repeatable) |
--file <path> | string | no | Config file path (default: agents.yaml) |
--yes | switch | no | Write YAML and run the scoped remote create |
bl managed-agent vault create --name Production
- Creates an empty Vault. Add secrets later with
vault credential create.
bl managed-agent vault credential create
Append and create one environment-variable Credential in a tracked Vault. Requires API Key authentication.
Usage
bl managed-agent vault credential create --vault <yaml-key> --name <name> --secret-name <name> --secret-env <env-name> [--metadata <key=value>...] [--file <path>] [--yes]
| Parameter | Type | Required | Description |
|---|
--vault <yaml-key> | string | yes | Existing tracked Vault key from agents.yaml |
--name <name> | string | yes | Credential display name |
--secret-name <name> | string | yes | Environment variable name exposed to the Agent |
--secret-env <env-name> | string | yes | Local environment variable containing the secret value |
--metadata <key=value> | array | no | Metadata entry (repeatable) |
--file <path> | string | no | Config file path (default: agents.yaml) |
--yes | switch | no | Write YAML and create the remote Credential |
bl managed-agent vault credential create --vault production --name api-token --secret-name API_TOKEN --secret-env PROD_API_TOKEN
- --secret-env is an environment variable name, not the secret itself. The CLI auto-loads the nearest .env from the current directory upward; shell exports and CI secret injection also work.
- YAML stores only ${ENV_NAME}. Never commit .env; subsequent full apply runs must provide the same environment variable.
Memory Store
Memory Store lifecycle is managed by agents.yaml and State; memory contents are managed through API commands. Read and write commands use a workspace-specific endpoint; when no base URL is configured, they require --workspace-id, which can also come from BAILIAN_WORKSPACE_ID or the workspace_id config field.
bl managed-agent memory-store create
Declare and create a Memory Store through a scoped YAML apply. Requires API Key authentication.
Usage
bl managed-agent memory-store create --name <name> [--description <text>] [--metadata <key=value>...] [--entry <json|@path>...] [--file <path>] [--yes]
| Parameter | Type | Required | Description |
|---|
--name <name> | string | yes | Memory Store display name; generates a YAML key |
--description <text> | string | no | Store description (default: empty) |
--metadata <key=value> | array | no | Metadata entry (repeatable) |
--entry <json|@path> | array | no | Initial entry JSON with key and content (repeatable) |
--file <path> | string | no | Config file path (default: agents.yaml) |
--yes | switch | no | Write YAML and run the scoped remote create |
bl managed-agent memory-store create --name Notes --entry '{"key":"notes.md","content":"Initial notes"}' --dry-run
- Without --yes, this command only previews. --dry-run is fully offline.
- Store lifecycle is managed by agents.yaml.
--entry initializes new stores; existing content is preserved unless entries_mode: sync is explicitly configured.
bl managed-agent memory-store list
List Memory Stores. Requires API Key authentication.
Usage
bl managed-agent memory-store list [--workspace-id <id>] [--limit <n>] [--page <cursor>] [--include-archived]
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID; optional when a base URL is configured |
--limit <n> | number | no | Page size (1-100) |
--page <cursor> | string | no | Opaque next_page cursor from the previous response |
--include-archived | switch | no | Include archived stores |
bl managed-agent memory-store list --workspace-id ws-example --output json
- Reading stores and their contents does not require agents.yaml or State.
- Remote operations use
--store-id; pass the response next_page back to --page unchanged.
bl managed-agent memory-store get
Get a Memory Store. Requires API Key authentication.
Usage
bl managed-agent memory-store get --store-id <id> [--workspace-id <id>]
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID; optional when a base URL is configured |
--store-id <id> | string | yes | Remote Memory Store ID |
bl managed-agent memory-store get --workspace-id ws-example --store-id memstore_example
bl managed-agent memory-store memories create
Create a memory file. Requires API Key authentication.
Usage
bl managed-agent memory-store memories create --store-id <id> --path <path> (--content <text> | --content-file <path>)
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID; optional when a base URL is configured |
--store-id <id> | string | yes | Remote Memory Store ID |
--path <path> | string | yes | Memory file path |
--content <text> | string | no | Memory content; an empty string is allowed |
--content-file <path> | string | no | Read UTF-8 content from a local file; exclusive with --content |
--yes | switch | no | Confirm this high-risk operation |
This changes persistent memory content. Review the request with --dry-run before adding --yes.
bl managed-agent memory-store memories create --store-id memstore_example --path notes.md --content-file ./notes.md --dry-run
bl managed-agent memory-store memories list
List memory files and prefixes. Requires API Key authentication.
Usage
bl managed-agent memory-store memories list --store-id <id> [--page <cursor>] [--limit <n>] [--path-prefix <prefix>] [--depth <n>] [--view <basic|full>]
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID; optional when a base URL is configured |
--store-id <id> | string | yes | Remote Memory Store ID |
--limit <n> | number | no | Page size (1-20) |
--page <cursor> | string | no | Opaque next_page cursor from the previous response |
--view <basic|full> | string | no | Response view: basic or full |
--path-prefix <prefix> | string | no | Filter by memory path prefix |
--depth <n> | number | no | Directory listing depth |
bl managed-agent memory-store memories list --store-id memstore_example --path-prefix /notes/ --view full
bl managed-agent memory-store memories get
Get a memory file. Requires API Key authentication.
Usage
bl managed-agent memory-store memories get --store-id <id> --memory-id <id>
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID; optional when a base URL is configured |
--store-id <id> | string | yes | Remote Memory Store ID |
--memory-id <id> | string | yes | Remote Memory ID |
bl managed-agent memory-store memories get --store-id memstore_example --memory-id mem_example
bl managed-agent memory-store memories update
Update memory content with an optional SHA-256 precondition. Requires API Key authentication.
Usage
bl managed-agent memory-store memories update --store-id <id> --memory-id <id> (--content <text> | --content-file <path>) [--expected-content-sha256 <sha256>]
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID; optional when a base URL is configured |
--store-id <id> | string | yes | Remote Memory Store ID |
--memory-id <id> | string | yes | Remote Memory ID |
--content <text> | string | no | Memory content; an empty string is allowed |
--content-file <path> | string | no | Read UTF-8 content from a local file; exclusive with --content |
--expected-content-sha256 <sha256> | string | no | Expected current SHA-256; reject a concurrent content change |
--yes | switch | no | Confirm this high-risk operation |
This changes persistent memory content. Review the request with --dry-run before adding --yes.
bl managed-agent memory-store memories update --store-id memstore_example --memory-id mem_example --content-file ./notes.md --expected-content-sha256 <sha256> --dry-run
bl managed-agent memory-store memories delete
Delete a memory file. Requires API Key authentication.
Usage
bl managed-agent memory-store memories delete --store-id <id> --memory-id <id>
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID; optional when a base URL is configured |
--store-id <id> | string | yes | Remote Memory Store ID |
--memory-id <id> | string | yes | Remote Memory ID |
--yes | switch | no | Confirm this high-risk operation |
This changes persistent memory content. Review the request with --dry-run before adding --yes.
bl managed-agent memory-store memories delete --store-id memstore_example --memory-id mem_example --dry-run
bl managed-agent memory-store versions list
List Memory Store versions. Requires API Key authentication.
Usage
bl managed-agent memory-store versions list --store-id <id> [--memory-id <id>] [--operation <created|modified|deleted>] [--created-at-gte <timestamp>] [--created-at-lte <timestamp>] [--page <cursor>] [--limit <n>] [--view <basic|full>]
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID; optional when a base URL is configured |
--store-id <id> | string | yes | Remote Memory Store ID |
--memory-id <id> | string | no | Filter by Memory ID |
--operation <created|modified|deleted> | string | no | Filter by version operation |
--created-at-gte <timestamp> | string | no | Inclusive creation timestamp lower bound |
--created-at-lte <timestamp> | string | no | Inclusive creation timestamp upper bound |
--page <cursor> | string | no | Opaque next_page cursor from the previous response |
--limit <n> | number | no | Page size (1-100) |
--view <basic|full> | string | no | Response view: basic or full |
bl managed-agent memory-store versions list --store-id memstore_example --operation modified --view full
bl managed-agent memory-store versions get
Get a memory version. Requires API Key authentication.
Usage
bl managed-agent memory-store versions get --store-id <id> --version-id <id>
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID; optional when a base URL is configured |
--store-id <id> | string | yes | Remote Memory Store ID |
--version-id <id> | string | yes | Remote Memory Version ID |
bl managed-agent memory-store versions get --store-id memstore_example --version-id memver_example
bl managed-agent memory-store versions redact
Permanently redact a memory version's content. Requires API Key authentication.
Usage
bl managed-agent memory-store versions redact --store-id <id> --version-id <id>
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID; optional when a base URL is configured |
--store-id <id> | string | yes | Remote Memory Store ID |
--version-id <id> | string | yes | Remote Memory Version ID |
--yes | switch | no | Confirm this high-risk operation |
This permanently redacts the selected version's content and cannot be undone.
bl managed-agent memory-store versions redact --store-id memstore_example --version-id memver_example --dry-run
Deployment
bl managed-agent deployment list
List Managed Agent deployments. Requires API Key authentication.
Usage
bl managed-agent deployment list [--agent-id <id>] [--status active|paused] [--limit <n>] [--page <cursor>] [--all]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--limit <n> | number | no | Page size (1-100) |
--page <cursor> | string | no | Opaque page cursor returned by a previous request |
--all | switch | no | Fetch all pages by following opaque cursors |
--agent-id <id> | string | no | Filter by agent ID |
--status <status> | string | no | Filter by deployment status |
--include-archived | switch | no | Include archived resources |
--created-at-gte <timestamp> | string | no | Created at or after this timestamp |
--created-at-lte <timestamp> | string | no | Created at or before this timestamp |
bl managed-agent deployment list --status active --all --output json
bl managed-agent deployment get
Get a Managed Agent deployment. Requires API Key authentication.
Usage
bl managed-agent deployment get --deployment-id <id>
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--deployment-id <id> | string | yes | Deployment ID |
bl managed-agent deployment get --deployment-id dep_abc
bl managed-agent deployment search
Search Managed Agent deployments. Requires API Key authentication.
Usage
bl managed-agent deployment search --query <text> [--limit <n>] [--page <cursor>] [--all]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--limit <n> | number | no | Page size (1-100) |
--page <cursor> | string | no | Opaque page cursor returned by a previous request |
--all | switch | no | Fetch all pages by following opaque cursors |
--query <text> | string | yes | Case-insensitive text to find in IDs, names, and descriptions |
--agent-id <id> | string | no | Filter by agent ID |
--status <status> | string | no | Filter by deployment status |
--include-archived | switch | no | Include archived resources |
--created-at-gte <timestamp> | string | no | Created at or after this timestamp |
--created-at-lte <timestamp> | string | no | Created at or before this timestamp |
bl managed-agent deployment search --query report
- Deployment search maps --query to the provider's server-side keyword parameter.
bl managed-agent deployment create
Declare and create one Managed Agent Deployment through a scoped YAML apply. Requires API Key authentication.
Usage
bl managed-agent deployment create --name <name> --agent <yaml-key> (--message <text>... | --event <json|@path>...) [--agent-version <number>] [--environment <yaml-key>] [--environment_variables <KEY=VALUE>...] [--vault <yaml-key>...] [--resource <json|@path>...] [--schedule <cron> --timezone <timezone>] [--description <text>] [--metadata <key=value>...] [--file <path>] [--yes]
| Parameter | Type | Required | Description |
|---|
--name <name> | string | yes | Remote Deployment display name; the YAML key is generated automatically |
--agent <yaml-key> | string | yes | Existing Agent key from agents.yaml |
--agent-version <number> | number | no | Agent version |
--environment <yaml-key> | string | no | Existing Environment key from agents.yaml |
--environment_variables <KEY=VALUE> | array | no | Runtime environment variable; repeat for multiple values (last value wins) |
--vault <yaml-key> | array | no | Existing Vault key from agents.yaml (repeatable) |
--message <text> | array | no | Initial user message (repeatable) |
--event <json|@path> | array | no | Initial user.message or system.message JSON (repeatable) |
--resource <json|@path> | array | no | File Resource JSON with source or file_id (repeatable) |
--schedule <cron> | string | no | Five-field cron expression |
--timezone <timezone> | string | no | IANA schedule timezone |
--description <text> | string | no | Deployment description |
--metadata <key=value> | array | no | Metadata entry (repeatable) |
--file <path> | string | no | Config file path (default: agents.yaml) |
--yes | switch | no | Write YAML and run the scoped remote create |
bl managed-agent deployment create --name Daily --agent assistant --message "Generate the report"
- Initial Events must contain 1-50 user.message/system.message entries. --resource accepts only File Resources in this release.
- Use either repeatable --message values or repeatable --event values; the two input forms cannot be mixed.
--environment_variables values are written to the Deployment YAML declaration and managed by later apply runs. Remove the field or pass {} to clear them. YAML stores these values; do not put real secrets in them.
bl managed-agent deployment run
Run a Managed Agent deployment now. Requires API Key authentication.
Usage
bl managed-agent deployment run (--deployment <name> | --deployment-id <id>)
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--deployment <name> | string | no | Logical deployment name in agents.yaml/state |
--deployment-id <id> | string | no | Direct deployment ID |
--yes | switch | no | Confirm this high-risk operation |
This immediately starts a run for the specified Managed Agent deployment and may incur usage or trigger configured actions.
bl managed-agent deployment run --deployment daily-report --dry-run
bl managed-agent deployment pause
Pause a Managed Agent deployment. Requires API Key authentication.
Usage
bl managed-agent deployment pause (--deployment <name> | --deployment-id <id>)
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--deployment <name> | string | no | Logical deployment name in agents.yaml/state |
--deployment-id <id> | string | no | Direct deployment ID |
--yes | switch | no | Confirm this high-risk operation |
bl managed-agent deployment pause --deployment daily-report --dry-run
bl managed-agent deployment unpause
Unpause a Managed Agent deployment. Requires API Key authentication.
Usage
bl managed-agent deployment unpause (--deployment <name> | --deployment-id <id>)
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--deployment <name> | string | no | Logical deployment name in agents.yaml/state |
--deployment-id <id> | string | no | Direct deployment ID |
--yes | switch | no | Confirm this high-risk operation |
bl managed-agent deployment unpause --deployment daily-report --dry-run
bl managed-agent deployment runs list
List runs for a Managed Agent deployment. Requires API Key authentication.
Usage
bl managed-agent deployment runs list --deployment-id <id> [--limit <n>] [--page <cursor>] [--all]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--deployment-id <id> | string | yes | Deployment ID |
--limit <n> | number | no | Page size (1-100) |
--page <cursor> | string | no | Opaque page cursor returned by a previous request |
--all | switch | no | Fetch all pages by following opaque cursors |
bl managed-agent deployment runs list --deployment-id dep_abc
bl managed-agent deployment runs get
Get a Managed Agent deployment run. Requires API Key authentication.
Usage
bl managed-agent deployment runs get --run-id <id>
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--run-id <id> | string | yes | Deployment run ID |
bl managed-agent deployment runs get --run-id run_abc
Session
bl managed-agent session create
Create a new session for an agent. Requires API Key authentication.
Usage
bl managed-agent session create [--agent <name>] [--environment <name>] [--title <title>] [--environment_variables <KEY=VALUE>...] [--memory-stores <names>] [--resource <json|@path>...] [--file <path>]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--agent <name> | string | no | Agent name (auto-detected when only one agent is configured) |
--environment <name> | string | no | Override agent's declared environment |
--vault <name> | string | no | Override agent's declared vault |
--memory-stores <names> | string | no | Override agent's memory stores (comma-separated) |
--environment_variables <KEY=VALUE> | array | no | Runtime environment variable; repeat for multiple values (last value wins) |
--resource <json|@path> | array | no | Session resource JSON (repeatable); memory_store uses a YAML key plus access and instructions |
--title <title> | string | no | Session title |
bl managed-agent session create --agent assistant
--resource mounts a Memory Store into the Session. For example, --resource '{"type":"memory_store","memory_store":"notes","access":"read_only"}'.
bl managed-agent session run
Create a session, send a message, and stream the response. Requires API Key authentication.
Usage
bl managed-agent session run --prompt <text> [--agent <name>] [--no-stream] [--environment_variables <KEY=VALUE>...] [--memory-stores <names>] [--resource <json|@path>...] [--file <path>]
| Parameter | Type | Required | Description |
|---|
--prompt <text> | string | yes | Prompt to send |
--file <path> | string | no | Config file path (default: agents.yaml) |
--agent <name> | string | no | Agent name (auto-detected when only one agent is configured) |
--environment <name> | string | no | Override agent's declared environment |
--vault <name> | string | no | Override agent's declared vault |
--memory-stores <names> | string | no | Override agent's memory stores (comma-separated) |
--environment_variables <KEY=VALUE> | array | no | Runtime environment variable; repeat for multiple values (last value wins) |
--resource <json|@path> | array | no | Session resource JSON (repeatable); memory_store uses a YAML key plus access and instructions |
--title <title> | string | no | Session title |
--no-stream | switch | no | Use polling instead of SSE streaming |
bl managed-agent session run --prompt "hello"
- --output json emits one envelope: { session_id, provider, agent, events } — read session_id to chain
session send/get/events/delete.
bl managed-agent session send
Send a message to an existing session and stream the response. Requires API Key authentication.
Usage
bl managed-agent session send --session-id <id> --message <text> [--no-stream] [--file <path>]
| Parameter | Type | Required | Description |
|---|
--session-id <id> | string | yes | Session ID |
--message <text> | string | yes | Message to send |
--file <path> | string | no | Config file path (default: agents.yaml) |
--no-stream | switch | no | Use polling instead of SSE streaming |
bl managed-agent session send --session-id sess_abc123 --message "continue"
bl managed-agent session list
List sessions from the provider. Requires API Key authentication.
Usage
bl managed-agent session list [--agent <name>] [--statuses <statuses>] [--limit <n>] [--page <cursor>] [--all]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--agent <name> | string | no | Filter by agent name |
--all | switch | no | Fetch all pages by following the cursor |
--limit <n> | number | no | Page size (1-100) |
--page <cursor> | string | no | Opaque page cursor returned by a previous request |
--statuses <statuses> | string | no | Comma-separated session statuses |
--created-at-gte <timestamp> | string | no | Created at or after this RFC 3339 timestamp |
--created-at-lte <timestamp> | string | no | Created at or before this RFC 3339 timestamp |
bl managed-agent session list --agent assistant
bl managed-agent session get
Get details of a session. Requires API Key authentication.
Usage
bl managed-agent session get --session-id <id> [--file <path>]
| Parameter | Type | Required | Description |
|---|
--session-id <id> | string | yes | Session ID |
--file <path> | string | no | Config file path (default: agents.yaml) |
bl managed-agent session get --session-id sess_abc123
bl managed-agent session search
Search Managed Agent sessions. Requires API Key authentication.
Usage
bl managed-agent session search --query <text> [--agent <name>] [--statuses <statuses>] [--limit <n>] [--page-limit <n>]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--limit <n> | number | no | Page size (1-100) |
--query <text> | string | yes | Case-insensitive text to find in IDs, names, and descriptions |
--page-limit <n> | number | no | Maximum pages to scan for client-side search (default: 10) |
--agent <name> | string | no | Filter by configured agent name |
--statuses <statuses> | string | no | Comma-separated session statuses |
--created-at-gte <timestamp> | string | no | Created at or after this timestamp |
--created-at-lte <timestamp> | string | no | Created at or before this timestamp |
bl managed-agent session search --query debug
bl managed-agent session update
Update a Managed Agent session. Requires API Key authentication.
Usage
bl managed-agent session update --session-id <id> [--title <title>] [--metadata <json|@path>]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--session-id <id> | string | yes | Session ID |
--title <title> | string | no | New session title |
--metadata <json|@path> | string | no | String-valued metadata JSON or @file |
bl managed-agent session update --session-id sess_abc --title 'investigation'
bl managed-agent session archive
Archive a Managed Agent session. Requires API Key authentication.
Usage
bl managed-agent session archive --session-id <id>
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--session-id <id> | string | yes | Session ID |
--yes | switch | no | Confirm this high-risk operation |
This archives the specified remote Managed Agent Session.
bl managed-agent session archive --session-id sess_abc --dry-run
bl managed-agent session delete
Delete a session. Requires API Key authentication.
Usage
bl managed-agent session delete --session-id <id> [--file <path>]
| Parameter | Type | Required | Description |
|---|
--session-id <id> | string | yes | Session ID |
--file <path> | string | no | Config file path (default: agents.yaml) |
--yes | switch | no | Confirm this high-risk operation |
This deletes the specified remote managed Agent Session.
bl managed-agent session delete --session-id sess_abc123 --yes
bl managed-agent session event list
List events for a Managed Agent session. Requires API Key authentication.
Usage
bl managed-agent session event list --session-id <id> [--types <types>] [--order asc|desc] [--limit <n>] [--page <cursor>] [--all]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--session-id <id> | string | yes | Session ID |
--limit <n> | number | no | Page size (1-100) |
--page <cursor> | string | no | Opaque page cursor returned by a previous request |
--all | switch | no | Fetch all pages by following opaque cursors |
--order <order> | string | no | Event order: asc or desc |
--types <types> | string | no | Comma-separated raw event types |
--created-at-gte <timestamp> | string | no | Created at or after this timestamp |
--created-at-lte <timestamp> | string | no | Created at or before this timestamp |
bl managed-agent session event list --session-id sess_abc
- --types is applied client-side to each page returned by the provider.
bl managed-agent session event send
Send raw events to a Managed Agent session. Requires API Key authentication.
Usage
bl managed-agent session event send --session-id <id> --event <json|@path>
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--session-id <id> | string | yes | Session ID |
--event <json|@path> | string | yes | Raw event object/array as JSON or @event.json |
bl managed-agent session event send --session-id sess_abc --event '{"type":"message","role":"user","content":[{"type":"text","text":"hello"}]}'
bl managed-agent session event stream
Stream events from a Managed Agent session. Requires API Key authentication.
Usage
bl managed-agent session event stream --session-id <id> [--after-id <event-id>]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--session-id <id> | string | yes | Session ID |
--after-id <event-id> | string | no | Resume after this event ID |
bl managed-agent session event stream --session-id sess_abc
- When the provider has no native event cursor, --after-id resumes through paginated history polling and event ID de-duplication.
bl managed-agent session debug
Aggregate session diagnostics. Requires API Key authentication.
Usage
bl managed-agent session debug --session-id <id>
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--session-id <id> | string | yes | Session ID |
bl managed-agent session debug --session-id sess_abc
bl managed-agent session export
Export session diagnostics as a ZIP. Requires API Key authentication.
Usage
bl managed-agent session export --session-id <id> --output-file <path> [--force]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--session-id <id> | string | yes | Session ID |
--output-file <path> | string | yes | Destination ZIP path |
--force | switch | no | Overwrite an existing output file |
bl managed-agent session export --session-id sess_abc --output-file ./session-debug.zip
- The ZIP contains metadata only; file bodies and credential-like values are excluded/redacted.
File
bl managed-agent file list
List Managed Agent files. Requires API Key authentication.
Usage
bl managed-agent file list [--scope-id <id>] [--limit <n>] [--page <cursor>] [--all]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--limit <n> | number | no | Page size (1-100) |
--page <cursor> | string | no | Opaque page cursor returned by a previous request |
--all | switch | no | Fetch all pages by following opaque cursors |
--scope-id <id> | string | no | Filter by scope ID |
bl managed-agent file list --scope-id sess_abc --all --output json
bl managed-agent file get
Get Managed Agent file metadata. Requires API Key authentication.
Usage
bl managed-agent file get --file-id <id>
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--file-id <id> | string | yes | Remote file ID |
bl managed-agent file get --file-id file_abc
bl managed-agent file search
Search Managed Agent files. Requires API Key authentication.
Usage
bl managed-agent file search --query <text> [--scope-id <id>] [--limit <n>] [--page-limit <n>]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--limit <n> | number | no | Page size (1-100) |
--query <text> | string | yes | Case-insensitive text to find in IDs, names, and descriptions |
--page-limit <n> | number | no | Maximum pages to scan for client-side search (default: 10) |
--scope-id <id> | string | no | Filter by scope ID |
bl managed-agent file search --query report
bl managed-agent file upload
Upload a Managed Agent file. Requires API Key authentication.
Usage
bl managed-agent file upload --path <path> [--filename <name>] [--mime-type <type>]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--path <path> | string | yes | Local file path |
--filename <name> | string | no | Remote filename override |
--mime-type <type> | string | no | MIME type override |
bl managed-agent file upload --path ./report.pdf
bl managed-agent file download
Download Managed Agent file content. Requires API Key authentication.
Usage
bl managed-agent file download --file-id <id> --output-file <path> [--force]
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--file-id <id> | string | yes | Remote file ID |
--output-file <path> | string | yes | Destination path |
--force | switch | no | Overwrite an existing output file |
bl managed-agent file download --file-id file_abc --output-file ./artifact.pdf
bl managed-agent file delete
Delete a Managed Agent file. Requires API Key authentication.
Usage
bl managed-agent file delete --file-id <id>
| Parameter | Type | Required | Description |
|---|
--file <path> | string | no | Config file path (default: agents.yaml) |
--file-id <id> | string | yes | Remote file ID |
--yes | switch | no | Confirm this high-risk operation |
This permanently deletes the specified remote Managed Agent file.
bl managed-agent file delete --file-id file_abc --dry-run
Webhook
Webhooks are workspace-level resources and are not written to agents.yaml or State. Creating, updating, enabling or disabling, testing, and resetting a signing secret are high-risk operations: inspect the target and request with --dry-run, then add --yes after confirmation. The signing secret is returned only when a create or reset succeeds; save it immediately.
bl managed-agent webhook create
Create a Webhook endpoint. Requires API Key authentication.
Usage
bl managed-agent webhook create --url <url> --event <type> [--event <type>] [--description <text>] [--workspace-id <id>]
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID; optional when a base URL is configured |
--url <url> | string | yes | Public HTTP or HTTPS callback URL |
--event <type> | array | yes | Named event subscription; repeat for multiple events, wildcards are unsupported |
--description <text> | string | no | Description, up to 256 characters; an empty string clears it on update |
--yes | switch | no | Confirm this high-risk operation |
This creates a Webhook and starts delivering subscribed events to its callback URL.
bl managed-agent webhook create --workspace-id ws-example --url https://example.com/webhooks --event session.updated --dry-run
bl managed-agent webhook list
List all Webhook endpoints. Requires API Key authentication.
Usage
bl managed-agent webhook list [--workspace-id <id>]
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID; optional when a base URL is configured |
bl managed-agent webhook list --workspace-id ws-example --output json
- Returns every undeleted Webhook without pagination.
bl managed-agent webhook get
Get a Webhook endpoint. Requires API Key authentication.
Usage
bl managed-agent webhook get --webhook-id <wep_id> [--workspace-id <id>]
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID; optional when a base URL is configured |
--webhook-id <wep_id> | string | yes | Webhook endpoint ID |
bl managed-agent webhook get --workspace-id ws-example --webhook-id wep_example
bl managed-agent webhook update
Update a Webhook endpoint. Requires API Key authentication.
Usage
bl managed-agent webhook update --webhook-id <wep_id> [--url <url>] [--event <type>] [--description <text>] [--workspace-id <id>]
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID; optional when a base URL is configured |
--webhook-id <wep_id> | string | yes | Webhook endpoint ID |
--url <url> | string | no | Public HTTP or HTTPS callback URL |
--event <type> | array | no | Named event subscription; repeat for multiple events, wildcards are unsupported |
--description <text> | string | no | Description, up to 256 characters; an empty string clears it |
--yes | switch | no | Confirm this high-risk operation |
This updates the callback URL, description, or event subscriptions of the Webhook.
bl managed-agent webhook update --workspace-id ws-example --webhook-id wep_example --description "" --dry-run
- Omitted fields stay unchanged; passing --event replaces the complete subscription list.
bl managed-agent webhook delete
Delete a Webhook endpoint. Requires API Key authentication.
Usage
bl managed-agent webhook delete --webhook-id <wep_id> [--workspace-id <id>]
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID; optional when a base URL is configured |
--webhook-id <wep_id> | string | yes | Webhook endpoint ID |
--yes | switch | no | Confirm this high-risk operation |
This deletes the Webhook and cancels its pending deliveries.
bl managed-agent webhook delete --workspace-id ws-example --webhook-id wep_example --dry-run
bl managed-agent webhook enable
Enable a Webhook endpoint. Requires API Key authentication.
Usage
bl managed-agent webhook enable --webhook-id <wep_id> [--workspace-id <id>]
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID; optional when a base URL is configured |
--webhook-id <wep_id> | string | yes | Webhook endpoint ID |
--yes | switch | no | Confirm this high-risk operation |
This resumes event deliveries; events from the disabled period are not replayed.
bl managed-agent webhook enable --workspace-id ws-example --webhook-id wep_example --dry-run
bl managed-agent webhook disable
Disable a Webhook endpoint. Requires API Key authentication.
Usage
bl managed-agent webhook disable --webhook-id <wep_id> [--workspace-id <id>]
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID; optional when a base URL is configured |
--webhook-id <wep_id> | string | yes | Webhook endpoint ID |
--yes | switch | no | Confirm this high-risk operation |
This stops new event deliveries and cancels pending deliveries.
bl managed-agent webhook disable --workspace-id ws-example --webhook-id wep_example --dry-run
bl managed-agent webhook test
Send a real Webhook test event. Requires API Key authentication.
Usage
bl managed-agent webhook test --webhook-id <wep_id> [--workspace-id <id>]
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID; optional when a base URL is configured |
--webhook-id <wep_id> | string | yes | Webhook endpoint ID |
--yes | switch | no | Confirm this high-risk operation |
This sends a real callback request; redirects or security validation failures may disable the Webhook.
bl managed-agent webhook test --workspace-id ws-example --webhook-id wep_example --dry-run
- Tests are synchronous, are not retried or recorded, and do not affect consecutive failure counts.
bl managed-agent webhook reset-secret
Reset a Webhook signing secret. Requires API Key authentication.
Usage
bl managed-agent webhook reset-secret --webhook-id <wep_id> [--workspace-id <id>]
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID; optional when a base URL is configured |
--webhook-id <wep_id> | string | yes | Webhook endpoint ID |
--yes | switch | no | Confirm this high-risk operation |
This immediately invalidates the previous signing secret. Save the new secret and update your receiver.
bl managed-agent webhook reset-secret --workspace-id ws-example --webhook-id wep_example --dry-run
bl managed-agent webhook events
List recent Webhook delivery events. Requires API Key authentication.
Usage
bl managed-agent webhook events --webhook-id <wep_id> [--limit <count>] [--page <cursor>] [--workspace-id <id>]
| Parameter | Type | Required | Description |
|---|
--workspace-id <id> | string | no | Workspace ID; optional when a base URL is configured |
--webhook-id <wep_id> | string | yes | Webhook endpoint ID |
--limit <count> | number | no | Page size (1-100, default: 20) |
--page <cursor> | string | no | Opaque next_page cursor from the previous response |
bl managed-agent webhook events --workspace-id ws-example --webhook-id wep_example --limit 20 --output json
- Delivery events are retained for 7 days; pass the response
next_page back to --page to continue.
- Retained events for deleted Webhooks remain queryable.
