CLI Command Reference

Full reference for every AgenticFlow CLI command group and option.

Complete reference for all AgenticFlow CLI commands, as of @pixelml/agenticflow-cli@1.10.7 (SDK @pixelml/agenticflow-sdk@1.6.0).

The composition ladder

Three deploy verbs map 1:1 to rungs on a 7-level complexity ladder. Pick the lowest rung that solves the user's problem.

Rung	Kind	Deploy verb	Complexity field
0	workflow	af workflow init	complexity: 0 — minimal
1	workflow	af workflow init	complexity: 1 — chained LLMs
2	workflow	af workflow init	complexity: 2 — enriched w/ real data
3	agent	af agent init	complexity: 3 — agent + plugins
4	agent	(roadmap)	complexity: 4 — agent + workflow tools
5	agent	(roadmap)	complexity: 5 — agent + sub-agents
6	workforce	af workforce init	complexity: 6 — multi-agent DAG

Use af playbook composition-ladder for the decision rule in full.

Diagnostics & Discovery

agenticflow bootstrap --json       # One-shot workspace snapshot — START HERE
agenticflow context --json         # AI-agent invariants, journey, discovery helpers
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 discover --json        # Machine-readable capability index
agenticflow changelog --json       # What shipped per version

# Schemas
agenticflow schema                               # List resources with schemas
agenticflow schema agent --json                  # Full agent create/update shape
agenticflow schema agent --field mcp_clients     # Drill into a nested field

# Blueprints (CLI-shipped starter catalog — offline, version-locked)
agenticflow blueprints list --json                           # all 379 in v1.10.7
agenticflow blueprints list --kind workflow --json           # rungs 0-2, 362 blueprints
agenticflow blueprints list --kind agent --json              # rung 3
agenticflow blueprints list --kind workforce --json          # rung 6, 14 blueprints
agenticflow blueprints list --complexity 2 --json
agenticflow blueprints get --id <slug> --json                # full details
agenticflow blueprints show --id <slug> --json               # alias for `get`

# Marketplace (live backend catalog)
agenticflow marketplace list --json
agenticflow marketplace list --type agent_template --search "seo" --json
agenticflow marketplace get --id <item_id> --json
agenticflow marketplace try --id <item_id> --json            # auto-detects + clones

# Playbooks
agenticflow playbook --list
agenticflow playbook composition-ladder     # routing rule
agenticflow playbook ready-prompts          # copy-paste prompts per rung
agenticflow playbook marketplace-vs-blueprint
agenticflow playbook n8n-to-agenticflow
agenticflow playbook mas-graph-building
agenticflow playbook first-touch

When --json is set, command failures return a structured 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 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 or an unknown enum)
missing_required_option	Required flag not supplied
missing_connection	Workflow needs an LLM-provider connection not present in workspace
workforce_init_failed	Workforce init rolled back — see details.rolled_back_agents + details.rolled_back_workforce
workforce_run_api_key_unsupported	Authenticated workforce run rejects API-key auth; CLI prints a 3-step workaround
completed_empty	Agent run returned status: completed with empty response (recursion limit exhausted)

---

Workflows (rungs 0-2)

Workflows are deterministic multi-node pipelines. Same input → same output (modulo model stochasticity).

Blueprint-based initialization (new in v1.10.0)

agenticflow workflow init --blueprint llm-hello --json           # simplest: single LLM
agenticflow workflow init --blueprint llm-chain --json           # chained LLMs
agenticflow workflow init --blueprint summarize-url --json       # web_retrieval → llm
agenticflow workflow init --blueprint n8n-converter --json       # n8n JSON → AgenticFlow JSON
agenticflow workflow init --blueprint api-summary --json         # api_call → llm
agenticflow workflow init --blueprint <slug> --dry-run --json    # preview payload
agenticflow workflow init --blueprint <slug> --llm-connection-id <id>   # override auto-discovery

af workflow init auto-discovers the workspace's LLM-provider connection (Straico, OpenAI, Anthropic, Google, DeepSeek, Groq — in preference order). If none is found, the command emits missing_connection with a clear remediation hint.

CRUD

agenticflow workflow list --fields id,name,status --json
agenticflow workflow get --workflow-id <id> --json
agenticflow workflow create --body @workflow.json
agenticflow workflow update --workflow-id <id> --body @update.json
agenticflow workflow delete --workflow-id <id>

Execution

Workflow execution can be asynchronous or synchronous. Use --wait when you want the CLI to poll until a terminal state and return the final output inline.

agenticflow workflow run --workflow-id <id> --input '{"url":"..."}' --json
agenticflow workflow run --workflow-id <id> --body '{"url":"..."}' --json   # --body alias
agenticflow workflow run --workflow-id <id> --body '{"url":"..."}' --wait --timeout 180 --poll-interval 3 --json
agenticflow workflow run-status --workflow-run-id <run_id> --json
agenticflow workflow run-status --run-id <run_id> --json                     # --run-id alias

Run History

agenticflow workflow list-runs --workflow-id <id> --limit 50 --json
agenticflow workflow run-history --workflow-id <id> --limit 50 --json

Validation

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.

---

Agents (rung 3)

Blueprint-based initialization (since v1.8.0)

agenticflow agent init --blueprint research-assistant --json     # web_search + web_retrieval + api_call + string_to_json
agenticflow agent init --blueprint content-creator --json        # web + generate_image
agenticflow agent init --blueprint api-helper --json             # api_call + json parsing
agenticflow agent init --blueprint <slug> --dry-run --json       # preview payload
agenticflow agent init --blueprint <slug> --name "..." --model agenticflow/gpt-4o-mini

Tier-1 agent blueprints deploy a single agent with AgenticFlow-native plugins attached. Default model is agenticflow/gpt-4o-mini (verified to reliably call tools on "latest X" questions; override with --model).

CRUD

agenticflow agent list --fields id,name,model --json
agenticflow agent list --name-contains <substr> --fields id,name --json   # Client-side filter
agenticflow agent get --agent-id <id> --json
agenticflow agent get --id <id> --json                                    # --id alias
agenticflow agent get --id <id> --fields name,model,plugins --json        # projection
agenticflow agent create --body @agent.json --dry-run --json              # Always validate first
agenticflow agent create --body @agent.json --json
agenticflow agent update --agent-id <id> --body @update.json --json       # Full-body replace
agenticflow agent update --agent-id <id> --patch --body '{"system_prompt":"..."}' --json
agenticflow agent delete --agent-id <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

agenticflow agent run --agent-id <id> --message "..." --json              # Non-streaming, returns {response, thread_id}
agenticflow agent run --agent-id <id> --thread-id <tid> --message "..."   # Continue a thread
agenticflow agent stream --agent-id <id> --body @messages.json            # SSE streaming

If the agent run returns status: "completed_empty" with an empty response, the agent hit its recursion_limit in a tool loop. The warning message names the thread id; inspect with af agent-threads messages --thread-id <id>. Remediation: refine the prompt to converge faster, or raise recursion_limit via af agent update --patch.

Minimal Agent Payload

{
  "name": "Support Agent",
  "tools": [],
  "project_id": "<your_project_id>",
  "model": "agenticflow/gpt-4o-mini",
  "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

{
  "messages": [
    { "role": "user", "content": "What can you help me with?" }
  ]
}

---

Workforces (rung 6)

Blueprint-based initialization

agenticflow workforce init --blueprint <slug> --name "<name>" --dry-run --json   # Preview
agenticflow workforce init --blueprint <slug> --name "<name>" --json             # Create
agenticflow workforce init --blueprint <slug> --skeleton-only --json             # trigger+output scaffold, no agents
agenticflow workforce init --blueprint <slug> --include-optional-slots --json    # fill every slot including optionals
agenticflow workforce init --blueprint <slug> --model <model> --json             # override default model
agenticflow workforce init --blueprint autonomous-desk --json                    # self-correcting desk topology
agenticflow workforce init --blueprint autonomous-desk \
  --tool-workflow-id <workflow_id> \
  --tool-workflow-purpose "stock watchlist brief" \
  --tool-workflow-input '{"ticker":"{{nodes.agent_planner.output.structured_output.workflow_input_primary}}"}' \
  --json

The 14 workforce blueprints are:

Batteries-included (plugins pre-attached — work end-to-end):

Blueprint	Agents	Pattern
research-pair	2	Planner → Researcher (web_search + web_retrieval)
content-duo	2	Writer (web_search) → Illustrator (generate_image)
api-pipeline	2	Fetcher (api_call) → Analyst
fact-check-loop	2	Writer → Fact Checker
parallel-research	4	Coordinator → 2 Researchers (parallel) → Synthesizer
autonomous-desk	4	Planner → route gate → workflow or Researcher → Critic → revision loop → Editor

Vertical teams — generic agents, attach your own MCP tools after deploy:

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.

af workforce init --blueprint <id> creates one real agent per required slot, then wires them into a DAG (trigger → coordinator → worker agents → output — or coordinator → parallel workers → synthesizer → output if the blueprint declares isSynthesizer). Uses a single atomic graph PUT; on failure, every resource created so far is automatically rolled back.

autonomous-desk uses the newer desk topology. It adds structured-output planner and critic agents, condition gates, state variable branch merging, an optional deterministic workflow route, and an automatic revision path before the editor ships the final response. Read af playbook mas-graph-building before hand-authoring or editing this class of graph.

CRUD

agenticflow workforce list --fields id,name --json
agenticflow workforce get --workforce-id <id> --json
agenticflow workforce update --workforce-id <id> --body @update.json --json
agenticflow workforce delete --workforce-id <id> --json

Graph operations

agenticflow workforce schema --workforce-id <id> --json                  # Full graph (nodes + edges)
agenticflow workforce deploy --workforce-id <id> --body @graph.json      # Atomic graph replace
agenticflow workforce validate --workforce-id <id> --json                # Cycle + dangling-edge check
agenticflow workforce node-types --json                                  # Discover available node types

Running a workforce

agenticflow workforce run --workforce-id <id> --trigger-data '{"message":"..."}'
agenticflow workforce runs list --workforce-id <id> --json
agenticflow workforce runs get --run-id <id> --json
agenticflow workforce runs stop --run-id <id> --json

af workforce run currently rejects API-key auth (backend bug — returns 400 on user lookup). The CLI detects this and prints a 3-step workaround. Reliable path: af workforce publish to get a public_key, then curl the /v1/workforce/public/<public_key>/run endpoint.

Versions & publishing

agenticflow workforce versions list --workforce-id <id> --json
agenticflow workforce versions latest --workforce-id <id> --json
agenticflow workforce versions publish --workforce-id <id> --version-id <v> --json
agenticflow workforce versions restore --workforce-id <id> --version-id <v> --json

agenticflow workforce publish --workforce-id <id> --json          # Generate public key + URL
agenticflow workforce rotate-key --workforce-id <id> --json

---

Blueprints

CLI-shipped starter catalog (offline, version-locked to the CLI release).

agenticflow blueprints list --json                            # all 379 in v1.10.7
agenticflow blueprints list --kind workflow --json            # filter by kind
agenticflow blueprints list --kind agent --json
agenticflow blueprints list --kind workforce --json
agenticflow blueprints list --complexity 2 --json             # filter by rung
agenticflow blueprints list --tier 1 --json                   # legacy filter (still works)
agenticflow blueprints get --id <slug> --json                 # full details
agenticflow blueprints show --id <slug> --json                # alias for `get`

Response shape includes: id, name, kind, complexity, tier (legacy), description, goal, use_cases, agents[] (with plugins, is_synthesizer), workflow_nodes[], workflow_input_schema, and deploy_command. The deploy_command field tells you exactly how to deploy (af <kind> init --blueprint <id> --json). Current v1.10.7 counts: 362 workflow blueprints, 3 agent blueprints, and 14 workforce blueprints.

---

Marketplace

Live backend catalog — complements blueprints. Updated independently of the CLI.

agenticflow marketplace list --json
agenticflow marketplace list --type agent_template --json
agenticflow marketplace list --type workflow_template --json
agenticflow marketplace list --type mas_template --json
agenticflow marketplace list --search "seo" --featured --free --json
agenticflow marketplace list --fields id,name,type,creator --json
agenticflow marketplace get --id <item_id> --json
agenticflow marketplace try --id <item_id> --json             # auto-detects type + clones
agenticflow marketplace try --id <item_id> --dry-run --json   # preview payload

marketplace try auto-detects the item type and delegates:

• agent_template → reuses af templates duplicate agent flow (materializes tool workflows, then the agent)

• workflow_template → reuses af templates duplicate workflow flow

• mas_template → creates a workforce shell + PUTs nodes/edges. Warns about cross-workspace agent_id references.

See af playbook marketplace-vs-blueprint for when to use marketplace vs blueprints.

---

Templates (duplicate by id)

agenticflow templates sync --json                                # Cache all templates locally
agenticflow templates index --dir <path> --json                  # Inspect cache manifest
agenticflow templates duplicate agent --template-id <id> --json
agenticflow templates duplicate workflow --template-id <id> --json
agenticflow templates duplicate workforce --template-id <marketplace_mas_id> --json
agenticflow templates duplicate workforce --workforce-id <src_ulid> --json   # latest version of a source

The templates duplicate commands rebuild the create payload client-side from the template snapshot, so cloning works with API-key auth (the marketplace /mix endpoint currently requires user JWT).

---

MCP Clients

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 <id> --json                  # --client-id also works
agenticflow mcp-clients inspect --id <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.

---

Node Types

agenticflow node-types search --query "llm" --json
agenticflow node-types get --name <name> --json
agenticflow node-types list --limit 50 --json                  # Prefer search/get — full list is large
agenticflow node-types dynamic-options --name <name> --field-name <field> --json

Prefer get or search over list. The full node types list is very large.

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. connection: null means no connection required (e.g. web_search, web_retrieval, api_call, agenticflow_generate_image, string_to_json).

---

Connections

agenticflow connections list --limit 200 --json
agenticflow connections create --body @conn.json
agenticflow connections update --connection-id <id> --body @update.json
agenticflow connections delete --connection-id <id>

The default limit is 10. Use --limit 200 when you need a full workspace view.

---

Uploads

agenticflow uploads create --body @upload.json
agenticflow uploads status --session-id <id> --json

---

Gateway (webhook orchestration)

agenticflow gateway serve --channels webhook,linear --verbose
agenticflow gateway channels --json

Send a task via the generic webhook channel:

curl -X POST http://localhost:4100/webhook/webhook \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"<id>","message":"Do X","callback_url":"https://..."}'

---

API Discovery

agenticflow ops list --public-only --tag agents --json
agenticflow ops show <operation_id>
agenticflow catalog export --json
agenticflow catalog rank --task "<description>" --top 10 --json
agenticflow discover --json
agenticflow schema <resource> --json
agenticflow schema <resource> --field <name> --json

af schema <resource> --field <name> 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:

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

agenticflow policy show
agenticflow policy init

---

Hidden (deprecated) command groups

These groups are hidden from default --help in current v1.10.x releases. They still work; set AF_SHOW_DEPRECATED=1 to reveal them in --help. All migration paths resolve to blueprints or the workforce surface.

Group	Migration	Sunset
af pack *	af workforce init --blueprint <id> (or af agent init --blueprint <id> for Tier 1)	2026-10-14
af paperclip *	af workforce * — see af playbook migrate-from-paperclip	2026-10-14
af company *	af workforce export/import	No hard sunset

Per-invocation deprecation warnings print to stderr. Silence with AF_SILENCE_DEPRECATIONS=1.

---

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

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
AF_SHOW_DEPRECATED	Set =1 to un-hide af pack, af paperclip, af company in --help
AF_INSECURE_TLS	Set =1 to opt-in to insecure TLS (default off; CLI unsets an inherited NODE_TLS_REJECT_UNAUTHORIZED=0 at startup)

---

Recommended Build Flow (for an AI agent)

# 1. Orient
agenticflow bootstrap --json

# 2. Pick a rung. Reading `blueprints[]` from bootstrap gives you kind + complexity + deploy_command.
agenticflow blueprints list --kind workflow --json   # simplest first

# 3. Preview
agenticflow workflow init --blueprint summarize-url --dry-run --json

# 4. Deploy
agenticflow workflow init --blueprint summarize-url --json

# 5. Run
agenticflow workflow run --workflow-id <id> --body '{"url":"..."}' --wait --json

# 6. If a single-agent orchestrator is a better fit, promote to rung 3
agenticflow agent init --blueprint research-assistant --json
agenticflow agent run --agent-id <id> --message "..." --json
agenticflow agent update --agent-id <id> --patch --body '{"system_prompt":"..."}' --json

# 7. If multi-agent coordination is genuinely needed, rung 6
agenticflow workforce init --blueprint parallel-research --json
agenticflow workforce init --blueprint autonomous-desk --json

# 8. Cleanup
agenticflow workflow delete --workflow-id <id> --json
agenticflow agent delete --agent-id <id> --json
agenticflow workforce delete --workforce-id <id> --json

---

Troubleshooting

Problem	Solution
Unsure which rung to pick	Read af playbook composition-ladder and the complexity field on af blueprints list --json
missing_connection on af workflow init	Workflow needs an LLM-provider connection. Create one (Straico, OpenAI, Anthropic, Google, DeepSeek, or Groq) or pass --llm-connection-id <id>
af workforce run 400 "Failed to retrieve user info"	Known backend bug for API-key auth. CLI prints a 3-step workaround — publish + public SSE run
Connection X not found on workflow run	Re-run the command. CLI auto-resolves 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, 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
completed_empty on agent run	Agent exhausted recursion_limit in a tool loop. Raise the limit or refine the prompt
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
Hand-authored workforce graph renders empty downstream prompts	Read af playbook mas-graph-building; node references need the .output hop, e.g. {{nodes.planner.output.last_message}}
[deprecated] warning noise	Set AF_SILENCE_DEPRECATIONS=1 while migrating off af paperclip * / af pack *
pack/paperclip/company hidden from --help	By design — set AF_SHOW_DEPRECATED=1 to see them, or use the replacement commands (blueprints, workforce)
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 insecure TLS