> For the complete documentation index, see [llms.txt](https://docs.agenticflow.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.agenticflow.ai/developers/agenticflow-cli-capabilities.md).

# CLI Command Reference

Complete reference for all AgenticFlow CLI commands, as of `@pixelml/agenticflow-cli@1.10.7` (SDK `@pixelml/agenticflow-sdk@1.6.0`).

## The composition ladder

Three deploy verbs map 1:1 to rungs on a 7-level complexity ladder. Pick the **lowest rung** that solves the user's problem.

| Rung | Kind      | Deploy verb         | Complexity field                         |
| ---- | --------- | ------------------- | ---------------------------------------- |
| 0    | workflow  | `af workflow init`  | `complexity: 0` — minimal                |
| 1    | workflow  | `af workflow init`  | `complexity: 1` — chained LLMs           |
| 2    | workflow  | `af workflow init`  | `complexity: 2` — enriched w/ real data  |
| 3    | agent     | `af agent init`     | `complexity: 3` — agent + plugins        |
| 4    | agent     | (roadmap)           | `complexity: 4` — agent + workflow tools |
| 5    | agent     | (roadmap)           | `complexity: 5` — agent + sub-agents     |
| 6    | workforce | `af workforce init` | `complexity: 6` — multi-agent DAG        |

Use `af playbook composition-ladder` for the decision rule in full.

## Diagnostics & Discovery

```bash
agenticflow bootstrap --json       # One-shot workspace snapshot — START HERE
agenticflow context --json         # AI-agent invariants, journey, discovery helpers
agenticflow doctor --json          # Preflight check (auth, health, spec)
agenticflow doctor --json --strict # Exit 1 if required checks fail
agenticflow whoami --json          # Show current auth profile
agenticflow discover --json        # Machine-readable capability index
agenticflow changelog --json       # What shipped per version

# Schemas
agenticflow schema                               # List resources with schemas
agenticflow schema agent --json                  # Full agent create/update shape
agenticflow schema agent --field mcp_clients     # Drill into a nested field

# Blueprints (CLI-shipped starter catalog — offline, version-locked)
agenticflow blueprints list --json                           # all 379 in v1.10.7
agenticflow blueprints list --kind workflow --json           # rungs 0-2, 362 blueprints
agenticflow blueprints list --kind agent --json              # rung 3
agenticflow blueprints list --kind workforce --json          # rung 6, 14 blueprints
agenticflow blueprints list --complexity 2 --json
agenticflow blueprints get --id <slug> --json                # full details
agenticflow blueprints show --id <slug> --json               # alias for `get`

# Marketplace (live backend catalog)
agenticflow marketplace list --json
agenticflow marketplace list --type agent_template --search "seo" --json
agenticflow marketplace get --id <item_id> --json
agenticflow marketplace try --id <item_id> --json            # auto-detects + clones

# Playbooks
agenticflow playbook --list
agenticflow playbook composition-ladder     # routing rule
agenticflow playbook ready-prompts          # copy-paste prompts per rung
agenticflow playbook marketplace-vs-blueprint
agenticflow playbook n8n-to-agenticflow
agenticflow playbook mas-graph-building
agenticflow playbook first-touch
```

When `--json` is set, command failures return a structured envelope with an actionable `hint`:

```json
{
  "schema": "agenticflow.error.v1",
  "code": "request_failed",
  "message": "Request failed with status 404: Agent not found",
  "hint": "Resource not found. Run the matching `list` command to see available IDs, or double-check the ID you passed.",
  "details": {
    "status_code": 404,
    "payload": { "detail": "Agent not found" }
  }
}
```

Common codes:

| Code                                | Meaning                                                                                         |
| ----------------------------------- | ----------------------------------------------------------------------------------------------- |
| `local_schema_validation_failed`    | Payload failed client-side validation — fix fields per `details.issues`                         |
| `request_failed`                    | API returned a non-2xx — inspect `details.status_code` + `details.payload`                      |
| `invalid_option_value`              | Bad flag value (usually numeric or an unknown enum)                                             |
| `missing_required_option`           | Required flag not supplied                                                                      |
| `missing_connection`                | Workflow needs an LLM-provider connection not present in workspace                              |
| `workforce_init_failed`             | Workforce init rolled back — see `details.rolled_back_agents` + `details.rolled_back_workforce` |
| `workforce_run_api_key_unsupported` | Authenticated workforce run rejects API-key auth; CLI prints a 3-step workaround                |
| `completed_empty`                   | Agent run returned `status: completed` with empty response (recursion limit exhausted)          |

***

## Workflows (rungs 0-2)

Workflows are deterministic multi-node pipelines. Same input → same output (modulo model stochasticity).

### Blueprint-based initialization (new in v1.10.0)

```bash
agenticflow workflow init --blueprint llm-hello --json           # simplest: single LLM
agenticflow workflow init --blueprint llm-chain --json           # chained LLMs
agenticflow workflow init --blueprint summarize-url --json       # web_retrieval → llm
agenticflow workflow init --blueprint n8n-converter --json       # n8n JSON → AgenticFlow JSON
agenticflow workflow init --blueprint api-summary --json         # api_call → llm
agenticflow workflow init --blueprint <slug> --dry-run --json    # preview payload
agenticflow workflow init --blueprint <slug> --llm-connection-id <id>   # override auto-discovery
```

`af workflow init` auto-discovers the workspace's LLM-provider connection (Straico, OpenAI, Anthropic, Google, DeepSeek, Groq — in preference order). If none is found, the command emits `missing_connection` with a clear remediation hint.

### CRUD

```bash
agenticflow workflow list --fields id,name,status --json
agenticflow workflow get --workflow-id <id> --json
agenticflow workflow create --body @workflow.json
agenticflow workflow update --workflow-id <id> --body @update.json
agenticflow workflow delete --workflow-id <id>
```

### Execution

Workflow execution can be asynchronous or synchronous. Use `--wait` when you want the CLI to poll until a terminal state and return the final output inline.

```bash
agenticflow workflow run --workflow-id <id> --input '{"url":"..."}' --json
agenticflow workflow run --workflow-id <id> --body '{"url":"..."}' --json   # --body alias
agenticflow workflow run --workflow-id <id> --body '{"url":"..."}' --wait --timeout 180 --poll-interval 3 --json
agenticflow workflow run-status --workflow-run-id <run_id> --json
agenticflow workflow run-status --run-id <run_id> --json                     # --run-id alias
```

### Run History

```bash
agenticflow workflow list-runs --workflow-id <id> --limit 50 --json
agenticflow workflow run-history --workflow-id <id> --limit 50 --json
```

### Validation

```bash
agenticflow workflow validate --body @workflow.json --local-only
agenticflow workflow validate --body @workflow.json
```

### Smart Connection Resolution

When `workflow run` encounters a "Connection not found" error, the CLI automatically:

1. Fetches the workflow and identifies which nodes use the missing connection
2. Looks up the node type's `connection_category` (for example `pixelml`, `openai`)
3. Lists available connections matching that category
4. Prompts you to select a replacement
5. Updates the workflow with the new connection
6. Retries the run

This removes most manual connection-repair work when importing workflows between workspaces.

***

## Agents (rung 3)

### Blueprint-based initialization (since v1.8.0)

```bash
agenticflow agent init --blueprint research-assistant --json     # web_search + web_retrieval + api_call + string_to_json
agenticflow agent init --blueprint content-creator --json        # web + generate_image
agenticflow agent init --blueprint api-helper --json             # api_call + json parsing
agenticflow agent init --blueprint <slug> --dry-run --json       # preview payload
agenticflow agent init --blueprint <slug> --name "..." --model agenticflow/gpt-4o-mini
```

Tier-1 agent blueprints deploy a single agent with AgenticFlow-native plugins attached. Default model is `agenticflow/gpt-4o-mini` (verified to reliably call tools on "latest X" questions; override with `--model`).

### CRUD

```bash
agenticflow agent list --fields id,name,model --json
agenticflow agent list --name-contains <substr> --fields id,name --json   # Client-side filter
agenticflow agent get --agent-id <id> --json
agenticflow agent get --id <id> --json                                    # --id alias
agenticflow agent get --id <id> --fields name,model,plugins --json        # projection
agenticflow agent create --body @agent.json --dry-run --json              # Always validate first
agenticflow agent create --body @agent.json --json
agenticflow agent update --agent-id <id> --body @update.json --json       # Full-body replace
agenticflow agent update --agent-id <id> --patch --body '{"system_prompt":"..."}' --json
agenticflow agent delete --agent-id <id> --json
```

`--patch` is the recommended iteration path. It fetches the current agent, merges your partial body over it, strips server-rejected null fields automatically, and PUTs the result — preserving MCP clients, tools, code-execution config, and every other attached capability.

### Execution

```bash
agenticflow agent run --agent-id <id> --message "..." --json              # Non-streaming, returns {response, thread_id}
agenticflow agent run --agent-id <id> --thread-id <tid> --message "..."   # Continue a thread
agenticflow agent stream --agent-id <id> --body @messages.json            # SSE streaming
```

If the agent run returns `status: "completed_empty"` with an empty response, the agent hit its `recursion_limit` in a tool loop. The warning message names the thread id; inspect with `af agent-threads messages --thread-id <id>`. Remediation: refine the prompt to converge faster, or raise `recursion_limit` via `af agent update --patch`.

### Minimal Agent Payload

```json
{
  "name": "Support Agent",
  "tools": [],
  "project_id": "<your_project_id>",
  "model": "agenticflow/gpt-4o-mini",
  "system_prompt": "You are a reliable support agent."
}
```

`project_id` is **required** — agents do not auto-inject it from client config. Grab it from `af bootstrap --json > auth.project_id`.

### Stream Payload

```json
{
  "messages": [
    { "role": "user", "content": "What can you help me with?" }
  ]
}
```

***

## Workforces (rung 6)

### Blueprint-based initialization

```bash
agenticflow workforce init --blueprint <slug> --name "<name>" --dry-run --json   # Preview
agenticflow workforce init --blueprint <slug> --name "<name>" --json             # Create
agenticflow workforce init --blueprint <slug> --skeleton-only --json             # trigger+output scaffold, no agents
agenticflow workforce init --blueprint <slug> --include-optional-slots --json    # fill every slot including optionals
agenticflow workforce init --blueprint <slug> --model <model> --json             # override default model
agenticflow workforce init --blueprint autonomous-desk --json                    # self-correcting desk topology
agenticflow workforce init --blueprint autonomous-desk \
  --tool-workflow-id <workflow_id> \
  --tool-workflow-purpose "stock watchlist brief" \
  --tool-workflow-input '{"ticker":"{{nodes.agent_planner.output.structured_output.workflow_input_primary}}"}' \
  --json
```

The 14 workforce blueprints are:

**Batteries-included (plugins pre-attached — work end-to-end):**

| Blueprint           | Agents | Pattern                                                                         |
| ------------------- | ------ | ------------------------------------------------------------------------------- |
| `research-pair`     | 2      | Planner → Researcher (web\_search + web\_retrieval)                             |
| `content-duo`       | 2      | Writer (web\_search) → Illustrator (generate\_image)                            |
| `api-pipeline`      | 2      | Fetcher (api\_call) → Analyst                                                   |
| `fact-check-loop`   | 2      | Writer → Fact Checker                                                           |
| `parallel-research` | 4      | Coordinator → 2 Researchers (parallel) → Synthesizer                            |
| `autonomous-desk`   | 4      | Planner → route gate → workflow or Researcher → Critic → revision loop → Editor |

**Vertical teams — generic agents, attach your own MCP tools after deploy:**

| Blueprint          | Required slots                 | Optional slots |
| ------------------ | ------------------------------ | -------------- |
| `dev-shop`         | ceo, engineer                  | designer, qa   |
| `marketing-agency` | ceo, cmo, designer             | researcher     |
| `sales-team`       | ceo, researcher, general       | —              |
| `content-studio`   | ceo, cmo, engineer             | designer       |
| `support-center`   | ceo, general                   | researcher     |
| `amazon-seller`    | ceo, cmo, engineer, researcher | general        |
| `tutor`            | ceo, cmo, engineer, researcher | general        |
| `freelancer`       | ceo, cmo, engineer, researcher | general        |

> `tutor` and `freelancer` were added in CLI v1.7.0, absorbing the legacy `tutor-pack` and `freelancer-pack` from the deprecated `af pack *` surface.

`af workforce init --blueprint <id>` creates one real agent per required slot, then wires them into a DAG (trigger → coordinator → worker agents → output — or coordinator → parallel workers → synthesizer → output if the blueprint declares `isSynthesizer`). Uses a single atomic graph PUT; on failure, every resource created so far is automatically rolled back.

`autonomous-desk` uses the newer desk topology. It adds structured-output planner and critic agents, condition gates, state variable branch merging, an optional deterministic workflow route, and an automatic revision path before the editor ships the final response. Read `af playbook mas-graph-building` before hand-authoring or editing this class of graph.

### CRUD

```bash
agenticflow workforce list --fields id,name --json
agenticflow workforce get --workforce-id <id> --json
agenticflow workforce update --workforce-id <id> --body @update.json --json
agenticflow workforce delete --workforce-id <id> --json
```

### Graph operations

```bash
agenticflow workforce schema --workforce-id <id> --json                  # Full graph (nodes + edges)
agenticflow workforce deploy --workforce-id <id> --body @graph.json      # Atomic graph replace
agenticflow workforce validate --workforce-id <id> --json                # Cycle + dangling-edge check
agenticflow workforce node-types --json                                  # Discover available node types
```

### Running a workforce

```bash
agenticflow workforce run --workforce-id <id> --trigger-data '{"message":"..."}'
agenticflow workforce runs list --workforce-id <id> --json
agenticflow workforce runs get --run-id <id> --json
agenticflow workforce runs stop --run-id <id> --json
```

{% hint style="warning" %}
`af workforce run` currently rejects API-key auth (backend bug — returns 400 on user lookup). The CLI detects this and prints a 3-step workaround. Reliable path: `af workforce publish` to get a `public_key`, then `curl` the `/v1/workforce/public/<public_key>/run` endpoint.
{% endhint %}

### Versions & publishing

```bash
agenticflow workforce versions list --workforce-id <id> --json
agenticflow workforce versions latest --workforce-id <id> --json
agenticflow workforce versions publish --workforce-id <id> --version-id <v> --json
agenticflow workforce versions restore --workforce-id <id> --version-id <v> --json

agenticflow workforce publish --workforce-id <id> --json          # Generate public key + URL
agenticflow workforce rotate-key --workforce-id <id> --json
```

***

## Blueprints

CLI-shipped starter catalog (offline, version-locked to the CLI release).

```bash
agenticflow blueprints list --json                            # all 379 in v1.10.7
agenticflow blueprints list --kind workflow --json            # filter by kind
agenticflow blueprints list --kind agent --json
agenticflow blueprints list --kind workforce --json
agenticflow blueprints list --complexity 2 --json             # filter by rung
agenticflow blueprints list --tier 1 --json                   # legacy filter (still works)
agenticflow blueprints get --id <slug> --json                 # full details
agenticflow blueprints show --id <slug> --json                # alias for `get`
```

Response shape includes: `id`, `name`, `kind`, `complexity`, `tier` (legacy), `description`, `goal`, `use_cases`, `agents[]` (with `plugins`, `is_synthesizer`), `workflow_nodes[]`, `workflow_input_schema`, and `deploy_command`. The `deploy_command` field tells you exactly how to deploy (`af <kind> init --blueprint <id> --json`). Current v1.10.7 counts: 362 workflow blueprints, 3 agent blueprints, and 14 workforce blueprints.

***

## Marketplace

Live backend catalog — complements blueprints. Updated independently of the CLI.

```bash
agenticflow marketplace list --json
agenticflow marketplace list --type agent_template --json
agenticflow marketplace list --type workflow_template --json
agenticflow marketplace list --type mas_template --json
agenticflow marketplace list --search "seo" --featured --free --json
agenticflow marketplace list --fields id,name,type,creator --json
agenticflow marketplace get --id <item_id> --json
agenticflow marketplace try --id <item_id> --json             # auto-detects type + clones
agenticflow marketplace try --id <item_id> --dry-run --json   # preview payload
```

`marketplace try` auto-detects the item type and delegates:

* `agent_template` → reuses `af templates duplicate agent` flow (materializes tool workflows, then the agent)
* `workflow_template` → reuses `af templates duplicate workflow` flow
* `mas_template` → creates a workforce shell + PUTs nodes/edges. Warns about cross-workspace agent\_id references.

See `af playbook marketplace-vs-blueprint` for when to use marketplace vs blueprints.

***

## Templates (duplicate by id)

```bash
agenticflow templates sync --json                                # Cache all templates locally
agenticflow templates index --dir <path> --json                  # Inspect cache manifest
agenticflow templates duplicate agent --template-id <id> --json
agenticflow templates duplicate workflow --template-id <id> --json
agenticflow templates duplicate workforce --template-id <marketplace_mas_id> --json
agenticflow templates duplicate workforce --workforce-id <src_ulid> --json   # latest version of a source
```

The templates duplicate commands rebuild the create payload client-side from the template snapshot, so cloning works with API-key auth (the marketplace `/mix` endpoint currently requires user JWT).

***

## MCP Clients

```bash
agenticflow mcp-clients list --name-contains "google sheets" --fields id,name --json
agenticflow mcp-clients list --verify-auth --json             # Re-verify each client's auth state
agenticflow mcp-clients get --id <id> --json                  # --client-id also works
agenticflow mcp-clients inspect --id <id> --json              # Classify pattern, flag write-safety
```

### Inspecting before attach

`mcp-clients inspect` classifies an MCP client's tool set so you know if it's safe to attach to an agent:

| `pattern`   | Meaning                                                                                                         |
| ----------- | --------------------------------------------------------------------------------------------------------------- |
| `composio`  | Structured schemas with multiple named properties — writes work reliably                                        |
| `pipedream` | Every tool takes a single `instruction: string` property — parametric writes may stall in a configure-only loop |
| `mixed`     | Some tools are structured, some are instruction-only — restrict Pipedream tools to read-only                    |
| `unknown`   | No tools enumerated — check `classification_reason` for the root cause                                          |

The response also carries a `known_quirks` array with human-readable warnings and a pointer to `af playbook mcp-client-quirks`.

***

## Node Types

```bash
agenticflow node-types search --query "llm" --json
agenticflow node-types get --name <name> --json
agenticflow node-types list --limit 50 --json                  # Prefer search/get — full list is large
agenticflow node-types dynamic-options --name <name> --field-name <field> --json
```

{% hint style="info" %}
Prefer `get` or `search` over `list`. The full node types list is very large.
{% endhint %}

To find what kind of connection a workflow node requires, look at the `connection` field in the node-type response — `connection_category` tells you which category is needed. `connection: null` means no connection required (e.g. `web_search`, `web_retrieval`, `api_call`, `agenticflow_generate_image`, `string_to_json`).

***

## Connections

```bash
agenticflow connections list --limit 200 --json
agenticflow connections create --body @conn.json
agenticflow connections update --connection-id <id> --body @update.json
agenticflow connections delete --connection-id <id>
```

{% hint style="warning" %}
The default limit is **10**. Use `--limit 200` when you need a full workspace view.
{% endhint %}

***

## Uploads

```bash
agenticflow uploads create --body @upload.json
agenticflow uploads status --session-id <id> --json
```

***

## Gateway (webhook orchestration)

```bash
agenticflow gateway serve --channels webhook,linear --verbose
agenticflow gateway channels --json
```

Send a task via the generic webhook channel:

```bash
curl -X POST http://localhost:4100/webhook/webhook \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"<id>","message":"Do X","callback_url":"https://..."}'
```

***

## API Discovery

```bash
agenticflow ops list --public-only --tag agents --json
agenticflow ops show <operation_id>
agenticflow catalog export --json
agenticflow catalog rank --task "<description>" --top 10 --json
agenticflow discover --json
agenticflow schema <resource> --json
agenticflow schema <resource> --field <name> --json
```

`af schema <resource> --field <name>` drills into a single field's documented shape — useful for nested payloads like `mcp_clients`, `suggested_messages`, `response_format`, or the workforce graph `schema` subtree.

***

## Raw API Call

For any endpoint not wrapped by a resource subcommand, use `call`:

```bash
agenticflow call --method GET --path /v1/health --json
agenticflow call --method POST --path /v1/echo/ --body '{"message": "test"}' --json
agenticflow call --operation-id get_all_v1_agents__get --dry-run --json
```

`--dry-run` is supported on `agenticflow call` only — it validates the request shape and prints the resolved URL + body without sending.

***

## Policy & Safety

```bash
agenticflow policy show
agenticflow policy init
```

***

## Hidden (deprecated) command groups

These groups are **hidden from default `--help`** in current v1.10.x releases. They still work; set `AF_SHOW_DEPRECATED=1` to reveal them in `--help`. All migration paths resolve to blueprints or the workforce surface.

| Group            | Migration                                                                             | Sunset         |
| ---------------- | ------------------------------------------------------------------------------------- | -------------- |
| `af pack *`      | `af workforce init --blueprint <id>` (or `af agent init --blueprint <id>` for Tier 1) | 2026-10-14     |
| `af paperclip *` | `af workforce *` — see `af playbook migrate-from-paperclip`                           | 2026-10-14     |
| `af company *`   | `af workforce export/import`                                                          | No hard sunset |

Per-invocation deprecation warnings print to stderr. Silence with `AF_SILENCE_DEPRECATIONS=1`.

***

## Global Options

| Flag                  | Purpose                                                                      |
| --------------------- | ---------------------------------------------------------------------------- |
| `--json`              | Machine-readable JSON output with `schema:` discriminators                   |
| `--fields <list>`     | Return only the named fields (saves context on list commands)                |
| `--dry-run`           | Validate without executing (create and deploy commands)                      |
| `--patch`             | Partial update: fetch → merge → PUT (on `af agent update` and other updates) |
| `--api-key <key>`     | Override API key                                                             |
| `--workspace-id <id>` | Override workspace                                                           |
| `--project-id <id>`   | Override project                                                             |

## Environment Variables

| Variable                   | Purpose                                                                                                               |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `AGENTICFLOW_API_KEY`      | API key                                                                                                               |
| `AGENTICFLOW_WORKSPACE_ID` | Default workspace ID                                                                                                  |
| `AGENTICFLOW_PROJECT_ID`   | Default project ID                                                                                                    |
| `AF_SILENCE_DEPRECATIONS`  | Set `=1` to suppress deprecation warnings                                                                             |
| `AF_SHOW_DEPRECATED`       | Set `=1` to un-hide `af pack`, `af paperclip`, `af company` in `--help`                                               |
| `AF_INSECURE_TLS`          | Set `=1` to opt-in to insecure TLS (default off; CLI unsets an inherited `NODE_TLS_REJECT_UNAUTHORIZED=0` at startup) |

***

## Recommended Build Flow (for an AI agent)

```bash
# 1. Orient
agenticflow bootstrap --json

# 2. Pick a rung. Reading `blueprints[]` from bootstrap gives you kind + complexity + deploy_command.
agenticflow blueprints list --kind workflow --json   # simplest first

# 3. Preview
agenticflow workflow init --blueprint summarize-url --dry-run --json

# 4. Deploy
agenticflow workflow init --blueprint summarize-url --json

# 5. Run
agenticflow workflow run --workflow-id <id> --body '{"url":"..."}' --wait --json

# 6. If a single-agent orchestrator is a better fit, promote to rung 3
agenticflow agent init --blueprint research-assistant --json
agenticflow agent run --agent-id <id> --message "..." --json
agenticflow agent update --agent-id <id> --patch --body '{"system_prompt":"..."}' --json

# 7. If multi-agent coordination is genuinely needed, rung 6
agenticflow workforce init --blueprint parallel-research --json
agenticflow workforce init --blueprint autonomous-desk --json

# 8. Cleanup
agenticflow workflow delete --workflow-id <id> --json
agenticflow agent delete --agent-id <id> --json
agenticflow workforce delete --workforce-id <id> --json
```

***

## Troubleshooting

| Problem                                                        | Solution                                                                                                                                         |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Unsure which rung to pick                                      | Read `af playbook composition-ladder` and the `complexity` field on `af blueprints list --json`                                                  |
| `missing_connection` on `af workflow init`                     | Workflow needs an LLM-provider connection. Create one (Straico, OpenAI, Anthropic, Google, DeepSeek, or Groq) or pass `--llm-connection-id <id>` |
| `af workforce run` 400 "Failed to retrieve user info"          | Known backend bug for API-key auth. CLI prints a 3-step workaround — publish + public SSE run                                                    |
| `Connection X not found` on `workflow run`                     | Re-run the command. CLI auto-resolves using available connections                                                                                |
| `operation_not_found`                                          | Use `agenticflow ops list --json` then retry with the suggested operation id                                                                     |
| `invalid_option_value`                                         | Check numeric flags (`--limit`, `--offset`, `--top`) — integers only                                                                             |
| `local_schema_validation_failed`                               | Inspect `details.issues`, fix payload fields, rerun (try `workflow validate --local-only`)                                                       |
| `401 Error decoding token`                                     | Some endpoints require session tokens, not API keys. Use the web UI for those actions                                                            |
| `422 validation error`                                         | Read the `details.payload.detail` array — each entry names the missing/invalid field                                                             |
| `completed_empty` on agent run                                 | Agent exhausted `recursion_limit` in a tool loop. Raise the limit or refine the prompt                                                           |
| Connections list too few                                       | Default limit is 10; use `--limit 200`                                                                                                           |
| `af agent update` 422 on null fields                           | Use `--patch` — the CLI auto-strips null-rejected fields                                                                                         |
| Hand-authored workforce graph renders empty downstream prompts | Read `af playbook mas-graph-building`; node references need the `.output` hop, e.g. `{{nodes.planner.output.last_message}}`                      |
| `[deprecated]` warning noise                                   | Set `AF_SILENCE_DEPRECATIONS=1` while migrating off `af paperclip *` / `af pack *`                                                               |
| `pack`/`paperclip`/`company` hidden from `--help`              | By design — set `AF_SHOW_DEPRECATED=1` to see them, or use the replacement commands (blueprints, workforce)                                      |
| Noisy Node.js TLS warning                                      | The CLI unsets inherited `NODE_TLS_REJECT_UNAUTHORIZED=0` at startup. Set `AF_INSECURE_TLS=1` only if you genuinely need insecure TLS            |