# 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.6.3`**. ## 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. Talk to an existing agent af agent run --agent-id --message "Hello!" --json # 4. Or deploy a ready-made multi-agent team in one command af workforce init --blueprint dev-shop --name "My Dev Team" --json ``` For AI agents: start every session with `af bootstrap --json`. It returns everything you need — auth state, agents, workforces, models, blueprints, playbooks, changelog, and a commands cheat-sheet — in a single call. ## What you can build Pick the shape of your solution based on how much orchestration you need: | You want… | Use | Why | | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | | A single chat endpoint / customer-facing bot / one assistant | `af agent create` then `af agent run` | One prompt handles routing. Iterate with `af agent update --patch` | | Multiple agents that hand off (research → write, triage → specialist, pre-built team templates) | `af workforce init --blueprint ` | One command creates the workforce, all required agents, and the wired DAG. Atomic rollback on failure | | A DAG of prompt/tool/logic nodes (not necessarily multi-agent) | `af workflow create` then `af workflow run` | Classic workflow engine with 190+ built-in node types | | Attach Google Docs/Sheets/Slack/Notion/etc. to an agent | `af mcp-clients list/inspect` then `af agent update --patch` | Inspect before attach to avoid tool-schema quirks | Don't reach for a workforce when a single agent suffices. The eight built-in workforce blueprints (`dev-shop`, `marketing-agency`, `sales-team`, `content-studio`, `support-center`, `amazon-seller`, `tutor`, `freelancer`) are for genuine multi-agent orchestration. The legacy `af pack *` surface is deprecated as of v1.7.0 (sunset 2026-10-14) — use `af workforce init --blueprint ` instead. ## 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 the one-line deprecation warning printed when you invoke legacy commands | | `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 Six 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 playbook # All guided playbooks af playbook first-touch # Zero-to-working-agent walkthrough af changelog --json # What changed after an upgrade ``` ## Core Commands ### Agents ```bash 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 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 (multi-agent, native deploy) ```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, wires them into a DAG (trigger → coordinator → worker agents → output), and returns the workforce ID plus every created agent ID — all in one response. If any step fails, the command rolls back every resource created so far. ### 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 and warns when parametric write operations are likely to fail. See the [MCP client quirks playbook](https://docs.agenticflow.ai/developers/cli): `af playbook mcp-client-quirks`. ### Workflows ```bash 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 @input.json af workflow run-status --workflow-run-id --json ``` ### Company (portable agent-bundle I/O) ```bash af company export --output company-export.yaml af company diff company-export.yaml --json # Exit 0 = in sync, 1 = differences af company import --merge company-export.yaml --conflict-strategy local ``` ## 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 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 amazon-seller # Deploy a 5-agent Amazon Singapore seller team af playbook company-from-scratch # Build an AI company step-by-step af playbook migrate-from-paperclip # Legacy paperclip → workforce command map af playbook mcp-client-quirks # Tool-schema patterns and attach safety af playbook gateway-setup # Multi-channel webhook gateway af playbook agent-channels # Connect Linear, webhooks, Slack, etc. af playbook template-bootstrap # Start from pre-built templates af playbook mcp-to-cli-map # MCP tool → CLI command mapping ``` ## 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 | ## 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`. ## SDK A TypeScript SDK is published alongside the CLI: ```typescript import { createClient } from "@pixelml/agenticflow-sdk"; 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: "..." }); // 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: "..." } }); ``` ## Next Steps * [CLI Command Reference](https://docs.agenticflow.ai/developers/agenticflow-cli-capabilities) — Full command reference * [API Overview](https://docs.agenticflow.ai/developers/api) — REST API documentation * [Authentication](https://docs.agenticflow.ai/developers/authentication) — API authentication details