CLI Command Reference

Complete reference for all AgenticFlow CLI commands.

Diagnostics

agenticflow discover --json        # Machine-readable capability index
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

doctor validates config presence, token presence, API reachability, and bundled OpenAPI loading. Use --strict in CI/CD to gate execution.

When --json is set, command failures return the structured envelope:

{
  "schema": "agenticflow.error.v1",
  "code": "request_failed",
  "message": "...",
  "hint": "optional"
}

---

Workflows

CRUD

agenticflow workflow list [--limit N] [--offset N] --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.

# Start a run
agenticflow workflow run --workflow-id <id> --input @input.json --json

# Poll until status is terminal (success|failed|cancelled)
agenticflow workflow run-status --workflow-run-id <run_id> --json

Run History

agenticflow workflow list-runs --workflow-id <id> [--limit N] --json
agenticflow workflow run-history --workflow-id <id> [--limit N] --json

Validation & Metadata

agenticflow workflow validate --body @workflow.json --local-only
agenticflow workflow validate --body @workflow.json
agenticflow workflow like-status --workflow-id <id> --json
agenticflow workflow reference-impact --workflow-id <id> --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

agenticflow agent list [--limit N] --json
agenticflow agent get --agent-id <id> --json
agenticflow agent create --body @agent.json
agenticflow agent update --agent-id <id> --body @update.json
agenticflow agent delete --agent-id <id>
agenticflow agent stream --agent-id <id> --body @stream.json
agenticflow agent reference-impact --agent-id <id> --json

Template Bootstrap & Duplicate

# Seed local template samples
agenticflow templates sync --dir .agenticflow/templates --json
agenticflow templates index --dir .agenticflow/templates --json

# Duplicate workflow/agent from template ids
agenticflow templates duplicate workflow --template-id <workflow_template_id> --json
agenticflow templates duplicate agent --template-id <agent_template_id> --json

# Prefer cache-first template resolution
agenticflow templates duplicate workflow --template-id <workflow_template_id> --cache-dir .agenticflow/templates --json
agenticflow templates duplicate agent --template-id <agent_template_id> --cache-dir .agenticflow/templates --json

# Dry-run from local template files (no create)
agenticflow templates duplicate workflow --template-id <workflow_template_id> --cache-dir .agenticflow/templates --dry-run --json
agenticflow templates duplicate agent --template-file .agenticflow/templates/agent/<file>.json --cache-dir .agenticflow/templates --dry-run --json

templates duplicate agent duplicates referenced workflow templates first, then creates the agent with duplicated workflow_id tool references.

Minimal Agent Payload

{
  "name": "Support Agent",
  "description": "Handles support Q&A",
  "project_id": "<your_project_id>",
  "system_prompt": "You are a reliable support agent."
}

Stream Payload

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

---

Node Types

agenticflow node-types get --name <name> --json        # Get specific node type
agenticflow node-types search --query <query> --json   # Search by keyword
agenticflow node-types list [--limit N] --json         # List all (large response)
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 and may time out.

Finding Connection Requirements

To find what kind of connection a node requires:

agenticflow node-types get --name google_search --json

Look at the connection field in the response. connection_category tells you which connection category is needed.

---

Connections

agenticflow connections list [--limit N] --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

---

API Discovery

These commands help you explore the full AgenticFlow API surface:

agenticflow ops list [--public-only] [--tag <tag>] [--json]
agenticflow ops show <operation_id>
agenticflow catalog export --json
agenticflow catalog rank --task "description"
agenticflow playbook --list
agenticflow playbook first-touch
agenticflow discover --json

---

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.

---

Policy & Safety

agenticflow policy show    # Show current execution policies
agenticflow policy init    # Initialize policy config

---

Recommended Build Flow for Agents

Step-by-step process for an AI agent to build and run a workflow:

# 1. Verify setup (CI-safe)
agenticflow doctor --json --strict

# 2. Find the right node type
agenticflow node-types search --query "gmail" --json

# 3. Inspect node schema and connection requirements
agenticflow node-types get --name mcp_run_action --json

# 4. Check available connections
agenticflow connections list --limit 200 --json

# 5. Validate the workflow payload
agenticflow workflow validate --body @workflow.json

# 6. Create the workflow
agenticflow workflow create --body @workflow.json

# 7. Run the workflow (smart connection resolution if needed)
agenticflow workflow run --workflow-id <id> --input @input.json --json

# 8. Poll until completion
agenticflow workflow run-status --workflow-run-id <run_id> --json

---

Troubleshooting

Problem	Solution
Connection X not found	Re-run the workflow. CLI can auto-resolve using available connections.
operation_not_found	Use agenticflow ops list --json then retry with the suggested operation id.
invalid_option_value	Check numeric flags like --limit, --offset, --top and provide integers only.
local_schema_validation_failed	Inspect details.issues, fix payload fields, and 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 detail array for exact missing/invalid fields.
Network request failed	Verify network/TLS/path; prefer targeted queries (node-types get/search) over huge list calls.
Connections list too few	Default limit is 10. Use --limit 200.

For restricted/sandbox network environments, use cache-first dry runs:

agenticflow templates duplicate workflow --template-id <id> --cache-dir .agenticflow/templates --dry-run --json
agenticflow templates duplicate agent --template-file .agenticflow/templates/agent/<file>.json --cache-dir .agenticflow/templates --dry-run --json