# CLI Command Reference Complete reference for all AgenticFlow CLI commands, as of `@pixelml/agenticflow-cli@1.10.0` (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 20 agenticflow blueprints list --kind workflow --json # rungs 0-2 agenticflow blueprints list --kind agent --json # rung 3 agenticflow blueprints list --kind workforce --json # rung 6 agenticflow blueprints list --complexity 2 --json agenticflow blueprints get --id --json # full details agenticflow blueprints show --id --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 --json agenticflow marketplace try --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 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 api-summary --json # api_call → llm agenticflow workflow init --blueprint --dry-run --json # preview payload agenticflow workflow init --blueprint --llm-connection-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 --json agenticflow workflow create --body @workflow.json agenticflow workflow update --workflow-id --body @update.json agenticflow workflow delete --workflow-id ``` ### Execution Workflow execution is a **2-step process**: start the run, then poll for status. ```bash agenticflow workflow run --workflow-id --input '{"url":"..."}' --json agenticflow workflow run --workflow-id --body '{"url":"..."}' --json # --body alias agenticflow workflow run-status --workflow-run-id --json agenticflow workflow run-status --run-id --json # --run-id alias ``` ### Run History ```bash agenticflow workflow list-runs --workflow-id --limit 50 --json agenticflow workflow run-history --workflow-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 --dry-run --json # preview payload agenticflow agent init --blueprint --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 --fields id,name --json # Client-side filter agenticflow agent get --agent-id --json agenticflow agent get --id --json # --id alias agenticflow agent get --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 --body @update.json --json # Full-body replace agenticflow agent update --agent-id --patch --body '{"system_prompt":"..."}' --json agenticflow agent delete --agent-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 --message "..." --json # Non-streaming, returns {response, thread_id} agenticflow agent run --agent-id --thread-id --message "..." # Continue a thread agenticflow agent stream --agent-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 `. 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": "", "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 --name "" --dry-run --json # Preview agenticflow workforce init --blueprint --name "" --json # Create agenticflow workforce init --blueprint --skeleton-only --json # trigger+output scaffold, no agents agenticflow workforce init --blueprint --include-optional-slots --json # fill every slot including optionals agenticflow workforce init --blueprint --model --json # override default model ``` The 13 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 | **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 ` 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. ### CRUD ```bash agenticflow workforce list --fields id,name --json agenticflow workforce get --workforce-id --json agenticflow workforce update --workforce-id --body @update.json --json agenticflow workforce delete --workforce-id --json ``` ### Graph operations ```bash agenticflow workforce schema --workforce-id --json # Full graph (nodes + edges) agenticflow workforce deploy --workforce-id --body @graph.json # Atomic graph replace agenticflow workforce validate --workforce-id --json # Cycle + dangling-edge check agenticflow workforce node-types --json # Discover available node types ``` ### Running a workforce ```bash agenticflow workforce run --workforce-id --trigger-data '{"message":"..."}' agenticflow workforce runs list --workforce-id --json agenticflow workforce runs get --run-id --json agenticflow workforce runs stop --run-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//run` endpoint. {% endhint %} ### Versions & publishing ```bash agenticflow workforce versions list --workforce-id --json agenticflow workforce versions latest --workforce-id --json agenticflow workforce versions publish --workforce-id --version-id --json agenticflow workforce versions restore --workforce-id --version-id --json agenticflow workforce publish --workforce-id --json # Generate public key + URL agenticflow workforce rotate-key --workforce-id --json ``` *** ## Blueprints CLI-shipped starter catalog (offline, version-locked to the CLI release). ```bash agenticflow blueprints list --json # all 20 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 --json # full details agenticflow blueprints show --id --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`, `deploy_command`. The `deploy_command` field tells you exactly how to deploy (`af init --blueprint --json`). *** ## 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 --json agenticflow marketplace try --id --json # auto-detects type + clones agenticflow marketplace try --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 --json # Inspect cache manifest agenticflow templates duplicate agent --template-id --json agenticflow templates duplicate workflow --template-id --json agenticflow templates duplicate workforce --template-id --json agenticflow templates duplicate workforce --workforce-id --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 --json # --client-id also works agenticflow mcp-clients inspect --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 --json agenticflow node-types list --limit 50 --json # Prefer search/get — full list is large agenticflow node-types dynamic-options --name --field-name --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 --body @update.json agenticflow connections delete --connection-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 --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":"","message":"Do X","callback_url":"https://..."}' ``` *** ## API Discovery ```bash agenticflow ops list --public-only --tag agents --json agenticflow ops show agenticflow catalog export --json agenticflow catalog rank --task "" --top 10 --json agenticflow discover --json agenticflow schema --json agenticflow schema --field --json ``` `af schema --field ` 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 v1.10.0. 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 ` (or `af agent init --blueprint ` 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 ` | 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 ` | Override API key | | `--workspace-id ` | Override workspace | | `--project-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 --input '{"url":"..."}' --json agenticflow workflow run-status --run-id --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 --message "..." --json agenticflow agent update --agent-id --patch --body '{"system_prompt":"..."}' --json # 7. If multi-agent coordination is genuinely needed, rung 6 agenticflow workforce init --blueprint parallel-research --json # 8. Cleanup agenticflow workflow delete --workflow-id --json agenticflow agent delete --agent-id --json agenticflow workforce delete --workforce-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 ` | | `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 | | `[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 | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.agenticflow.ai/developers/agenticflow-cli-capabilities.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.