AgenticFlow CLI

The AgenticFlow CLI is a command-line interface for managing workflows, agents, and connections on the AgenticFlow platform.

It is designed for:

• AI agents executing platform operations autonomously

• Engineers scripting workflow automation

• CI/CD pipelines that need machine-readable JSON output

Install

# Run without installing
npx @pixelml/agenticflow-cli doctor

# Or install globally
npm install -g @pixelml/agenticflow-cli

Requires Node.js 18+.

Quick Start

# 1. Set your API key
export AGENTICFLOW_API_KEY=your_key

# 2. Verify setup (CI-safe: non-zero exit if required checks fail)
agenticflow doctor --json --strict

# 3. List your workflows
agenticflow workflow list --json

# 4. Prime local template cache (workflow + agent + workforce samples)
agenticflow templates sync --json
agenticflow templates index --json

# 4b. Duplicate from templates (cache-first)
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

# 5. Run a workflow
agenticflow workflow run --workflow-id <id> --input '{"query": "hello"}' --json

# 6. Check run status
agenticflow workflow run-status --workflow-run-id <run_id> --json

# 7. Create + stream an agent
agenticflow agent create --body @agent.json
agenticflow agent stream --agent-id <id> --body @stream.json --json

Start from the cold-agent path:

agenticflow playbook first-touch
agenticflow discover --json
agenticflow templates sync --json

Authentication

Three methods, in priority order:

Method	Usage	Best For
Interactive login	agenticflow 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	agenticflow auth import-env --file .env	Batch import

Interactive Login (recommended)

agenticflow login
# Prompts for: API Key, Workspace ID, Project ID
# Saves to ~/.agenticflow/auth.json

# Verify
agenticflow whoami --json

# Remove credentials
agenticflow logout

Import from .env

agenticflow auth import-env --file /path/to/.env

Environment Variables

Variable	Purpose
AGENTICFLOW_API_KEY	API key
AGENTICFLOW_WORKSPACE_ID	Default workspace ID
AGENTICFLOW_PROJECT_ID	Default project ID

AGENTICFLOW_PUBLIC_API_KEY is accepted as a legacy fallback if AGENTICFLOW_API_KEY is not set.

Machine Output Contract

Why this matters for autonomous agents:

• The CLI is designed to be self-discoverable and contract-first.

• Agents should infer capabilities from CLI output, not hardcoded assumptions.

What to run first:

• agenticflow discover --json (capability index)

• agenticflow playbook --list --json (available guided flows)

• agenticflow templates sync --json (local template seed cache)

• agenticflow templates index --json (cache summary)

• agenticflow templates duplicate workflow --template-id <id> --cache-dir .agenticflow/templates --dry-run --json (build from template safely)

How output works: SDK-backed resource commands already emit JSON. Use --json when you need JSON on mixed-output commands (doctor, ops, catalog, call, playbook, discover) and structured JSON errors.

Error envelope shape:

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

Local-first validation:

• workflow create/update/run and agent create/update/stream run local schema checks before API calls.

• Failures return code: local_schema_validation_failed with field-level issues in details.issues.

Global Options

Global flags available on all commands:

Flag	Purpose
--api-key <key>	Override API key
--workspace-id <id>	Override workspace
--project-id <id>	Override project
--spec-file <path>	Custom OpenAPI spec
--no-color	Disable ANSI color output
--json	Force JSON output

--dry-run is available on agenticflow call only.

Next Steps

• CLI Command Reference — Full command reference

• API Overview — REST API documentation

• Authentication — API authentication details