> 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/cli.md). # AgenticFlow CLI The AgenticFlow CLI (`agenticflow`, alias `af`) is a command-line interface for operating the AgenticFlow platform. It is designed for: * **AI agents** that execute platform operations autonomously * **Engineers** scripting automation and CI/CD pipelines * **Human operators** who prefer a shell-first workflow Current published version: **`@pixelml/agenticflow-cli@1.10.7`** (SDK `@pixelml/agenticflow-sdk@1.6.0`). ## Install ```bash # Run without installing npx @pixelml/agenticflow-cli doctor # Or install globally (recommended for daily use) npm install -g @pixelml/agenticflow-cli ``` Requires **Node.js 18+**. The CLI is available as both `agenticflow` and `af` (short alias). ## Quick Start ```bash # 1. Authenticate (interactive — prompts for API key, workspace, project) af login # 2. One-shot orientation — auth, agents, workforces, blueprints, playbooks, what's new af bootstrap --json # 3. Deploy a starter — pick the simplest shape that fits your need af workflow init --blueprint summarize-url --json # rung 2: URL → LLM summary af agent init --blueprint research-assistant --json # rung 3: agent with web-search plugins af workforce init --blueprint parallel-research --json # rung 6: 4-agent fan-out DAG # 4. Run it af workflow run --workflow-id --body '{"url":"..."}' --wait --json af agent run --agent-id --message "..." --json af workforce run --workforce-id --trigger-data '{"message":"..."}' ``` For AI agents: start every session with `af bootstrap --json`. It returns everything you need — auth state, agents, workforces, models, blueprints (with `kind` + `complexity` + `deploy_command`), playbooks, changelog, and a commands cheat-sheet — in a single call. ## The composition ladder The three deploy verbs — `workflow`, `agent`, `workforce` — are rungs on a complexity ladder. **Start at the lowest rung that solves the user's problem.** | Rung | Kind | Deploy | What it does | | ---- | --------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | 0 | workflow | `af workflow init --blueprint llm-hello` | trigger → llm → output (hello world) | | 1 | workflow | `af workflow init --blueprint llm-chain` | llm\_plan → llm\_execute (chained reasoning) | | 2 | workflow | `af workflow init --blueprint summarize-url` | web\_retrieval → llm (enriched) | | 2 | workflow | `af workflow init --blueprint n8n-converter` | n8n workflow JSON → AgenticFlow workflow JSON + setup guide | | 2 | workflow | `af workflow init --blueprint api-summary` | api\_call → llm | | 3 | agent | `af agent init --blueprint research-assistant` | single agent + plugins (flexible) | | 3 | agent | `af agent init --blueprint content-creator` | agent with web\_search + generate\_image | | 3 | agent | `af agent init --blueprint api-helper` | agent with api\_call + json parsing | | 6 | workforce | `af workforce init --blueprint parallel-research` | 4-agent fan-out/fan-in DAG | | 6 | workforce | `af workforce init --blueprint autonomous-desk` | planner → route gate → researcher/workflow → critic → revision → editor | | 6 | workforce | `af workforce init --blueprint ` | `dev-shop` · `marketing-agency` · `sales-team` · `content-studio` · `support-center` · `amazon-seller` · `tutor` · `freelancer` | Rungs 4-5 (agent + workflow-as-tool; agent + sub-agents) are on the roadmap. See `af playbook composition-ladder` for the decision rule in full. ## Blueprints (379 CLI-shipped starters) Blueprints ship with the CLI and are offline, version-locked to the CLI release. ```bash af blueprints list --json # all 379 in v1.10.7 af blueprints list --kind workflow --json # rungs 0-2 (362 blueprints) af blueprints list --kind agent --json # rung 3 (3 blueprints) af blueprints list --kind workforce --json # rung 6 (14 blueprints) af blueprints list --complexity 0 --json # just the simplest rung af blueprints get --id summarize-url --json # full details of one af blueprints show --id summarize-url --json # alias for `get` ``` Workflow blueprints need one LLM-provider connection (Straico, OpenAI, Anthropic, Google, DeepSeek, Groq) in the workspace — `af workflow init` auto-discovers it. The catalog now includes the original ladder starters plus many ready-to-run workflow packs, including `n8n-converter`, `email-to-structured`, `rss-digest-email`, `competitor-url-snapshot`, and `job-app-package`. Agent and workforce blueprints don't need any pre-configured connections for the built-in-plugin ones. ## Marketplace (live catalog) Complements blueprints. The marketplace is the **live, backend-hosted catalog** of user- and admin-curated templates (agent, workflow, MAS/workforce). Updated independently of the CLI. ```bash af marketplace list --json # browse everything af marketplace list --type agent_template --search "seo" --json af marketplace list --type mas_template --json # multi-agent workforces af marketplace get --id --json # full details + embedded template af marketplace try --id --dry-run --json # preview clone payload af marketplace try --id --json # clone into your workspace ``` `af marketplace try` auto-detects the item's type and delegates to the right duplicate flow. See `af playbook marketplace-vs-blueprint` for when to use each. ## Authentication | Method | Usage | Best For | | -------------------- | ---------------------------------- | ----------------------- | | Interactive login | `af login` | First-time setup | | Environment variable | `export AGENTICFLOW_API_KEY=` | CI/CD, automated agents | | CLI flag | `--api-key ` | One-off scripts | | Import from `.env` | `af auth import-env --file .env` | Batch import | ```bash af login # Saves to ~/.agenticflow/auth.json af whoami --json af doctor --json --strict # Preflight with explicit exit codes (for CI) ``` ### 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 on legacy commands | | `AF_SHOW_DEPRECATED` | Set `=1` to UN-hide `af pack`, `af paperclip`, `af company` in `--help` (hidden by default) | | `AF_INSECURE_TLS` | Set `=1` to opt-in to insecure TLS (off by default — useful only for self-signed dev backends) | ## AI-Agent Discovery — start here Eight discovery commands cover everything you need to know about your workspace and the CLI surface: ```bash af bootstrap --json # The one-shot orientation — START HERE af context --json # AI-agent usage guide with invariants + journey af schema # List all resource schemas af schema agent # Agent create/update/stream shape af schema agent --field mcp_clients # Drill into a nested field af schema workforce --field schema # Workforce graph shape (nodes + edges) af blueprints list --kind --json # CLI-shipped starters by ladder rung af marketplace list --json # Live backend catalog af playbook # All guided playbooks af playbook composition-ladder # The routing rule — pick the lowest rung af changelog --json # What changed after an upgrade ``` ## Core Commands ### Workflows (rungs 0-2 — deterministic) ```bash af workflow init --blueprint --json # Deploy a workflow blueprint af workflow list --fields id,name,status --json af workflow get --workflow-id --json af workflow validate --body @wf.json --local-only af workflow create --body @wf.json --json af workflow run --workflow-id --input '{"url":"..."}' --json af workflow run --workflow-id --body '{"url":"..."}' --json # --body alias af workflow run --workflow-id --body '{"url":"..."}' --wait --json af workflow run-status --workflow-run-id --json af workflow run-status --run-id --json # --run-id alias af workflow delete --workflow-id --json ``` ### Agents (rung 3 — flexible) ```bash af agent init --blueprint --json # Deploy a Tier-1 agent blueprint af agent list --fields id,name,model --json af agent list --name-contains silk --fields id,name --json af agent get --agent-id --json af agent get --id --json # --id alias af agent get --id --fields name,model,plugins --json af agent create --body @agent.json --dry-run --json # Always validate first af agent create --body @agent.json --json af agent update --agent-id --patch --body '{"system_prompt":"..."}' af agent delete --agent-id --json af agent run --agent-id --message "..." --json af agent run --agent-id --thread-id --message "continue" af agent stream --agent-id --body @messages.json ``` `af agent update --patch` is the recommended iteration path — send only the fields you want to change, and the CLI preserves your MCP clients, tools, code-execution config, and other settings. ### Workforces (rung 6 — multi-agent DAG) ```bash af workforce init --blueprint --name "My Team" --dry-run --json # Preview af workforce init --blueprint --name "My Team" --json # Create af workforce init --blueprint autonomous-desk --json # Self-correcting desk topology af workforce init --blueprint autonomous-desk \ --tool-workflow-id \ --tool-workflow-purpose "stock watchlist brief" \ --tool-workflow-input '{"ticker":"{{nodes.agent_planner.output.structured_output.workflow_input_primary}}"}' \ --json af workforce list --fields id,name --json af workforce schema --workforce-id --json # Full graph af workforce deploy --workforce-id --body @graph.json --json # Atomic graph replace af workforce validate --workforce-id --json # Cycle detection af workforce run --workforce-id --trigger-data '{"message":"..."}' af workforce versions list --workforce-id --json af workforce versions publish --workforce-id --version-id af workforce publish --workforce-id --json # Mint public URL af workforce delete --workforce-id --json ``` `af workforce init --blueprint ` creates one real agent per required blueprint slot (with plugins pre-attached for the batteries-included blueprints), wires them into a DAG, and returns the workforce ID plus every created agent ID — all in one response. Atomic rollback on failure. Use `autonomous-desk` when you need a self-correcting research or planning mission. The desk blueprint wires planner, route gate, researcher or deterministic workflow route, critic QA gate, revision loop, and editor. If you hand-author a graph instead, read `af playbook mas-graph-building` first; it documents the `.output` template hop, condition branches, state variable merging, structured-output schemas, and workflow-in-workforce invocation rules. > **Known limitation**: `af workforce run` currently fails on API-key auth (backend returns 400 on user lookup). The CLI detects this and prints a 3-step workaround (publish + public SSE run). `af workforce publish` + a direct `curl` call to the public endpoint is the reliable path until the backend fix lands. ### MCP clients (external tool providers) ```bash af mcp-clients list --name-contains "google sheets" --fields id,name --json af mcp-clients list --verify-auth --json # Reconcile stale auth flags af mcp-clients get --id --json af mcp-clients inspect --id --json # Classify pattern + flag risks ``` Always inspect an MCP client before attaching it to an agent. The `inspect` command classifies the tool-schema pattern (Composio structured vs Pipedream single-instruction) and warns when parametric write operations are likely to fail. See: `af playbook mcp-client-quirks`. ### Marketplace templates ```bash af marketplace list --type agent_template|workflow_template|mas_template --json af marketplace get --id --json af marketplace try --id --json # Auto-detects type + clones af templates duplicate agent --template-id --json # Clone an agent template directly af templates duplicate workflow --template-id --json af templates duplicate workforce --template-id --json # New in v1.8+ af templates sync --json # Cache all templates locally ``` ### Company (portable agent-bundle I/O) \[hidden — legacy] ```bash AF_SHOW_DEPRECATED=1 af company export --output company-export.yaml AF_SHOW_DEPRECATED=1 af company diff company-export.yaml --json AF_SHOW_DEPRECATED=1 af company import --merge company-export.yaml --conflict-strategy local ``` `af company *` is hidden from default `--help`. Prefer `af workforce export/import` for new work. ## Playbooks — guided paths Playbooks are step-by-step walkthroughs shown when you run `af playbook `: ```bash af playbook first-touch # AI-agent onboarding (START HERE) af playbook composition-ladder # The rung-picking decision rule af playbook ready-prompts # Copy-paste prompts per rung af playbook marketplace-vs-blueprint # When to use each starter catalog af playbook quickstart # Zero → working agent in 5 minutes af playbook agent-build # Agent configuration deep dive af playbook workflow-build # Workflow design checklist af playbook workflow-run # Execute + monitor workflows af playbook workforce-build # Build a workforce from scratch af playbook mcp-client-quirks # Tool-schema patterns and attach safety af playbook migrate-from-paperclip # Legacy paperclip → workforce command map af playbook gateway-setup # Multi-channel webhook gateway af playbook template-bootstrap # Start from pre-built templates af playbook n8n-to-agenticflow # Convert n8n workflow JSON into AgenticFlow workflows af playbook mas-graph-building # Field-verified rules for hand-authored MAS graphs ``` ## 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 | ## Hidden (deprecated) commands `af pack`, `af paperclip`, `af company` are hidden from default `--help` in current v1.10.x releases. They still work — set `AF_SHOW_DEPRECATED=1` to see them in `--help` output. All migration paths: * `af pack install` → `af workforce init --blueprint ` (sunset 2026-10-14) * `af paperclip init` → `af workforce init --blueprint ` (sunset 2026-10-14) * `af company *` → `af workforce export/import` (no hard sunset) ## Error Handling Every `--json` error returns a consistent 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 (e.g. `af agent list --json`) to see available IDs, or double-check the ID you passed.", "details": { "status_code": 404, "payload": { "detail": "Agent not found" } } } ``` Common codes: `local_schema_validation_failed`, `request_failed`, `operation_not_found`, `invalid_option_value`, `missing_required_option`, `workforce_init_failed`, `workforce_run_api_key_unsupported`, `completed_empty`, `missing_connection`. ## SDK A TypeScript SDK is published alongside the CLI: ```typescript import { createClient } from "@pixelml/agenticflow-sdk"; // v1.6.0+ const client = createClient({ apiKey: process.env.AGENTICFLOW_API_KEY, workspaceId: process.env.AGENTICFLOW_WORKSPACE_ID, projectId: process.env.AGENTICFLOW_PROJECT_ID, }); // Agents const agents = await client.agents.list(); await client.agents.patch(agentId, { system_prompt: "..." }); // Workflows const workflow = await client.workflows.create({ name: "...", nodes: [...] }); // Workforces const wf = await client.workforces.create({ name: "My Team" }); await client.workforces.putSchema(wf.id, { nodes, edges }); const stream = await client.workforces.run(wf.id, { trigger_data: { message: "..." } }); // Marketplace (new in SDK 1.6.0) const catalog = await client.marketplace.list({ type: "agent_template", search: "seo" }); const item = await client.marketplace.get(itemId); const templates = await client.agentTemplates.listPublic(); const masVersions = await client.masTemplates.listVersions(workforceId); ``` ## Next Steps * [CLI Command Reference](/developers/agenticflow-cli-capabilities.md) — Full command reference * [Documentation Hub](/welcome-to-agenticflow/readme.md) — How the CLI fits with the platform docs * [API Overview](/developers/api.md) — REST API documentation * [Authentication](/developers/authentication.md) — API authentication details