# 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.0`** (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 --input '{"url":"..."}' --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 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 ` | `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 (20 CLI-shipped starters) Blueprints ship with the CLI and are offline, version-locked to the CLI release. ```bash af blueprints list --json # all 20 af blueprints list --kind workflow --json # rungs 0-2 (4 blueprints) af blueprints list --kind agent --json # rung 3 (3 blueprints) af blueprints list --kind workforce --json # rung 6 (13 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. 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-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 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. > **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 ``` ## 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` (v1.10.0). 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 --- # 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/cli.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.