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.0 (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 20
agenticflow blueprints list --kind workflow --json           # rungs 0-2
agenticflow blueprints list --kind agent --json              # rung 3
agenticflow blueprints list --kind workforce --json          # rung 6
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 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 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 is a 2-step process: start the run, then poll for status.

agenticflow workflow run --workflow-id <id> --input '{"url":"..."}' --json
agenticflow workflow run --workflow-id <id> --body '{"url":"..."}' --json   # --body alias
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

The 13 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

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.

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 20
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, deploy_command. The deploy_command field tells you exactly how to deploy (af <kind> init --blueprint <id> --json).

---

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 v1.10.0. 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> --input '{"url":"..."}' --json
agenticflow workflow run-status --run-id <id> --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

# 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
[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