# CLI Command Reference Complete reference for all AgenticFlow CLI commands, as of `@pixelml/agenticflow-cli@1.6.3`. ## Diagnostics ```bash agenticflow discover --json # Machine-readable capability index 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 bootstrap --json # One-shot workspace snapshot (START HERE) agenticflow context --json # AI-agent invariants, journey, discovery helpers agenticflow changelog --json # What shipped per version ``` `doctor` validates config presence, token presence, API reachability, and bundled OpenAPI loading. Use `--strict` in CI/CD to gate execution. 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) | | `missing_required_option` | Required flag not supplied | | `workforce_init_failed` | Workforce init rolled back — see `details.rolled_back_agents` + `details.rolled_back_workforce` | | `operation_not_found` | Wrong operation id on `ops show` / `call` | *** ## Agents ### 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 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 ``` ### Minimal Agent Payload ```json { "name": "Support Agent", "tools": [], "project_id": "", "model": "agenticflow/gemini-2.0-flash", "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 (multi-agent native deploy) ```bash agenticflow workforce list --fields id,name --json agenticflow workforce get --workforce-id --json agenticflow workforce init --blueprint --name "" --dry-run --json # Preview agenticflow workforce init --blueprint --name "" --json # Create 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 ``` `workforce deploy` sends a complete `{nodes, edges}` body to the atomic PUT-schema endpoint. The server diffs current vs desired and applies create/update/delete in one transaction. ### 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 ``` `workforce run` streams server-sent events (SSE) — each event appears as one JSON line. The CLI automatically wraps your `--trigger-data` payload in the `{trigger_data: ...}` envelope the server expects. ### 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 ``` ### Blueprint-based initialization The eight built-in blueprints (v1.7.0+): | 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. Use blueprints going forward. `af workforce init --blueprint ` creates one real agent per required slot, then wires them into a DAG (trigger → coordinator → worker agents → output) via a single atomic graph PUT. Use `--include-optional-slots` to create agents for the optional slots as well. Use `--skeleton-only` if you want a trigger + output scaffold and prefer to wire agents yourself. On failure, every resource created so far is automatically rolled back — the error response lists `rolled_back_agents` and `rolled_back_workforce` so you know what was undone. *** ## 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`. *** ## Workflows ### 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 @input.json --json agenticflow workflow run-status --workflow-run-id --json ``` ### 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. *** ## Company (portable agent-bundle I/O) ```bash agenticflow company export --output company-export.yaml agenticflow company diff company-export.yaml --json # Exit 0 = in sync, 1 = differences agenticflow company import company-export.yaml --json agenticflow company import company-export.yaml --merge --conflict-strategy local agenticflow company import company-export.yaml --merge --conflict-strategy remote --dry-run ``` Company export/import serializes the current workspace's agent set as YAML/JSON, making it portable between workspaces. `diff` produces a field-level comparison; `import --merge` resolves conflicts per-agent. *** ## 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. *** ## 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 playbook --list agenticflow playbook 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 ``` *** ## Legacy: Paperclip (deprecated) {% hint style="warning" %} The `agenticflow paperclip *` command group is **deprecated** and will be removed on **2026-10-14**. Use `af workforce *` instead. See `af playbook migrate-from-paperclip` for the command-by-command migration map. Suppress the per-session deprecation warning with `AF_SILENCE_DEPRECATIONS=1`. {% endhint %} The paperclip commands still work; no migration is required before the sunset date. *** ## Recommended Build Flow (for an AI agent) ```bash # 1. Orient agenticflow bootstrap --json # 2. Read a relevant playbook agenticflow playbook first-touch # 3. Inspect the payload shape you'll construct agenticflow schema agent --json agenticflow schema agent --field mcp_clients --json # 4. Validate locally agenticflow agent create --body @agent.json --dry-run --json # 5. Create agenticflow agent create --body @agent.json --json # 6. Smoke-test agenticflow agent run --agent-id --message "..." --json # 7. Iterate surgically (preserves MCP clients, tools, code_exec) agenticflow agent update --agent-id --patch --body '{"system_prompt":"..."}' --json # 8. For multi-agent teams agenticflow workforce init --blueprint --name "" --dry-run --json agenticflow workforce init --blueprint --name "" --json # 9. Cleanup agenticflow agent delete --agent-id --json agenticflow workforce delete --workforce-id --json ``` *** ## Troubleshooting | Problem | Solution | | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `Connection X not found` | Re-run the workflow. CLI can auto-resolve 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, and 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 | | `Network request failed` | Verify network/TLS/path; prefer targeted queries over large list calls | | 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 | | `af workforce run` 400 "Failed to retrieve user info" | Known server-side issue for API-key auth — not a CLI bug | | `[deprecated]` warning noise | Set `AF_SILENCE_DEPRECATIONS=1` while migrating off `af paperclip *` | | 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 it |