reference/index.md
# `bailian-managed-agent` command reference
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Command **details** are in sibling `<group>.md` files in this directory.
This index only covers groups owned by this skill. Other `bl` groups live in sibling bailian-\* skills.
Use this index for the skill-scoped quick index and global flags.
## Quick index
| Command | Authentication | Description | Detail |
| ------------------------------------------ | -------------- | ---------------------------------------------------------------------------- | ------------------------------------ |
| `bl managed-agent agent create` | API Key | Declare and create one Managed Agent through an isolated YAML apply | [managed-agent.md](managed-agent.md) |
| `bl managed-agent agent get` | API Key | Get a Managed Agent | [managed-agent.md](managed-agent.md) |
| `bl managed-agent agent list` | API Key | List Managed Agents | [managed-agent.md](managed-agent.md) |
| `bl managed-agent agent search` | API Key | Search Managed Agents | [managed-agent.md](managed-agent.md) |
| `bl managed-agent agent versions` | API Key | List Managed Agent versions | [managed-agent.md](managed-agent.md) |
| `bl managed-agent apply` | API Key | Apply planned changes to create/update/delete agent resources | [managed-agent.md](managed-agent.md) |
| `bl managed-agent deployment create` | API Key | Declare and create one Managed Agent Deployment through a scoped YAML apply | [managed-agent.md](managed-agent.md) |
| `bl managed-agent deployment get` | API Key | Get a Managed Agent deployment | [managed-agent.md](managed-agent.md) |
| `bl managed-agent deployment list` | API Key | List Managed Agent deployments | [managed-agent.md](managed-agent.md) |
| `bl managed-agent deployment pause` | API Key | Pause a Managed Agent deployment | [managed-agent.md](managed-agent.md) |
| `bl managed-agent deployment run` | API Key | Run a Managed Agent deployment now | [managed-agent.md](managed-agent.md) |
| `bl managed-agent deployment runs get` | API Key | Get a Managed Agent deployment run | [managed-agent.md](managed-agent.md) |
| `bl managed-agent deployment runs list` | API Key | List runs for a Managed Agent deployment | [managed-agent.md](managed-agent.md) |
| `bl managed-agent deployment search` | API Key | Search Managed Agent deployments | [managed-agent.md](managed-agent.md) |
| `bl managed-agent deployment unpause` | API Key | Unpause a Managed Agent deployment | [managed-agent.md](managed-agent.md) |
| `bl managed-agent destroy` | API Key | Destroy all managed agent resources tracked in state | [managed-agent.md](managed-agent.md) |
| `bl managed-agent environment create` | API Key | Declare and create one Managed Agent Environment through a scoped YAML apply | [managed-agent.md](managed-agent.md) |
| `bl managed-agent environment get` | API Key | Get a Managed Agent environment | [managed-agent.md](managed-agent.md) |
| `bl managed-agent environment list` | API Key | List Managed Agent environments | [managed-agent.md](managed-agent.md) |
| `bl managed-agent environment search` | API Key | Search Managed Agent environments | [managed-agent.md](managed-agent.md) |
| `bl managed-agent file delete` | API Key | Delete a Managed Agent file | [managed-agent.md](managed-agent.md) |
| `bl managed-agent file download` | API Key | Download Managed Agent file content | [managed-agent.md](managed-agent.md) |
| `bl managed-agent file get` | API Key | Get Managed Agent file metadata | [managed-agent.md](managed-agent.md) |
| `bl managed-agent file list` | API Key | List Managed Agent files | [managed-agent.md](managed-agent.md) |
| `bl managed-agent file search` | API Key | Search Managed Agent files | [managed-agent.md](managed-agent.md) |
| `bl managed-agent file upload` | API Key | Upload a Managed Agent file | [managed-agent.md](managed-agent.md) |
| `bl managed-agent init` | No Auth | Create an agents.yaml template | [managed-agent.md](managed-agent.md) |
| `bl managed-agent plan` | API Key | Show what changes would be applied to agent infrastructure | [managed-agent.md](managed-agent.md) |
| `bl managed-agent playground` | API Key | Launch a Session Preview for an agents.yaml Agent | [managed-agent.md](managed-agent.md) |
| `bl managed-agent project build` | No Auth | Organize directory source and generate the immutable Publish Build | [managed-agent.md](managed-agent.md) |
| `bl managed-agent project init` | No Auth | Create a directory project or convert the local agents.yaml | [managed-agent.md](managed-agent.md) |
| `bl managed-agent project publish` | API Key | Publish the current directory-project Build and record a version | [managed-agent.md](managed-agent.md) |
| `bl managed-agent project validate` | No Auth | Validate a directory Agent project | [managed-agent.md](managed-agent.md) |
| `bl managed-agent project version disable` | No Auth | Disable directory project versions | [managed-agent.md](managed-agent.md) |
| `bl managed-agent project version enable` | No Auth | Enable directory project versions | [managed-agent.md](managed-agent.md) |
| `bl managed-agent project version list` | No Auth | List directory project versions | [managed-agent.md](managed-agent.md) |
| `bl managed-agent project version preview` | No Auth | Preview a directory project version | [managed-agent.md](managed-agent.md) |
| `bl managed-agent project version restore` | No Auth | Restore a version to the project working directory | [managed-agent.md](managed-agent.md) |
| `bl managed-agent project version status` | No Auth | Show directory project version status | [managed-agent.md](managed-agent.md) |
| `bl managed-agent project workbench` | API Key | Launch the directory project Workbench | [managed-agent.md](managed-agent.md) |
| `bl managed-agent session archive` | API Key | Archive a Managed Agent session | [managed-agent.md](managed-agent.md) |
| `bl managed-agent session create` | API Key | Create a new session for an agent | [managed-agent.md](managed-agent.md) |
| `bl managed-agent session debug` | API Key | Aggregate session diagnostics | [managed-agent.md](managed-agent.md) |
| `bl managed-agent session delete` | API Key | Delete a session | [managed-agent.md](managed-agent.md) |
| `bl managed-agent session event list` | API Key | List events for a Managed Agent session | [managed-agent.md](managed-agent.md) |
| `bl managed-agent session event send` | API Key | Send raw events to a Managed Agent session | [managed-agent.md](managed-agent.md) |
| `bl managed-agent session event stream` | API Key | Stream events from a Managed Agent session | [managed-agent.md](managed-agent.md) |
| `bl managed-agent session events` | API Key | List events for a Managed Agent session | [managed-agent.md](managed-agent.md) |
| `bl managed-agent session export` | API Key | Export session diagnostics as a ZIP | [managed-agent.md](managed-agent.md) |
| `bl managed-agent session get` | API Key | Get details of a session | [managed-agent.md](managed-agent.md) |
| `bl managed-agent session list` | API Key | List sessions from the provider | [managed-agent.md](managed-agent.md) |
| `bl managed-agent session run` | API Key | Create a session, send a message, and stream the response | [managed-agent.md](managed-agent.md) |
| `bl managed-agent session search` | API Key | Search Managed Agent sessions | [managed-agent.md](managed-agent.md) |
| `bl managed-agent session send` | API Key | Send a message to an existing session and stream the response | [managed-agent.md](managed-agent.md) |
| `bl managed-agent session update` | API Key | Update a Managed Agent session | [managed-agent.md](managed-agent.md) |
| `bl managed-agent skill create` | API Key | Declare and create one custom Managed Agent Skill from a local source | [managed-agent.md](managed-agent.md) |
| `bl managed-agent skill download` | API Key | Download a Managed Agent skill version | [managed-agent.md](managed-agent.md) |
| `bl managed-agent skill get` | API Key | Get a Managed Agent skill | [managed-agent.md](managed-agent.md) |
| `bl managed-agent skill list` | API Key | List Managed Agent skills | [managed-agent.md](managed-agent.md) |
| `bl managed-agent skill search` | API Key | Search Managed Agent skills | [managed-agent.md](managed-agent.md) |
| `bl managed-agent skill versions` | API Key | List Managed Agent skill versions | [managed-agent.md](managed-agent.md) |
| `bl managed-agent skill-list` | API Key | List Managed Agent skills | [managed-agent.md](managed-agent.md) |
| `bl managed-agent state import` | API Key | Import an existing remote resource into agents state | [managed-agent.md](managed-agent.md) |
| `bl managed-agent state list` | No Auth | List resources tracked in agents state | [managed-agent.md](managed-agent.md) |
| `bl managed-agent state rm` | No Auth | Remove a resource from state without destroying it remotely | [managed-agent.md](managed-agent.md) |
| `bl managed-agent state show` | No Auth | Show details of a resource in agents state | [managed-agent.md](managed-agent.md) |
| `bl managed-agent validate` | No Auth | Validate an agents.yaml configuration (offline) | [managed-agent.md](managed-agent.md) |
| `bl managed-agent vault create` | API Key | Declare and create one empty Managed Agent Vault through a scoped YAML apply | [managed-agent.md](managed-agent.md) |
| `bl managed-agent vault credential create` | API Key | Append and create one environment-variable Credential in a tracked Vault | [managed-agent.md](managed-agent.md) |
| `bl managed-agent vault get` | API Key | Get a Managed Agent vault | [managed-agent.md](managed-agent.md) |
| `bl managed-agent vault list` | API Key | List Managed Agent vaults | [managed-agent.md](managed-agent.md) |
| `bl managed-agent vault search` | API Key | Search Managed Agent vaults | [managed-agent.md](managed-agent.md) |
## By group
| Group | Commands | Reference |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `managed-agent` | `agent create`, `agent get`, `agent list`, `agent search`, `agent versions`, `apply`, `deployment create`, `deployment get`, `deployment list`, `deployment pause`, `deployment run`, `deployment runs get`, `deployment runs list`, `deployment search`, `deployment unpause`, `destroy`, `environment create`, `environment get`, `environment list`, `environment search`, `file delete`, `file download`, `file get`, `file list`, `file search`, `file upload`, `init`, `plan`, `playground`, `project build`, `project init`, `project publish`, `project validate`, `project version disable`, `project version enable`, `project version list`, `project version preview`, `project version restore`, `project version status`, `project workbench`, `session archive`, `session create`, `session debug`, `session delete`, `session event list`, `session event send`, `session event stream`, `session events`, `session export`, `session get`, `session list`, `session run`, `session search`, `session send`, `session update`, `skill create`, `skill download`, `skill get`, `skill list`, `skill search`, `skill versions`, `skill-list`, `state import`, `state list`, `state rm`, `state show`, `validate`, `vault create`, `vault credential create`, `vault get`, `vault list`, `vault search` | [managed-agent.md](managed-agent.md) |
## Global flags
Available on every command (in addition to command-specific flags):
| Flag | Type | Required | Description |
| --------------------- | ------ | -------- | ------------------------------------- |
| `--output <format>` | string | no | Output format: text, json |
| `--timeout <seconds>` | number | no | Request timeout |
| `--quiet` | switch | no | Suppress non-essential output |
| `--verbose` | switch | no | Print HTTP request/response details |
| `--dry-run` | switch | no | Dry run mode |
| `--config <name>` | string | no | Use a config profile for this command |
| `--help` | switch | no | Show help |
| `--version` | switch | no | Print version |
## Model auth flags
Available on model-domain commands (API-key auth); also listed per command below:
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | ------------ |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
## Console auth flags
Available on console-domain commands (console login auth); also listed per command below:
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | -------------------------------------------------------- |
| `--console-region <region>` | string | no | Console gateway region (e.g. cn-beijing, ap-southeast-1) |
| `--console-site <site>` | string | no | Console site: domestic, international |
| `--console-switch-agent <uid>` | number | no | Switch agent UID for delegated access |
| `--workspace-id <id>` | string | no | Workspace ID (env: BAILIAN_WORKSPACE_ID) |
## OpenAPI auth flags
Available on OpenAPI-domain commands (AK/SK auth); also listed per command below:
| Flag | Type | Required | Description |
| --------------------------- | ------ | -------- | ---------------------------------------------------------------------- |
| `--access-key-id <key>` | string | no | Alibaba Cloud Access Key ID (env: ALIBABA_CLOUD_ACCESS_KEY_ID) |
| `--access-key-secret <key>` | string | no | Alibaba Cloud Access Key Secret (env: ALIBABA_CLOUD_ACCESS_KEY_SECRET) |
| `--security-token <token>` | string | no | Alibaba Cloud STS Security Token (env: ALIBABA_CLOUD_SECURITY_TOKEN) |
## Notes
- Console commands (`app list`, `usage free`, `console call`) require `bl auth login --console`.
- Most API commands use `DASHSCOPE_API_KEY` or `bl auth login --api-key`.
- Token Plan commands use OpenAPI AK/SK via `bl auth login --open-api` or `ALIBABA_CLOUD_ACCESS_KEY_ID` / `ALIBABA_CLOUD_ACCESS_KEY_SECRET`.
- Default output: **text** unless explicitly set to `json` with `--output`, `DASHSCOPE_OUTPUT`, or config.
reference/managed-agent.md
# `bl managed-agent` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| ------------------------------------------ | -------------- | ---------------------------------------------------------------------------- |
| `bl managed-agent agent create` | API Key | Declare and create one Managed Agent through an isolated YAML apply |
| `bl managed-agent agent get` | API Key | Get a Managed Agent |
| `bl managed-agent agent list` | API Key | List Managed Agents |
| `bl managed-agent agent search` | API Key | Search Managed Agents |
| `bl managed-agent agent versions` | API Key | List Managed Agent versions |
| `bl managed-agent apply` | API Key | Apply planned changes to create/update/delete agent resources |
| `bl managed-agent deployment create` | API Key | Declare and create one Managed Agent Deployment through a scoped YAML apply |
| `bl managed-agent deployment get` | API Key | Get a Managed Agent deployment |
| `bl managed-agent deployment list` | API Key | List Managed Agent deployments |
| `bl managed-agent deployment pause` | API Key | Pause a Managed Agent deployment |
| `bl managed-agent deployment run` | API Key | Run a Managed Agent deployment now |
| `bl managed-agent deployment runs get` | API Key | Get a Managed Agent deployment run |
| `bl managed-agent deployment runs list` | API Key | List runs for a Managed Agent deployment |
| `bl managed-agent deployment search` | API Key | Search Managed Agent deployments |
| `bl managed-agent deployment unpause` | API Key | Unpause a Managed Agent deployment |
| `bl managed-agent destroy` | API Key | Destroy all managed agent resources tracked in state |
| `bl managed-agent environment create` | API Key | Declare and create one Managed Agent Environment through a scoped YAML apply |
| `bl managed-agent environment get` | API Key | Get a Managed Agent environment |
| `bl managed-agent environment list` | API Key | List Managed Agent environments |
| `bl managed-agent environment search` | API Key | Search Managed Agent environments |
| `bl managed-agent file delete` | API Key | Delete a Managed Agent file |
| `bl managed-agent file download` | API Key | Download Managed Agent file content |
| `bl managed-agent file get` | API Key | Get Managed Agent file metadata |
| `bl managed-agent file list` | API Key | List Managed Agent files |
| `bl managed-agent file search` | API Key | Search Managed Agent files |
| `bl managed-agent file upload` | API Key | Upload a Managed Agent file |
| `bl managed-agent init` | No Auth | Create an agents.yaml template |
| `bl managed-agent plan` | API Key | Show what changes would be applied to agent infrastructure |
| `bl managed-agent playground` | API Key | Launch a Session Preview for an agents.yaml Agent |
| `bl managed-agent project build` | No Auth | Organize directory source and generate the immutable Publish Build |
| `bl managed-agent project init` | No Auth | Create a directory project or convert the local agents.yaml |
| `bl managed-agent project publish` | API Key | Publish the current directory-project Build and record a version |
| `bl managed-agent project validate` | No Auth | Validate a directory Agent project |
| `bl managed-agent project version disable` | No Auth | Disable directory project versions |
| `bl managed-agent project version enable` | No Auth | Enable directory project versions |
| `bl managed-agent project version list` | No Auth | List directory project versions |
| `bl managed-agent project version preview` | No Auth | Preview a directory project version |
| `bl managed-agent project version restore` | No Auth | Restore a version to the project working directory |
| `bl managed-agent project version status` | No Auth | Show directory project version status |
| `bl managed-agent project workbench` | API Key | Launch the directory project Workbench |
| `bl managed-agent session archive` | API Key | Archive a Managed Agent session |
| `bl managed-agent session create` | API Key | Create a new session for an agent |
| `bl managed-agent session debug` | API Key | Aggregate session diagnostics |
| `bl managed-agent session delete` | API Key | Delete a session |
| `bl managed-agent session event list` | API Key | List events for a Managed Agent session |
| `bl managed-agent session event send` | API Key | Send raw events to a Managed Agent session |
| `bl managed-agent session event stream` | API Key | Stream events from a Managed Agent session |
| `bl managed-agent session events` | API Key | List events for a Managed Agent session |
| `bl managed-agent session export` | API Key | Export session diagnostics as a ZIP |
| `bl managed-agent session get` | API Key | Get details of a session |
| `bl managed-agent session list` | API Key | List sessions from the provider |
| `bl managed-agent session run` | API Key | Create a session, send a message, and stream the response |
| `bl managed-agent session search` | API Key | Search Managed Agent sessions |
| `bl managed-agent session send` | API Key | Send a message to an existing session and stream the response |
| `bl managed-agent session update` | API Key | Update a Managed Agent session |
| `bl managed-agent skill create` | API Key | Declare and create one custom Managed Agent Skill from a local source |
| `bl managed-agent skill download` | API Key | Download a Managed Agent skill version |
| `bl managed-agent skill get` | API Key | Get a Managed Agent skill |
| `bl managed-agent skill list` | API Key | List Managed Agent skills |
| `bl managed-agent skill search` | API Key | Search Managed Agent skills |
| `bl managed-agent skill versions` | API Key | List Managed Agent skill versions |
| `bl managed-agent skill-list` | API Key | List Managed Agent skills |
| `bl managed-agent state import` | API Key | Import an existing remote resource into agents state |
| `bl managed-agent state list` | No Auth | List resources tracked in agents state |
| `bl managed-agent state rm` | No Auth | Remove a resource from state without destroying it remotely |
| `bl managed-agent state show` | No Auth | Show details of a resource in agents state |
| `bl managed-agent validate` | No Auth | Validate an agents.yaml configuration (offline) |
| `bl managed-agent vault create` | API Key | Declare and create one empty Managed Agent Vault through a scoped YAML apply |
| `bl managed-agent vault credential create` | API Key | Append and create one environment-variable Credential in a tracked Vault |
| `bl managed-agent vault get` | API Key | Get a Managed Agent vault |
| `bl managed-agent vault list` | API Key | List Managed Agent vaults |
| `bl managed-agent vault search` | API Key | Search Managed Agent vaults |
## Command details
### `bl managed-agent agent create`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent agent create` |
| **Description** | Declare and create one Managed Agent through an isolated YAML apply |
| **Authentication** | API Key |
| **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>...] [--file <path>] [--yes]` |
#### Flags
| Flag | 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) |
| `--file <path>` | string | no | Config file path (default: agents.yaml) |
| `--yes` | switch | no | Write YAML and run the scoped remote create |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
- 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.
#### Examples
```bash
bl managed-agent agent create --name assistant --model qwen3.8-max --instructions "You are helpful."
```
```bash
bl managed-agent agent create --name assistant --model qwen3.8-max --instructions ./prompts/assistant.md --skill skill_abc --yes
```
```bash
bl managed-agent agent create --name slides --model qwen3.8-max --instructions ./prompts/slides.md --skill skill_pptx --type official --yes
```
```bash
bl managed-agent agent create --name reviewer --model qwen3.8-max --instructions ./prompts/reviewer.md --skill-dir ./skills/code-review --yes
```
### `bl managed-agent agent get`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------------------- |
| **Name** | `managed-agent agent get` |
| **Description** | Get a Managed Agent |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent agent get --agent-id <id> [--agent-version <n>] [--file <path>]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent agent get --agent-id agent_abc
```
```bash
bl managed-agent agent get --agent-id agent_abc --agent-version 3 --output json
```
### `bl managed-agent agent list`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent agent list` |
| **Description** | List Managed Agents |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent agent list [--limit <n>] [--page <cursor>] [--all] [--include-archived] [--file <path>]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent agent list
```
```bash
bl managed-agent agent list --limit 50
```
```bash
bl managed-agent agent list --all --include-archived --output json
```
### `bl managed-agent agent search`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent agent search` |
| **Description** | Search Managed Agents |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent agent search --query <text> [--limit <n>] [--page-limit <n>] [--include-archived]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent agent search --query assistant
```
```bash
bl managed-agent agent search --query code --page-limit 20 --output json
```
### `bl managed-agent agent versions`
| Field | Value |
| ------------------ | ----------------------------------------------------------------------------------------- |
| **Name** | `managed-agent agent versions` |
| **Description** | List Managed Agent versions |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent agent versions --agent-id <id> [--limit <n>] [--page <cursor>] [--all]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent agent versions --agent-id agent_abc
```
```bash
bl managed-agent agent versions --agent-id agent_abc --all --output json
```
### `bl managed-agent apply`
| Field | Value |
| ------------------ | ----------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent apply` |
| **Description** | Apply planned changes to create/update/delete agent resources |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent apply [--file <path>] [--concurrency <n>]` |
| **Risk** | `high` |
| **Risk message** | This applies the current plan and may create, update, or delete remote managed Agent resources. |
> **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
# Only after explicit user confirmation:
bl managed-agent apply --yes
```
### `bl managed-agent deployment create`
| Field | Value |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent deployment create` |
| **Description** | Declare and create one Managed Agent Deployment through a scoped YAML apply |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent deployment create --name <name> --agent <yaml-key> (--message <text>... \| --event <json\|@path>...) [--agent-version <number>] [--environment <yaml-key>] [--vault <yaml-key>...] [--resource <json\|@path>...] [--schedule <cron> --timezone <timezone>] [--description <text>] [--metadata <key=value>...] [--file <path>] [--yes]` |
#### Flags
| Flag | 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 |
| `--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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
- Without --yes, this command only previews. --dry-run is fully offline. The scoped flow checks only the target resource and its transitive dependencies; unrelated resources are not refreshed or drift-checked.
- 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.
#### Examples
```bash
bl managed-agent deployment create --name Daily --agent assistant --message "Generate the report"
```
```bash
bl managed-agent deployment create --name Daily --agent assistant --event '{"type":"system.message","content":"Be concise"}' --yes
```
### `bl managed-agent deployment get`
| Field | Value |
| ------------------ | ------------------------------------------------------ |
| **Name** | `managed-agent deployment get` |
| **Description** | Get a Managed Agent deployment |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent deployment get --deployment-id <id>` |
#### Flags
| Flag | Type | Required | Description |
| ---------------------- | ------ | -------- | --------------------------------------- |
| `--file <path>` | string | no | Config file path (default: agents.yaml) |
| `--deployment-id <id>` | string | yes | Deployment ID |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent deployment get --deployment-id dep_abc
```
### `bl managed-agent deployment list`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent deployment list` |
| **Description** | List Managed Agent deployments |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent deployment list [--agent-id <id>] [--status active\|paused] [--limit <n>] [--page <cursor>] [--all]` |
#### Flags
| Flag | 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 <active\|paused>` | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent deployment list
```
```bash
bl managed-agent deployment list --status active --all --output json
```
### `bl managed-agent deployment pause`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent deployment pause` |
| **Description** | Pause a Managed Agent deployment |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent deployment pause (--deployment <name> \| --deployment-id <id>)` |
| **Risk** | `high` |
| **Risk message** | This pauses the specified Managed Agent deployment and stops its scheduled executions until resumed. |
> **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent deployment pause --deployment daily-report --dry-run
```
```bash
# Only after explicit user confirmation:
bl managed-agent deployment pause --deployment-id dep_abc --yes
```
### `bl managed-agent deployment run`
| Field | Value |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent deployment run` |
| **Description** | Run a Managed Agent deployment now |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent deployment run (--deployment <name> \| --deployment-id <id>)` |
| **Risk** | `high` |
| **Risk message** | This immediately starts a run for the specified Managed Agent deployment and may incur usage or trigger configured actions. |
> **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent deployment run --deployment daily-report --dry-run
```
```bash
# Only after explicit user confirmation:
bl managed-agent deployment run --deployment-id dep_abc --yes
```
### `bl managed-agent deployment runs get`
| Field | Value |
| ------------------ | ---------------------------------------------------- |
| **Name** | `managed-agent deployment runs get` |
| **Description** | Get a Managed Agent deployment run |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent deployment runs get --run-id <id>` |
#### Flags
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | --------------------------------------- |
| `--file <path>` | string | no | Config file path (default: agents.yaml) |
| `--run-id <id>` | string | yes | Deployment run ID |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent deployment runs get --run-id run_abc
```
### `bl managed-agent deployment runs list`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent deployment runs list` |
| **Description** | List runs for a Managed Agent deployment |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent deployment runs list --deployment-id <id> [--limit <n>] [--page <cursor>] [--all]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent deployment runs list --deployment-id dep_abc
```
```bash
bl managed-agent deployment runs list --deployment-id dep_abc --all --output json
```
### `bl managed-agent deployment search`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent deployment search` |
| **Description** | Search Managed Agent deployments |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent deployment search --query <text> [--limit <n>] [--page <cursor>] [--all]` |
#### Flags
| Flag | 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 <active\|paused>` | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
- Deployment search maps --query to the provider's server-side keyword parameter.
#### Examples
```bash
bl managed-agent deployment search --query report
```
```bash
bl managed-agent deployment search --query nightly --all --output json
```
### `bl managed-agent deployment unpause`
| Field | Value |
| ------------------ | ----------------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent deployment unpause` |
| **Description** | Unpause a Managed Agent deployment |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent deployment unpause (--deployment <name> \| --deployment-id <id>)` |
| **Risk** | `high` |
| **Risk message** | This resumes the specified Managed Agent deployment and may restart scheduled executions and related usage. |
> **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent deployment unpause --deployment daily-report --dry-run
```
```bash
# Only after explicit user confirmation:
bl managed-agent deployment unpause --deployment-id dep_abc --yes
```
### `bl managed-agent destroy`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent destroy` |
| **Description** | Destroy all managed agent resources tracked in state |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent destroy [--file <path>] [--cascade]` |
| **Risk** | `high` |
| **Risk message** | This deletes every managed Agent resource tracked in state; --cascade may also delete dependent resources. |
> **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
# Only after explicit user confirmation:
bl managed-agent destroy --yes
```
```bash
# Only after explicit user confirmation:
bl managed-agent destroy --yes --cascade
```
### `bl managed-agent environment create`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent environment create` |
| **Description** | Declare and create one Managed Agent Environment through a scoped YAML apply |
| **Authentication** | API Key |
| **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]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
- Without --yes, this command only previews. --dry-run is fully offline. The scoped flow checks only the target resource and its transitive dependencies; unrelated resources are not refreshed or drift-checked.
- Creates a cloud Environment with unrestricted networking. Without --yes, only previews the generated YAML key and scoped plan.
#### Examples
```bash
bl managed-agent environment create --name Development
```
```bash
bl managed-agent environment create --name Development --pip pandas --npm typescript --metadata owner=platform --yes
```
### `bl managed-agent environment get`
| Field | Value |
| ------------------ | -------------------------------------------------------- |
| **Name** | `managed-agent environment get` |
| **Description** | Get a Managed Agent environment |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent environment get --environment-id <id>` |
#### Flags
| Flag | Type | Required | Description |
| ----------------------- | ------ | -------- | --------------------------------------- |
| `--file <path>` | string | no | Config file path (default: agents.yaml) |
| `--environment-id <id>` | string | yes | Environment ID |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent environment get --environment-id env_abc
```
### `bl managed-agent environment list`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| **Name** | `managed-agent environment list` |
| **Description** | List Managed Agent environments |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent environment list [--limit <n>] [--page <cursor>] [--all] [--include-archived]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent environment list
```
```bash
bl managed-agent environment list --all --output json
```
### `bl managed-agent environment search`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent environment search` |
| **Description** | Search Managed Agent environments |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent environment search --query <text> [--limit <n>] [--page-limit <n>] [--include-archived]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent environment search --query sandbox
```
```bash
bl managed-agent environment search --query production --page-limit 20 --output json
```
### `bl managed-agent file delete`
| Field | Value |
| ------------------ | ----------------------------------------------------------------- |
| **Name** | `managed-agent file delete` |
| **Description** | Delete a Managed Agent file |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent file delete --file-id <id>` |
| **Risk** | `high` |
| **Risk message** | This permanently deletes the specified remote Managed Agent file. |
> **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent file delete --file-id file_abc --dry-run
```
```bash
# Only after explicit user confirmation:
bl managed-agent file delete --file-id file_abc --yes
```
### `bl managed-agent file download`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------ |
| **Name** | `managed-agent file download` |
| **Description** | Download Managed Agent file content |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent file download --file-id <id> --output-file <path> [--force]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent file download --file-id file_abc --output-file ./artifact.pdf
```
### `bl managed-agent file get`
| Field | Value |
| ------------------ | ------------------------------------------ |
| **Name** | `managed-agent file get` |
| **Description** | Get Managed Agent file metadata |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent file get --file-id <id>` |
#### Flags
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | --------------------------------------- |
| `--file <path>` | string | no | Config file path (default: agents.yaml) |
| `--file-id <id>` | string | yes | Remote file ID |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent file get --file-id file_abc
```
### `bl managed-agent file list`
| Field | Value |
| ------------------ | -------------------------------------------------------------------------------------- |
| **Name** | `managed-agent file list` |
| **Description** | List Managed Agent files |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent file list [--scope-id <id>] [--limit <n>] [--page <cursor>] [--all]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent file list
```
```bash
bl managed-agent file list --scope-id sess_abc --all --output json
```
### `bl managed-agent file search`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| **Name** | `managed-agent file search` |
| **Description** | Search Managed Agent files |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent file search --query <text> [--scope-id <id>] [--limit <n>] [--page-limit <n>]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent file search --query report
```
```bash
bl managed-agent file search --query pdf --scope-id sess_abc --output json
```
### `bl managed-agent file upload`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------- |
| **Name** | `managed-agent file upload` |
| **Description** | Upload a Managed Agent file |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent file upload --path <path> [--filename <name>] [--mime-type <type>]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent file upload --path ./report.pdf
```
### `bl managed-agent init`
| Field | Value |
| ------------------ | ----------------------------------------------------------------------- |
| **Name** | `managed-agent init` |
| **Description** | Create an agents.yaml template |
| **Authentication** | No Auth |
| **Usage** | `bl managed-agent init [--agent-name <name>] [--file <path>] [--force]` |
#### Flags
| Flag | 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 |
#### Examples
```bash
bl managed-agent init
```
```bash
bl managed-agent init --agent-name assistant
```
### `bl managed-agent plan`
| Field | Value |
| ------------------ | ----------------------------------------------------------------------- |
| **Name** | `managed-agent plan` |
| **Description** | Show what changes would be applied to agent infrastructure |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent plan [--file <path>] [--no-refresh] [--refresh-only]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
- --no-refresh and --dry-run plan offline from local config and state: no remote requests, no state writes, provider keys are not checked.
#### Examples
```bash
bl managed-agent plan
```
```bash
bl managed-agent plan --no-refresh
```
### `bl managed-agent playground`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------- |
| **Name** | `managed-agent playground` |
| **Description** | Launch a Session Preview for an agents.yaml Agent |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent playground [--file <path>] [--agent <id>] [--port <n>] [--no-open]` |
#### Flags
| Flag | 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) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
- Session Preview requires Node.js 22+ and keeps using an agents.yaml source. Directory Workbench is available under managed-agent project workbench.
#### Examples
```bash
bl managed-agent playground
```
```bash
bl managed-agent playground --agent assistant
```
```bash
bl managed-agent playground --file agents.yaml --no-open
```
### `bl managed-agent project build`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent project build` |
| **Description** | Organize directory source and generate the immutable Publish Build |
| **Authentication** | No Auth |
| **Usage** | `bl managed-agent project build [--project <directory>]` |
| **Risk** | `high` |
| **Risk message** | This organizes project source, moves literal Vault secrets into the local .env, and writes the previewed immutable Build. |
> **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
#### Flags
| Flag | Type | Required | Description |
| ----------------------- | ------ | -------- | --------------------------------------------------- |
| `--project <directory>` | string | no | Directory project root (default: current directory) |
| `--yes` | switch | no | Confirm this high-risk operation |
#### Examples
```bash
bl managed-agent project build --dry-run
```
```bash
# Only after explicit user confirmation:
bl managed-agent project build --yes
```
```bash
# Only after explicit user confirmation:
bl managed-agent project build --project ./my-agent --yes
```
### `bl managed-agent project init`
| Field | Value |
| ------------------ | ----------------------------------------------------------- |
| **Name** | `managed-agent project init` |
| **Description** | Create a directory project or convert the local agents.yaml |
| **Authentication** | No Auth |
| **Usage** | `bl managed-agent project init [--project <directory>]` |
#### Flags
| Flag | Type | Required | Description |
| ----------------------- | ------ | -------- | --------------------------------------------------- |
| `--project <directory>` | string | no | Directory project root (default: current directory) |
#### Notes
- 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.
#### Examples
```bash
bl managed-agent project init
```
```bash
bl managed-agent project init --project ./my-agent
```
### `bl managed-agent project publish`
| Field | Value |
| ------------------ | -------------------------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent project publish` |
| **Description** | Publish the current directory-project Build and record a version |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent project publish [--project <directory>] [--no-refresh] [--concurrency <n>]` |
| **Risk** | `high` |
| **Risk message** | This publishes the current directory-project Build and may create, update, or delete remote managed Agent resources. |
> **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
# Only after explicit user confirmation:
bl managed-agent project publish --yes
```
```bash
# Only after explicit user confirmation:
bl managed-agent project publish --project ./my-agent --yes
```
### `bl managed-agent project validate`
| Field | Value |
| ------------------ | ----------------------------------------------------------- |
| **Name** | `managed-agent project validate` |
| **Description** | Validate a directory Agent project |
| **Authentication** | No Auth |
| **Usage** | `bl managed-agent project validate [--project <directory>]` |
#### Flags
| Flag | Type | Required | Description |
| ----------------------- | ------ | -------- | --------------------------------------------------- |
| `--project <directory>` | string | no | Directory project root (default: current directory) |
#### Examples
```bash
bl managed-agent project validate
```
```bash
bl managed-agent project validate --project ./my-agent
```
### `bl managed-agent project version disable`
| Field | Value |
| ------------------ | ------------------------------------------------------------------ |
| **Name** | `managed-agent project version disable` |
| **Description** | Disable directory project versions |
| **Authentication** | No Auth |
| **Usage** | `bl managed-agent project version disable [--project <directory>]` |
#### Flags
| Flag | Type | Required | Description |
| ----------------------- | ------ | -------- | --------------------------------------------------- |
| `--project <directory>` | string | no | Directory project root (default: current directory) |
#### Examples
```bash
bl managed-agent project version disable
```
```bash
bl managed-agent project version disable --project ./my-agent
```
### `bl managed-agent project version enable`
| Field | Value |
| ------------------ | ----------------------------------------------------------------- |
| **Name** | `managed-agent project version enable` |
| **Description** | Enable directory project versions |
| **Authentication** | No Auth |
| **Usage** | `bl managed-agent project version enable [--project <directory>]` |
#### Flags
| Flag | Type | Required | Description |
| ----------------------- | ------ | -------- | --------------------------------------------------- |
| `--project <directory>` | string | no | Directory project root (default: current directory) |
#### Examples
```bash
bl managed-agent project version enable
```
```bash
bl managed-agent project version enable --project ./my-agent
```
### `bl managed-agent project version list`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent project version list` |
| **Description** | List directory project versions |
| **Authentication** | No Auth |
| **Usage** | `bl managed-agent project version list [--project <directory>] [--limit <n>] [--cursor <cursor>]` |
#### Flags
| Flag | 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 |
#### Examples
```bash
bl managed-agent project version list
```
```bash
bl managed-agent project version list --limit 20 --output json
```
### `bl managed-agent project version preview`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent project version preview` |
| **Description** | Preview a directory project version |
| **Authentication** | No Auth |
| **Usage** | `bl managed-agent project version preview --version-id <full-version> [--project <directory>]` |
#### Flags
| Flag | Type | Required | Description |
| ----------------------------- | ------ | -------- | --------------------------------------------------- |
| `--project <directory>` | string | no | Directory project root (default: current directory) |
| `--version-id <full-version>` | string | yes | Full project version ID |
#### Examples
```bash
bl managed-agent project version preview --version-id <full-version>
```
### `bl managed-agent project version restore`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------------------ |
| **Name** | `managed-agent project version restore` |
| **Description** | Restore a version to the project working directory |
| **Authentication** | No Auth |
| **Usage** | `bl managed-agent project version restore --version-id <full-version> [--project <directory>]` |
| **Risk** | `high` |
| **Risk message** | This restores the full directory source to the working tree. Version history and remote State will not move. |
> **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
#### Flags
| Flag | 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 |
#### Examples
```bash
bl managed-agent project version restore --version-id <full-version>
```
```bash
# Only after explicit user confirmation:
bl managed-agent project version restore --version-id <full-version> --yes
```
### `bl managed-agent project version status`
| Field | Value |
| ------------------ | ----------------------------------------------------------------- |
| **Name** | `managed-agent project version status` |
| **Description** | Show directory project version status |
| **Authentication** | No Auth |
| **Usage** | `bl managed-agent project version status [--project <directory>]` |
#### Flags
| Flag | Type | Required | Description |
| ----------------------- | ------ | -------- | --------------------------------------------------- |
| `--project <directory>` | string | no | Directory project root (default: current directory) |
#### Examples
```bash
bl managed-agent project version status
```
```bash
bl managed-agent project version status --project ./my-agent --output json
```
### `bl managed-agent project workbench`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------- |
| **Name** | `managed-agent project workbench` |
| **Description** | Launch the directory project Workbench |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent project workbench [--project <directory>] [--port <n>] [--no-open]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent project workbench
```
```bash
bl managed-agent project workbench --project ./my-agent --no-open
```
### `bl managed-agent session archive`
| Field | Value |
| ------------------ | --------------------------------------------------------- |
| **Name** | `managed-agent session archive` |
| **Description** | Archive a Managed Agent session |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent session archive --session-id <id>` |
| **Risk** | `high` |
| **Risk message** | This archives the specified remote Managed Agent Session. |
> **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent session archive --session-id sess_abc --dry-run
```
```bash
# Only after explicit user confirmation:
bl managed-agent session archive --session-id sess_abc --yes
```
### `bl managed-agent session create`
| Field | Value |
| ------------------ | ----------------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent session create` |
| **Description** | Create a new session for an agent |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent session create [--agent <name>] [--environment <name>] [--title <title>] [--file <path>]` |
#### Flags
| Flag | 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) |
| `--title <title>` | string | no | Session title |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent session create
```
```bash
bl managed-agent session create --agent assistant
```
```bash
bl managed-agent session create --agent assistant --title 'debug run'
```
### `bl managed-agent session debug`
| Field | Value |
| ------------------ | -------------------------------------------------- |
| **Name** | `managed-agent session debug` |
| **Description** | Aggregate session diagnostics |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent session debug --session-id <id>` |
#### Flags
| Flag | Type | Required | Description |
| ------------------- | ------ | -------- | --------------------------------------- |
| `--file <path>` | string | no | Config file path (default: agents.yaml) |
| `--session-id <id>` | string | yes | Session ID |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent session debug --session-id sess_abc
```
```bash
bl managed-agent session debug --session-id sess_abc --output json
```
### `bl managed-agent session delete`
| Field | Value |
| ------------------ | ------------------------------------------------------------------- |
| **Name** | `managed-agent session delete` |
| **Description** | Delete a session |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent session delete --session-id <id> [--file <path>]` |
| **Risk** | `high` |
| **Risk message** | This deletes the specified remote managed Agent Session. |
> **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
#### Flags
| Flag | Type | Required | Description |
| ------------------- | ------ | -------- | --------------------------------------- |
| `--session-id <id>` | string | yes | Session ID (required) |
| `--file <path>` | string | no | Config file path (default: agents.yaml) |
| `--yes` | switch | no | Confirm this high-risk operation |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
# Only after explicit user confirmation:
bl managed-agent session delete --session-id sess_abc123 --yes
```
### `bl managed-agent session event list`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent session event list` |
| **Description** | List events for a Managed Agent session |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent session event list --session-id <id> [--types <types>] [--order asc\|desc] [--limit <n>] [--page <cursor>] [--all]` |
#### Flags
| Flag | 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 <asc\|desc>` | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
- --types is applied client-side to each page returned by the provider.
#### Examples
```bash
bl managed-agent session event list --session-id sess_abc
```
```bash
bl managed-agent session event list --session-id sess_abc --all --output json
```
### `bl managed-agent session event send`
| Field | Value |
| ------------------ | ----------------------------------------------------------------------------- |
| **Name** | `managed-agent session event send` |
| **Description** | Send raw events to a Managed Agent session |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent session event send --session-id <id> --event <json\|@path>` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent session event send --session-id sess_abc --event '{"type":"message","role":"user","content":[{"type":"text","text":"hello"}]}'
```
```bash
bl managed-agent session event send --session-id sess_abc --event @event.json
```
### `bl managed-agent session event stream`
| Field | Value |
| ------------------ | --------------------------------------------------------------------------------- |
| **Name** | `managed-agent session event stream` |
| **Description** | Stream events from a Managed Agent session |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent session event stream --session-id <id> [--after-id <event-id>]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
- When the provider has no native event cursor, --after-id resumes through paginated history polling and event ID de-duplication.
#### Examples
```bash
bl managed-agent session event stream --session-id sess_abc
```
```bash
bl managed-agent session event stream --session-id sess_abc --after-id evt_123 --output json
```
### `bl managed-agent session events`
| Field | Value |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent session events` |
| **Description** | List events for a Managed Agent session |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent session events --session-id <id> [--types <types>] [--order asc\|desc] [--limit <n>] [--page <cursor>] [--all]` |
#### Flags
| Flag | 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 <asc\|desc>` | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
- --types is applied client-side to each page returned by the provider.
#### Examples
```bash
bl managed-agent session events --session-id sess_abc
```
```bash
bl managed-agent session events --session-id sess_abc --all --output json
```
### `bl managed-agent session export`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------------------- |
| **Name** | `managed-agent session export` |
| **Description** | Export session diagnostics as a ZIP |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent session export --session-id <id> --output-file <path> [--force]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
- The ZIP contains metadata only; file bodies and credential-like values are excluded/redacted.
#### Examples
```bash
bl managed-agent session export --session-id sess_abc --output-file ./session-debug.zip
```
### `bl managed-agent session get`
| Field | Value |
| ------------------ | ---------------------------------------------------------------- |
| **Name** | `managed-agent session get` |
| **Description** | Get details of a session |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent session get --session-id <id> [--file <path>]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------- | ------ | -------- | --------------------------------------- |
| `--session-id <id>` | string | yes | Session ID (required) |
| `--file <path>` | string | no | Config file path (default: agents.yaml) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent session get --session-id sess_abc123
```
### `bl managed-agent session list`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent session list` |
| **Description** | List sessions from the provider |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent session list [--agent <name>] [--statuses <statuses>] [--limit <n>] [--page <cursor>] [--all]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent session list
```
```bash
bl managed-agent session list --agent assistant
```
```bash
bl managed-agent session list --all
```
### `bl managed-agent session run`
| Field | Value |
| ------------------ | --------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent session run` |
| **Description** | Create a session, send a message, and stream the response |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent session run --prompt <text> [--agent <name>] [--no-stream] [--file <path>]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------- | ------ | -------- | ------------------------------------------------------------ |
| `--prompt <text>` | string | yes | Prompt to send (required) |
| `--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) |
| `--title <title>` | string | no | Session title |
| `--no-stream` | switch | no | Use polling instead of SSE streaming |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
- --output json emits one envelope: { session_id, provider, agent, events } — read session_id to chain `session send/get/events/delete`.
#### Examples
```bash
bl managed-agent session run --prompt "hello"
```
```bash
bl managed-agent session run --agent assistant --prompt "summarize this repo"
```
### `bl managed-agent session search`
| Field | Value |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent session search` |
| **Description** | Search Managed Agent sessions |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent session search --query <text> [--agent <name>] [--statuses <statuses>] [--limit <n>] [--page-limit <n>]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent session search --query debug
```
```bash
bl managed-agent session search --query failed --statuses failed --output json
```
### `bl managed-agent session send`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| **Name** | `managed-agent session send` |
| **Description** | Send a message to an existing session and stream the response |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent session send --session-id <id> --message <text> [--no-stream] [--file <path>]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------- | ------ | -------- | --------------------------------------- |
| `--session-id <id>` | string | yes | Session ID (required) |
| `--message <text>` | string | yes | Message to send (required) |
| `--file <path>` | string | no | Config file path (default: agents.yaml) |
| `--no-stream` | switch | no | Use polling instead of SSE streaming |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent session send --session-id sess_abc123 --message "continue"
```
### `bl managed-agent session update`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| **Name** | `managed-agent session update` |
| **Description** | Update a Managed Agent session |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent session update --session-id <id> [--title <title>] [--metadata <json\|@path>]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent session update --session-id sess_abc --title 'investigation'
```
```bash
bl managed-agent session update --session-id sess_abc --metadata @metadata.json
```
### `bl managed-agent skill create`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent skill create` |
| **Description** | Declare and create one custom Managed Agent Skill from a local source |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent skill create --source <directory\|zip\|SKILL.md> [--file <path>] [--yes]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
- Without --yes, this command only previews. --dry-run is fully offline. The scoped flow checks only the target resource and its transitive dependencies; unrelated resources are not refreshed or drift-checked.
- The YAML key is derived from SKILL.md frontmatter name. Remote URLs remain available through handwritten YAML plus full apply.
#### Examples
```bash
bl managed-agent skill create --source ./skills/code-review
```
```bash
bl managed-agent skill create --source ./skill.zip --yes
```
### `bl managed-agent skill download`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent skill download` |
| **Description** | Download a Managed Agent skill version |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent skill download --skill-id <id> --skill-version <version> --output-file <path> [--force]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent skill download --skill-id skill_abc --skill-version 3 --output-file ./skill.zip
```
### `bl managed-agent skill get`
| Field | Value |
| ------------------ | -------------------------------------------- |
| **Name** | `managed-agent skill get` |
| **Description** | Get a Managed Agent skill |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent skill get --skill-id <id>` |
#### Flags
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | --------------------------------------- |
| `--file <path>` | string | no | Config file path (default: agents.yaml) |
| `--skill-id <id>` | string | yes | Skill ID |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent skill get --skill-id skill_abc
```
### `bl managed-agent skill list`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------------ |
| **Name** | `managed-agent skill list` |
| **Description** | List Managed Agent skills |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent skill list [--source custom\|official\|all] [--limit <n>] [--page <cursor>] [--all]` |
#### Flags
| Flag | 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 <custom\|official\|all>` | string | no | Skill catalog: custom (default), official, or all |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
- --source all combines one page from each catalog, or every page with --all; it does not accept --page.
#### Examples
```bash
bl managed-agent skill list
```
```bash
bl managed-agent skill list --source official
```
```bash
bl managed-agent skill list --source all --all --output json
```
### `bl managed-agent skill search`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent skill search` |
| **Description** | Search Managed Agent skills |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent skill search --query <text> [--source custom\|official\|all] [--limit <n>] [--page-limit <n>]` |
#### Flags
| Flag | 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 <custom\|official\|all>` | string | no | Skill catalog: custom (default), official, or all |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent skill search --query browser --source official
```
```bash
bl managed-agent skill search --query report --source all --output json
```
### `bl managed-agent skill versions`
| Field | Value |
| ------------------ | ----------------------------------------------------------------------------------------- |
| **Name** | `managed-agent skill versions` |
| **Description** | List Managed Agent skill versions |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent skill versions --skill-id <id> [--limit <n>] [--page <cursor>] [--all]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent skill versions --skill-id skill_abc
```
```bash
bl managed-agent skill versions --skill-id skill_abc --all --output json
```
### `bl managed-agent skill-list`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------------ |
| **Name** | `managed-agent skill-list` |
| **Description** | List Managed Agent skills |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent skill-list [--source custom\|official\|all] [--limit <n>] [--page <cursor>] [--all]` |
#### Flags
| Flag | 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 <custom\|official\|all>` | string | no | Skill catalog: custom (default), official, or all |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
- --source all combines one page from each catalog, or every page with --all; it does not accept --page.
#### Examples
```bash
bl managed-agent skill-list
```
```bash
bl managed-agent skill-list --source official
```
```bash
bl managed-agent skill-list --source all --all --output json
```
### `bl managed-agent state import`
| Field | Value |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent state import` |
| **Description** | Import an existing remote resource into agents state |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent state import --address <bailian.type.name> --remote-id <id> [--resource-version <n>] [--file <path>]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------- | ------ | -------- | ------------------------------------------------------ |
| `--address <bailian.type.name>` | string | yes | Resource state address (required) |
| `--remote-id <id>` | string | yes | Existing remote resource ID to import (required) |
| `--resource-version <n>` | number | no | Resource version (for versioned resources like agents) |
| `--file <path>` | string | no | Config file path (default: agents.yaml) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent state import --address bailian.agent.assistant --remote-id agent-abc123
```
### `bl managed-agent state list`
| Field | Value |
| ------------------ | --------------------------------------------- |
| **Name** | `managed-agent state list` |
| **Description** | List resources tracked in agents state |
| **Authentication** | No Auth |
| **Usage** | `bl managed-agent state list [--file <path>]` |
#### Flags
| Flag | Type | Required | Description |
| --------------- | ------ | -------- | --------------------------------------- |
| `--file <path>` | string | no | Config file path (default: agents.yaml) |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Runs fully offline against local files: no login or provider credentials required.
#### Examples
```bash
bl managed-agent state list
```
```bash
bl managed-agent state list --file agents.yaml
```
### `bl managed-agent state rm`
| Field | Value |
| ------------------ | ----------------------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent state rm` |
| **Description** | Remove a resource from state without destroying it remotely |
| **Authentication** | No Auth |
| **Usage** | `bl managed-agent state rm --address <provider.type.name> [--file <path>]` |
| **Risk** | `high` |
| **Risk message** | This removes the resource from local state without deleting it remotely, so this project will no longer track it. |
> **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
#### Flags
| Flag | Type | Required | Description |
| -------------------------------- | ------ | -------- | --------------------------------------- |
| `--address <provider.type.name>` | string | yes | Resource state address (required) |
| `--file <path>` | string | no | Config file path (default: agents.yaml) |
| `--yes` | switch | no | Confirm this high-risk operation |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Runs fully offline against local files: no login or provider credentials required.
#### Examples
```bash
# Only after explicit user confirmation:
bl managed-agent state rm --address bailian.agent.assistant --yes
```
### `bl managed-agent state show`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------------- |
| **Name** | `managed-agent state show` |
| **Description** | Show details of a resource in agents state |
| **Authentication** | No Auth |
| **Usage** | `bl managed-agent state show --address <provider.type.name> [--file <path>]` |
#### Flags
| Flag | Type | Required | Description |
| -------------------------------- | ------ | -------- | --------------------------------------- |
| `--address <provider.type.name>` | string | yes | Resource state address (required) |
| `--file <path>` | string | no | Config file path (default: agents.yaml) |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Runs fully offline against local files: no login or provider credentials required.
#### Examples
```bash
bl managed-agent state show --address bailian.agent.assistant
```
### `bl managed-agent validate`
| Field | Value |
| ------------------ | ----------------------------------------------- |
| **Name** | `managed-agent validate` |
| **Description** | Validate an agents.yaml configuration (offline) |
| **Authentication** | No Auth |
| **Usage** | `bl managed-agent validate [--file <path>]` |
#### Flags
| Flag | Type | Required | Description |
| --------------- | ------ | -------- | --------------------------------------- |
| `--file <path>` | string | no | Config file path (default: agents.yaml) |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Runs fully offline against local files: no login or provider credentials required.
#### Examples
```bash
bl managed-agent validate
```
```bash
bl managed-agent validate --file agents.yaml
```
### `bl managed-agent vault create`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent vault create` |
| **Description** | Declare and create one empty Managed Agent Vault through a scoped YAML apply |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent vault create --name <name> [--metadata <key=value>...] [--file <path>] [--yes]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
- Without --yes, this command only previews. --dry-run is fully offline. The scoped flow checks only the target resource and its transitive dependencies; unrelated resources are not refreshed or drift-checked.
- Creates an empty Vault. Add secrets later with `vault credential create`.
#### Examples
```bash
bl managed-agent vault create --name Production
```
```bash
bl managed-agent vault create --name Production --metadata owner=platform --yes
```
### `bl managed-agent vault credential create`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent vault credential create` |
| **Description** | Append and create one environment-variable Credential in a tracked Vault |
| **Authentication** | API Key |
| **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]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
- Without --yes, this command only previews. --dry-run is fully offline. The scoped flow checks only the target resource and its transitive dependencies; unrelated resources are not refreshed or drift-checked.
- --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.
#### Examples
```bash
bl managed-agent vault credential create --vault production --name api-token --secret-name API_TOKEN --secret-env PROD_API_TOKEN
```
```bash
bl managed-agent vault credential create --vault production --name api-token --secret-name API_TOKEN --secret-env PROD_API_TOKEN --yes
```
### `bl managed-agent vault get`
| Field | Value |
| ------------------ | -------------------------------------------- |
| **Name** | `managed-agent vault get` |
| **Description** | Get a Managed Agent vault |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent vault get --vault-id <id>` |
#### Flags
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | --------------------------------------- |
| `--file <path>` | string | no | Config file path (default: agents.yaml) |
| `--vault-id <id>` | string | yes | Vault ID |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent vault get --vault-id vault_abc
```
### `bl managed-agent vault list`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------ |
| **Name** | `managed-agent vault list` |
| **Description** | List Managed Agent vaults |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent vault list [--limit <n>] [--page <cursor>] [--all] [--include-archived]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent vault list
```
```bash
bl managed-agent vault list --all --output json
```
### `bl managed-agent vault search`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| **Name** | `managed-agent vault search` |
| **Description** | Search Managed Agent vaults |
| **Authentication** | API Key |
| **Usage** | `bl managed-agent vault search --query <text> [--limit <n>] [--page-limit <n>] [--include-archived]` |
#### Flags
| Flag | 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 |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- bl managed-agent supports the Bailian provider only; configurations containing other providers are rejected.
- Bailian credentials come from bl's auth chain: --api-key > DASHSCOPE_API_KEY > `bl auth login` (active config profile).
- Resolved credentials are injected into the SDK in-memory and cleared from the environment; they never persist in process env.
#### Examples
```bash
bl managed-agent vault search --query github
```
```bash
bl managed-agent vault search --query production --page-limit 20 --output json
```
SKILL.md
---
name: bailian-managed-agent
metadata:
version: "1.21.0"
requires:
bins: ["bl"]
description: >-
阿里云百炼托管 Agent 声明式基础设施与 API 命令入口：用户要创建agent、初始化 agents.yaml、校验或预览配置变更、
创建/更新/销毁托管 Agent 或 Deployment、在 Workbench 编辑和调试目录项目、管理本地快照版本，或查询
Agent/Environment/Skill/Vault/Deployment、管理 Session/Event/File、运行/暂停 Deployment 时使用
`bl managed-agent`。持久资源仍以 agents.yaml 为唯一事实源做 IaC；公开 API 能力按资源透出
list/get/search/versions/download、数据面和运行时动作命令。apply / destroy 与破坏性 API 命令受统一高风险确认闸门保护；
务必先展示预览再让用户确认，禁止自动添加 `--yes`。
反触发：调用已上线的百炼应用/智能体走 bailian-app-call 或 `bl app`；宿主 agent 自身的记忆、技能、
子代理不走本 skill；生图生视频走 bailian-gen。
官方安装：`bl skill init`（与共享协议 bailian-protocol 同装）。
---
# Bailian managed agent IaC (`bl managed-agent`)
**CRITICAL — Before executing, MUST read the shared protocol in [`../bailian-protocol/SKILL.md`](../bailian-protocol/SKILL.md): High-risk operation confirmation, Version & updates (pre-flight checklist), and CLI errors: report an issue. Command details are authoritative in [`reference/managed-agent.md`](reference/managed-agent.md) and `bl managed-agent --help` — do not guess flags. If that protocol file is missing, stop and run `bl skill init`; do not guess auth/consent.**
## Safety guardrail (the most important rule)
`apply` / `destroy` and single-resource `create --yes` **mutate persistent remote resources**:
1. For `agents.yaml` resource changes, always run `bl managed-agent plan` first and show the diff to the user.
2. A single-resource create command previews its scoped plan when `--yes` is absent; show that preview before retrying it with `--yes`.
3. Only after explicit user confirmation, retry `apply` / `destroy` / single-resource create with `--yes`.
4. Never add `--yes` on your own initiative before the user has confirmed.
API-oriented commands do not replace IaC. Agent / Environment / Skill / Vault / Deployment 的 create 命令仍通过
`agents.yaml → scoped plan → scoped apply` 管理；查询命令和 Session、Event、File、Deployment 运行时动作直接调用 API。
`session archive|delete`、`file delete`、`deployment run|pause|unpause` 也需要先 `--dry-run`，确认后才传 `--yes`。
`state rm`, `session archive|delete`, `file delete`, `deployment run|pause|unpause`, and future
`risk: high` commands follow the shared protocol: show the risk message and exact scope, then wait
for explicit confirmation before re-running with `--yes`.
## IaC lifecycle
```
1. Init bl managed-agent init # scaffold agents.yaml
2. Validate bl managed-agent validate # offline, no network calls
3. Preview bl managed-agent plan # show the pending change diff
4. Confirm show the plan and ask the user # no automatic --yes
5. Apply bl managed-agent apply --yes # only after explicit confirmation
6. Destroy bl managed-agent destroy --yes # separate explicit confirmation
```
## Directory projects, Workbench, and local versions
| Intent | Command |
| --------------------------------------- | ------------------------------------------------------ |
| Create or convert a directory project | `bl managed-agent project init` |
| Validate and Build directory source | `bl managed-agent project validate` / `build` |
| Publish the current immutable Build | `bl managed-agent project publish --yes` |
| Launch project resource editing | `bl managed-agent project workbench` |
| Launch one Agent Session Preview | `bl managed-agent playground --agent <id>` |
| Enable/disable project versions | `bl managed-agent project version enable` / `disable` |
| Inspect local version state and history | `bl managed-agent project version status` / `list` |
| Preview or restore project source | `bl managed-agent project version preview` / `restore` |
- Bailian CLI and Workbench use the same `.openagentpack/versions/project` store and enable switch. Git is not required.
- Directory projects always use Bailian. `project.json` does not declare a Provider; Build supplies the Bailian Provider configuration automatically.
- Fresh `project init` includes complete Skill/File/Vault/Environment examples with bilingual README files under `agents/assistant/<resource-type>/_examples/`. They are not linked in `agent.json` and are excluded from Build discovery, Workbench declarations, and remote Publish. Copy a resource outside `_examples/` and configure its Agent reference to use it. Examples remain local versioned source; never put real secrets into them. / 新项目的四类资源示例默认不启用、不发布；请按 README 复制到 `_examples/` 外再配置引用，不要向示例写入真实密钥。
- `project init`, `validate`, `build`, and version commands are local-only. Publish and Workbench resolve credentials from Bailian CLI flags, shell environment, or the active Profile; project initialization does not write credentials into the project directory.
- Build is local-only. Publish never runs Build implicitly and consumes only a current `.openagentpack/build/agents.yaml` plus manifest.
- Build moves literal Vault `secret_value` / `access_token` values from Agent-local or shared `vault.json` into project-root `.env`, replacing them with generated environment references. Existing references and `.env` entries are preserved; conflicts receive suffixed variable names. Preview/dry-run never write or print secrets. Publish and Workbench read the selected project's root `.env` as a fallback to inherited environment variables, even when invoked elsewhere. `.env` is private plaintext storage, excluded from local versions but not automatically ignored by Git; keep it backed up securely.
- Build 会将 Agent 本地或共享 `vault.json` 中的明文密钥移入项目根目录 `.env`，再写回环境变量引用；保留已有引用和变量，重名时生成后缀。预览不写文件或输出密钥。`.env` 不进入版本快照，也不加密；请自行备份并加入 Git 忽略规则。
- Agent-local File and Skill content supports Build-time association. A File may be copied directly into `agents/<agent>/files/`, or placed in `agents/<agent>/files/<id>/` when that directory contains exactly one content file; Build generates `file.json` and a `/mnt/<filename>` entry in `agent.json.files`. A directory under `agents/<agent>/skills/<id>/` containing `SKILL.md` generates `skill.json` and its `agent.json.skills` entry. Explicit JSON always wins; shared root resources remain explicit. Resources referenced by multiple Agents are promoted to the corresponding root shared directory during Build.
- A successful Publish versions the canonical YAML and the complete project source tree, including Skill scripts/assets and binary files. Remote State is never versioned or restored.
- `project version restore` restores source files to the working directory, invalidates Build, and does not move version history or remote State.
- `managed-agent playground` remains the standalone `agents.yaml` Session Preview path; directory Workbench is only under `managed-agent project workbench`.
## Scoped single-resource create
以下命令都先构造 `agents.yaml` 声明，再通过 SDK 的定向 Plan/Apply 创建远端资源，不绕过 State：
| Resource | Command |
| --------------------- | ------------------------------------------ |
| Agent | `bl managed-agent agent create` |
| Environment | `bl managed-agent environment create` |
| Custom Skill | `bl managed-agent skill create` |
| Empty Vault | `bl managed-agent vault create` |
| Credential in a Vault | `bl managed-agent vault credential create` |
| Deployment | `bl managed-agent deployment create` |
- 用户只提供资源 `name`；CLI 自动生成稳定的 YAML 逻辑 key，同名资源用递增后缀并存。Credential 追加到指定 Vault，不单独生成 key。
- `agent create --skill <id>` 直接绑定已存在的远端 Skill，不要求顶层 `skills` 声明；默认写为 `type: custom`，平台 Skill 显式增加 `--type official`。同一次命令中的全部 `--skill` 共用该类型。
- `agent create --skill-dir <path>` 接收可重复的本地 Skill 目录或 ZIP：CLI 从其中的 `SKILL.md` 读取 name，自动生成顶层 `skills.<key>` 声明，并把该 key 写入 Agent 的 `skills` 列表；定向 Apply 会先上传 custom Skill，再创建 Agent。`--type` 只作用于 `--skill <id>`，不改变本地 Skill 的 custom 类型。
- Environment 和 Vault 属于 Session/Deployment 运行时绑定，不是 Agent 创建参数；在 `session create|run` 或 `deployment create` 中传入。
- 默认只预览自动 key 和定向计划；`--dry-run` 完全离线，只有显式 `--yes` 才写 YAML 并创建远端资源。
- 定向流程只刷新目标资源及其传递依赖；无关资源不检测 Drift、不产生 action，也不阻塞。
- 目标资源必须是 `create`，相关依赖必须已经处于 `no-op`；项目级 Drift 和删除仍由全量 `plan/apply` 处理。
- 远端创建失败时保留 YAML 声明；修复相关依赖或 Provider 错误后，重复相同命令会复用待创建 key。
- `skill create` 接受本地目录、ZIP 或单个 `SKILL.md`；远程 URL 仍需手工声明到 YAML，再执行全量 Apply。
### Credential secret input
`vault credential create --secret-env <ENV_NAME>` 中的参数是变量名，不是 Secret 明文。Secret 可来自 Shell export、CI Secret 注入或可选的 `.env`；CLI 会从当前目录向上自动加载最近的 `.env`，用户不必创建该文件。
```bash
export PROD_API_TOKEN="..."
bl managed-agent vault credential create \
--vault production \
--name api-token \
--secret-name API_TOKEN \
--secret-env PROD_API_TOKEN
```
- YAML 只保存 `secret_value: ${PROD_API_TOKEN}`，输出、诊断和 State 都不保存明文。
- 不要提交 `.env`；若使用 `.env`，先确认项目 `.gitignore` 已忽略它。
- 预览后再带 `--yes` 重试。后续执行全量 Apply 时也必须提供同名环境变量。
具体 flags、usage 和 examples 以 `reference/` 或对应命令的 `--help` 为准。
## Deployment as IaC
Deployment 与 Agent 一样声明在 `agents.yaml` 中，并复用同一条 `validate → plan → apply → destroy` IaC 链路；
`deployment create` 可追加一条声明并走定向 Apply；CLI 不提供绕过 state 的 Deployment create/update/delete。最小配置：
```yaml
deployments:
daily-report:
agent: assistant
initial_events:
- type: user.message
content: "Generate today's report."
```
- `apply` 会在百炼创建原生 Deployment；`destroy` 会归档已跟踪的远端 Deployment。
- `schedule` 会在 `apply` 后由百炼服务端执行。若旧流程已有外部 cron / CI，先检查 `plan`，避免重复触发。
- `initial_events` 至少包含一个 `user.message` 或 `system.message`；`user.define_outcome` 在百炼会被丢弃并产生诊断。
- 本地文件资源在 `apply` 时上传，`mount_path` 必须位于 `/mnt`，且归一化后不能重复。
- 旧版模拟 Deployment 的 state 可能记录空 `remote_id`；升级后 `plan` 会显示 materialize 更新，确认后再 `apply`。
## Session interaction (chat with a deployed managed agent)
| Intent | Command |
| ------------------------------------- | -------------------------------------------------- |
| Create + send + stream in one step | `bl managed-agent session run` |
| Send a message to an existing session | `bl managed-agent session send` |
| Create / inspect / list sessions | `bl managed-agent session create` / `get` / `list` |
| List session event history | `bl managed-agent session events` |
| Delete a session | `bl managed-agent session delete` |
规范路径是 `session event list|send|stream`；`session events` 保留为 `session event list` 的兼容别名。
Managed Agents 的子线程通过 Event 中的 `session_thread_id` 暴露；公开 API 当前没有独立 Thread 资源 CRUD，
不要构造 `session thread list|get|archive|events` 命令。
## API-oriented resource commands
| Intent | Command family |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Discover agents and versions | `agent list`, `agent get`, `agent search`, `agent versions` |
| Discover environments | `environment list`, `environment get`, `environment search` |
| Discover skills and download a version | `skill list`, `skill get`, `skill search`, `skill versions`, `skill download` |
| Inspect vault envelopes | `vault list`, `vault get`, `vault search` |
| Inspect deployments and run history | `deployment list`, `deployment get`, `deployment search`, `deployment runs list`, `deployment runs get` |
| Run or pause deployments | `deployment run`, `deployment pause`, `deployment unpause` |
| Manage session metadata/lifecycle | `session list`, `session get`, `session search`, `session update`, `session archive`, `session delete` |
| Work with raw events | `session event send`, `session event list`, `session event stream` |
| Diagnose/export a session | `session debug`, `session export` |
| Work with files | `file upload`, `file list`, `file get`, `file search`, `file download`, `file delete` |
- 所有 Cursor 都是不透明字符串：只回传 `next_page`，不得转换为数字页码。
- 客户端搜索默认最多扫描 10 页；需要扩大范围时显式传 `--page-limit`。Deployment 搜索直接映射服务端 `keyword`。
- 下载必须给出 `--output-file`；默认不覆盖已有文件，只有用户确认后才可加 `--force`。
- `session export` 只导出诊断元数据，不含 File 正文，并会脱敏凭证类字段。
- 公开 Managed Agents API 没有模型 Catalog，也没有 MCP OAuth Login；CLI 不注册对应命令。
## Local state management
| Intent | Command |
| ------------------------------------------ | -------------------------------------- |
| Inspect tracked resources | `bl managed-agent state list` / `show` |
| Adopt an existing remote resource to state | `bl managed-agent state import` |
| Untrack only (do not destroy remotely) | `bl managed-agent state rm` |
- Always make the difference clear to the user: `state rm` only edits the local state file, while `destroy` deletes the remote resource.
Flags, usage, and examples: see [`reference/`](reference/index.md) or `bl <command> --help` — do not guess flags.
## Common hand-offs
软 hand-off（按 skill **名**；已安装则 Read，否则 `--help` / 提示 `bl skill init`）：
- Call an already published Bailian app/assistant → `bailian-app-call`, or skill `bailian-cli` (`bl app list` / `call`; fallback: `bl app --help`).
- Choosing the model referenced in agents.yaml → `bailian-model-recommend`.
- Deployment quota / billing questions → skill `bailian-cli` (fallback: `bl quota` / `bl usage --help`).
## references
- [bailian-protocol](../bailian-protocol/SKILL.md) — shared protocol (install via `bl skill init`)
- [reference/](reference/index.md) — command details