AgenticFlow CLI

Command-line interface for AgenticFlow — build agents, deploy workflows and multi-agent workforces, and automate operations from your shell.

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/[email protected] (SDK @pixelml/[email protected]).

Install

# 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

# 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 <id> --input '{"url":"..."}' --json
af agent run --agent-id <id> --message "..." --json
af workforce run --workforce-id <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 <vertical>	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.

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.

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 <item_id> --json               # full details + embedded template
af marketplace try --id <item_id> --dry-run --json     # preview clone payload
af marketplace try --id <item_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=<key>	CI/CD, automated agents
CLI flag	--api-key <key>	One-off scripts
Import from .env	af auth import-env --file .env	Batch import

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:

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 <k> --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)

af workflow init --blueprint <slug> --json              # Deploy a workflow blueprint
af workflow list --fields id,name,status --json
af workflow get --workflow-id <id> --json
af workflow validate --body @wf.json --local-only
af workflow create --body @wf.json --json
af workflow run --workflow-id <id> --input '{"url":"..."}' --json
af workflow run --workflow-id <id> --body '{"url":"..."}' --json   # --body alias
af workflow run-status --workflow-run-id <run_id> --json
af workflow run-status --run-id <run_id> --json                     # --run-id alias
af workflow delete --workflow-id <id> --json

Agents (rung 3 — flexible)

af agent init --blueprint <slug> --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 <id> --json
af agent get --id <id> --json                           # --id alias
af agent get --id <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 <id> --patch --body '{"system_prompt":"..."}'
af agent delete --agent-id <id> --json
af agent run --agent-id <id> --message "..." --json
af agent run --agent-id <id> --thread-id <tid> --message "continue"
af agent stream --agent-id <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)

af workforce init --blueprint <slug> --name "My Team" --dry-run --json   # Preview
af workforce init --blueprint <slug> --name "My Team" --json             # Create
af workforce list --fields id,name --json
af workforce schema --workforce-id <id> --json          # Full graph
af workforce deploy --workforce-id <id> --body @graph.json --json   # Atomic graph replace
af workforce validate --workforce-id <id> --json        # Cycle detection
af workforce run --workforce-id <id> --trigger-data '{"message":"..."}'
af workforce versions list --workforce-id <id> --json
af workforce versions publish --workforce-id <id> --version-id <v>
af workforce publish --workforce-id <id> --json         # Mint public URL
af workforce delete --workforce-id <id> --json

af workforce init --blueprint <id> 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)

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 <id> --json
af mcp-clients inspect --id <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

af marketplace list --type agent_template|workflow_template|mas_template --json
af marketplace get --id <item_id> --json
af marketplace try --id <item_id> --json                   # Auto-detects type + clones
af templates duplicate agent --template-id <id> --json     # Clone an agent template directly
af templates duplicate workflow --template-id <id> --json
af templates duplicate workforce --template-id <mas_id> --json   # New in v1.8+
af templates sync --json                                   # Cache all templates locally

Company (portable agent-bundle I/O) [hidden — legacy]

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 <topic>:

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 <list>	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 <key>	Override API key
--workspace-id <id>	Override workspace
--project-id <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 <id> (sunset 2026-10-14)

• af paperclip init → af workforce init --blueprint <id> (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:

{
  "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:

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 — Full command reference

• Ecosystem — How the CLI fits with the platform, docs, and AI Toolkit

• API Overview — REST API documentation

• Authentication — API authentication details