AgenticFlow CLI

Command-line interface for AI agents and developers to operate the AgenticFlow platform — build agents, deploy multi-agent workforces, and integrate with MCP tool providers, all from your shell.

Install

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
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 <id> --message "Hello!" --json

# 4. Or deploy a ready-made team in one command (v1.6+)
af workforce init --blueprint dev-shop --name "My Dev Team" --json

AI agents: start every session with af bootstrap --json — it returns everything in one call. See the AI Agent Context guide.

What you can build

You want…	Use	Because
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, dev shop, marketing agency, Amazon seller team, …)	`af workforce init --blueprint <id>`	Creates workforce + N agents + wired DAG in one command. 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
Attach Google Docs/Sheets/Slack/Notion to an agent	`af mcp-clients list/inspect` then `af agent update --patch`	Inspect before attach to avoid Pipedream write-capability traps

Don't reach for a workforce when a single agent suffices — the 6 built-in workforce blueprints are for genuine multi-agent orchestration (dev-shop, marketing-agency, sales-team, content-studio, support-center, amazon-seller).

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

Environment Variables

Variable	Purpose
`AGENTICFLOW_API_KEY`	API key
`AGENTICFLOW_WORKSPACE_ID`	Default workspace ID
`AGENTICFLOW_PROJECT_ID`	Default project ID
`AF_SILENCE_DEPRECATIONS=1`	Suppress `af paperclip` deprecation warnings while migrating
`AF_INSECURE_TLS=1`	Opt-in to insecure TLS for self-signed dev backends (off by default — CLI unsets inherited `NODE_TLS_REJECT_UNAUTHORIZED=0`)
`PAPERCLIP_URL`	Paperclip URL (deprecated — sunset 2026-10-14)
`LINEAR_API_KEY` / `LINEAR_AGENT_MAP`	Linear gateway config

AI-Agent Discovery

af bootstrap --json                      # THE one-shot orientation — start here
af context --json                        # AI-agent usage guide (invariants, schemas)
af schema                                # List all resource schemas
af schema agent                          # Agent create/update/stream shape
af schema agent --field mcp_clients      # Drill into a specific field (v1.5.1+)
af schema workforce --field schema       # Workforce graph shape (nodes + edges)
af playbook                              # List all guided playbooks
af playbook first-touch                  # Zero-to-working-agent walkthrough
af changelog --json                      # What changed after an upgrade

Core Commands

Agents

af agent list --fields id,name,model --json
af agent list --name-contains silk --fields id,name --json    # v1.5.1+ client-side filter
af agent get --agent-id <id> --json
af agent create --body @agent.json --dry-run --json           # Validate first
af agent create --body @agent.json --json
af agent update --agent-id <id> --patch --body '{"system_prompt":"..."}'    # v1.5.0+ partial update (fetch → merge → PUT)
af agent delete --agent-id <id> --json
af agent run --agent-id <id> --message "..." --json           # Non-streaming (returns {response, thread_id})
af agent run --agent-id <id> --thread-id <tid> --message "continue..."
af agent stream --agent-id <id> --body @messages.json         # SSE streaming

af agent update --patch (v1.5.0+) is the recommended iteration path — send only the field you want to change; MCP clients, tools, and other config stay intact.

Workforces (v1.5.0+) — the native multi-agent deploy

af workforce init --blueprint <slug> --name "My Team" --dry-run --json   # Preview
af workforce init --blueprint <slug> --name "My Team" --json             # Create workforce + agents + wired DAG, atomic rollback on failure

af workforce list --fields id,name --json
af workforce schema --workforce-id <id> --json                  # Full graph (nodes + edges)
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":"..."}'   # SSE stream
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                 # Public key + URL
af workforce delete --workforce-id <id> --json

Blueprints: dev-shop (4), marketing-agency (4), sales-team (3), content-studio (4), support-center (3), amazon-seller (5). Each af workforce init --blueprint <id> creates one agent per non-optional slot, wires the graph (trigger → coordinator → worker agents → output), and returns the workforce_id + every agent_id in one response.

MCP Clients

af mcp-clients list --name-contains "google sheets" --fields id,name --json   # v1.5.2+
af mcp-clients list --verify-auth --json                      # Reconcile stale auth flags
af mcp-clients get --id <id> --json                           # `--client-id` also works
af mcp-clients inspect --id <id> --json                       # v1.5.1+ — classify Pipedream vs Composio, flag write quirks

See af playbook mcp-client-quirks — some MCP providers break on parametric writes. Inspect before attaching.

Workflows

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 @input.json
af workflow run-status --workflow-run-id <run_id> --json

Company (portable agent-bundle export/import)

af company export --output company-export.yaml
af company diff company-export.yaml --json           # Phase 7 — field-level diff
af company import --merge company-export.yaml --conflict-strategy local

Paperclip (DEPRECATED — sunset 2026-10-14)

af paperclip * commands still work but emit a one-line deprecation warning per subcommand per session. Use af playbook migrate-from-paperclip for the command-by-command map. Silence with AF_SILENCE_DEPRECATIONS=1 while migrating.

Webhook Gateway

af gateway serve --channels webhook,linear --verbose
af gateway channels

Send a task:

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

Node Types & Connections

af node-types search --query "llm" --json
af node-types get --name <type> --json
af connections list --limit 200 --json

Playbooks — guided paths

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            # Full Amazon SG seller team deploy
af playbook company-from-scratch     # Build an AI company step-by-step
af playbook migrate-from-paperclip   # Paperclip → workforce command map (v1.5.0+)
af playbook mcp-client-quirks        # Pipedream vs Composio — attach safety (v1.5.1+)
af playbook gateway-setup            # Multi-channel webhook gateway
af playbook agent-channels           # Connect Linear, webhooks, etc.
af playbook template-bootstrap       # Start from pre-built templates
af playbook mcp-to-cli-map           # MCP → CLI command mapping
af playbook deploy-to-paperclip      # [DEPRECATED] legacy Paperclip deploy

Global Options

Flag	Purpose
`--json`	Machine-readable JSON output with `schema:` discriminators
`--fields <fields>`	Filter output fields (saves context window)
`--dry-run`	Validate without executing (on create/deploy commands)
`--patch`	Partial update (on `af agent update` and other update commands)
`--api-key <key>`	Override API key
`--workspace-id <id>`	Override workspace
`--project-id <id>`	Override project

Error handling

Every --json error returns a consistent envelope:

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

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 (v1.5.0+)
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: "..." } });

Troubleshooting

Problem	Solution
`401` from most commands	Run `af doctor --json` — then `af login` to refresh
`404: <Resource> not found`	Run the matching `list` command to see real IDs (error `hint` points you there)
`422` with pydantic errors	Inspect `details.payload` — field-level errors are there
`af agent update` 422s on null fields	Use `--patch` (auto-strips null-rejected fields)
`af workforce run` 400 "Failed to retrieve user info"	Known backend issue for API-key auth — not a CLI bug
`af paperclip *` deprecation noise	Set `AF_SILENCE_DEPRECATIONS=1` while migrating; use `af playbook migrate-from-paperclip`
Node TLS warning	CLI now unsets inherited `NODE_TLS_REJECT_UNAUTHORIZED=0`; set `AF_INSECURE_TLS=1` if you genuinely need it
Connections list too short	Default limit is 10; use `--limit 200`

Name		Name	Last commit message	Last commit date
Latest commit History 230 Commits
.github/workflows		.github/workflows
.planning		.planning
docs		docs
packages		packages
scripts		scripts
.gitignore		.gitignore
CODEX_AUTORESEARCH.md		CODEX_AUTORESEARCH.md
CODEX_TEST.md		CODEX_TEST.md
CONTEXT.md		CONTEXT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
af.sh		af.sh
autoresearch.md		autoresearch.md
package-lock.json		package-lock.json
package.json		package.json
test-all.sh		test-all.sh
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

AgenticFlow CLI

Install

Quick Start

What you can build

Authentication

Environment Variables

AI-Agent Discovery

Core Commands

Agents

Workforces (v1.5.0+) — the native multi-agent deploy

MCP Clients

Workflows

Company (portable agent-bundle export/import)

Paperclip (DEPRECATED — sunset 2026-10-14)

Webhook Gateway

Node Types & Connections

Playbooks — guided paths

Global Options

Error handling

SDK

Troubleshooting

Links

About

Uh oh!

Releases 37

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

AgenticFlow CLI

Install

Quick Start

What you can build

Authentication

Environment Variables

AI-Agent Discovery

Core Commands

Agents

Workforces (v1.5.0+) — the native multi-agent deploy

MCP Clients

Workflows

Company (portable agent-bundle export/import)

Paperclip (DEPRECATED — sunset 2026-10-14)

Webhook Gateway

Node Types & Connections

Playbooks — guided paths

Global Options

Error handling

SDK

Troubleshooting

Links

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 37

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages