CLI Reference

PetalFlow CLI

The PetalFlow CLI provides commands for running, validating, compiling, and serving workflow graphs. It also includes comprehensive tool management for native, HTTP, stdio, and MCP-based tools.

Installation

# Install the CLI
go install github.com/petal-labs/petalflow/cmd/petalflow@latest

# Verify installation
petalflow --version

Global Flags

These flags apply to all commands:

Flag	Description
--verbose	Enable verbose/debug logging
--quiet	Suppress all output except errors
--no-color	Disable colored output
--help, -h	Show help for any command

Commands

run

Execute a workflow file with input data.

compile

Compile agent workflow to graph IR.

validate

Validate workflow files without executing.

serve

Start HTTP daemon for workflow management.

tools

Register, inspect, and manage tools.

---

petalflow run

Execute a workflow file with input data. Supports both agent workflow files and graph IR files.

Usage

petalflow run [flags] <workflow-file>

Flags

Flag	Short	Description
--input	-i	Inline JSON input (e.g., '{"query": "hello"}')
--input-file	-f	Read input from JSON file
--output	-o	Write output to file instead of stdout
--format		Output format: json (default) or text
--timeout	-t	Execution timeout (e.g., 30s, 5m)
--dry-run		Validate without executing
--env	-e	Set environment variables (can be repeated)
--provider-key		Provider API key in format provider=key
--store-path		Path to SQLite store for tool registry
--stream		Enable streaming output via SSE

Examples

# Run with inline input
petalflow run workflow.yaml -i '{"message": "Hello, world!"}'

# Run with input file
petalflow run workflow.yaml -f input.json

# Run with timeout and output file
petalflow run workflow.yaml -i '{"query": "search"}' -t 30s -o result.json

# Run with provider key
petalflow run workflow.yaml -i '{}' --provider-key openai=sk-...

# Run with environment variables
petalflow run workflow.yaml -i '{}' -e API_URL=https://api.example.com

# Dry run (validate only)
petalflow run workflow.yaml -i '{}' --dry-run

# Stream output
petalflow run workflow.yaml -i '{}' --stream

Input Handling

The run command accepts input in multiple formats:

1. Inline JSON (--input): Direct JSON string on the command line
2. JSON file (--input-file): Path to a JSON file containing input data
3. Stdin: If no input flag is provided, reads from stdin

# Read from stdin
echo '{"query": "hello"}' | petalflow run workflow.yaml

# Or use input redirection
petalflow run workflow.yaml < input.json

Streaming Output

When --stream is enabled, the CLI outputs Server-Sent Events (SSE) format:

event: node_start
data: {"node": "classify", "timestamp": "2024-01-15T10:30:00Z"}

event: node_output
data: {"node": "classify", "output": {"category": "billing"}}

event: node_end
data: {"node": "classify", "duration_ms": 150}

event: complete
data: {"output": {"result": "..."}}

---

petalflow compile

Compile an agent workflow file to graph IR (Intermediate Representation). This command only accepts agent workflow files, not graph IR files.

Usage

petalflow compile [flags] <agent-workflow-file>

Flags

Flag	Short	Description
--output	-o	Write compiled IR to file (default: stdout)
--pretty		Pretty-print the JSON output
--validate-only		Validate without outputting IR

Examples

# Compile to stdout
petalflow compile agent-workflow.yaml

# Compile with pretty printing
petalflow compile agent-workflow.yaml --pretty

# Compile to file
petalflow compile agent-workflow.yaml -o compiled.json

# Validate only
petalflow compile agent-workflow.yaml --validate-only

Agent Workflow vs Graph IR

PetalFlow supports two workflow file formats:

Format	Extension	Description
Agent Workflow	.yaml, .yml	High-level declarative format for agents
Graph IR	.json	Low-level graph intermediate representation

The compile command transforms agent workflows into graph IR. The run and validate commands accept both formats.

---

petalflow validate

Validate a workflow file without executing it. Useful for CI/CD pipelines and pre-commit checks.

Usage

petalflow validate [flags] <workflow-file>

Flags

Flag	Description
--format	Output format: text (default) or json
--strict	Enable strict validation (additional checks)

Examples

# Basic validation
petalflow validate workflow.yaml

# JSON output for CI integration
petalflow validate workflow.yaml --format json

# Strict mode
petalflow validate workflow.yaml --strict

Output Formats

Text format (default):

Validating workflow.yaml...
OK: workflow is valid

JSON format:

{
  "valid": true,
  "file": "workflow.yaml",
  "schema": "agent_workflow",
  "errors": [],
  "warnings": []
}

Validation Checks

The validator performs these checks:

• Schema compliance (agent workflow or graph IR)
• Node reference integrity (edges point to valid nodes)
• Entry point existence
• Required field presence
• Type correctness for node configurations
• Cycle detection in non-iterative graphs

In strict mode, additional checks include:

• Unused node detection
• Unreachable node warnings
• Best practice recommendations

---

petalflow serve

Start an HTTP daemon server for managing workflows and tools. The server provides REST APIs for workflow execution, tool registration, and real-time streaming.

Usage

petalflow serve [flags]

Flags

Flag	Default	Description
--port	8080	HTTP server port
--host	127.0.0.1	Host address to bind
--cors-origin		Allowed CORS origins (comma-separated)
--sqlite-path		Path to SQLite database
--config		Path to server config file
--provider-key		Provider API key (provider=key)
--tls-cert		Path to TLS certificate file
--tls-key		Path to TLS key file
--read-timeout	30s	HTTP read timeout
--write-timeout	60s	HTTP write timeout
--max-body	10MB	Maximum request body size
--workflow-schedule-poll	10s	Polling interval for scheduled workflows

Examples

# Start on default port
petalflow serve

# Start on custom port with CORS
petalflow serve --port 3000 --cors-origin "http://localhost:5173"

# Start with TLS
petalflow serve --tls-cert cert.pem --tls-key key.pem

# Start with SQLite persistence
petalflow serve --sqlite-path /var/lib/petalflow/data.db

# Start with provider keys
petalflow serve --provider-key openai=sk-... --provider-key anthropic=sk-ant-...

API Endpoints

The server exposes these REST endpoints:

Health Check

Method	Path	Description
GET	/health	Server health check

Workflows

Method	Path	Description
GET	/api/workflows	List all workflows
POST	/api/workflows	Create/upload workflow
GET	/api/workflows/:id	Get workflow by ID
DELETE	/api/workflows/:id	Delete workflow
POST	/api/workflows/:id/run	Execute workflow

Runs

Method	Path	Description
GET	/api/runs	List all runs
GET	/api/runs/:id	Get run status/output
GET	/api/runs/:id/stream	Stream run events (SSE)
DELETE	/api/runs/:id	Cancel running workflow

Tools

Method	Path	Description
GET	/api/tools	List registered tools
POST	/api/tools	Register new tool
GET	/api/tools/:name	Get tool manifest
DELETE	/api/tools/:name	Unregister tool
POST	/api/tools/:name/test	Test tool invocation

Node Types

Method	Path	Description
GET	/api/node-types	List available node types

Server Configuration

Create a YAML configuration file for complex setups:

petalflow-server.yaml

server:
  host: 0.0.0.0
  port: 8080
  cors_origins:
    - http://localhost:3000
    - https://app.example.com

tls:
  cert: /etc/petalflow/cert.pem
  key: /etc/petalflow/key.pem

storage:
  sqlite_path: /var/lib/petalflow/data.db

providers:
  openai: ${OPENAI_API_KEY}
  anthropic: ${ANTHROPIC_API_KEY}

timeouts:
  read: 30s
  write: 60s
  workflow_poll: 10s

petalflow serve --config petalflow-server.yaml

---

petalflow tools

Manage tools for workflow execution. Tools can be native Go functions, HTTP endpoints, stdio executables, or MCP (Model Context Protocol) servers.

Usage

petalflow tools <subcommand> [flags]

Subcommands

Subcommand	Description
register	Register a new tool
list	List all registered tools
inspect	Show tool manifest details
unregister	Remove a tool from registry
config	Set or show tool configuration
test	Test a tool invocation
refresh	Re-discover MCP tool actions
overlay	Set or clear MCP overlay
health	Run tool health checks

---

tools register

Register a new tool with the tool registry.

petalflow tools register [flags] <tool-name>

Flags

Flag	Description
--type	Tool type: native, http, stdio, mcp
--manifest	Path to tool manifest JSON file
--endpoint	HTTP endpoint URL (for http type)
--command	Executable command (for stdio/mcp types)
--arg	Command arguments (can be repeated)
--env	Environment variables (can be repeated)
--transport-mode	MCP transport: stdio or sse
--overlay	MCP overlay configuration

Examples

# Register HTTP tool
petalflow tools register weather-api \
  --type http \
  --endpoint https://api.weather.com/v1

# Register stdio tool
petalflow tools register code-formatter \
  --type stdio \
  --command /usr/local/bin/prettier \
  --arg --stdin \
  --arg --parser=json

# Register MCP tool
petalflow tools register mcp-filesystem \
  --type mcp \
  --command npx \
  --arg @modelcontextprotocol/server-filesystem \
  --arg /path/to/allowed/directory \
  --transport-mode stdio

# Register from manifest file
petalflow tools register my-tool --manifest tool-manifest.json

Tool Manifest Format

{
  "name": "weather-lookup",
  "type": "http",
  "description": "Look up weather for a location",
  "endpoint": "https://api.weather.com/v1/current",
  "actions": [
    {
      "name": "get_weather",
      "description": "Get current weather for a city",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "City name"
          }
        },
        "required": ["city"]
      }
    }
  ]
}

---

tools list

List all registered and built-in tools.

petalflow tools list [flags]

Flags

Flag	Description
--format	Output format: table (default), json
--type	Filter by tool type

Examples

# List all tools
petalflow tools list

# List as JSON
petalflow tools list --format json

# Filter by type
petalflow tools list --type mcp

Output

NAME                TYPE    ACTIONS  STATUS
weather-api         http    2        healthy
code-formatter      stdio   1        healthy
mcp-filesystem      mcp     5        healthy
[built-in] echo     native  1        healthy
[built-in] sleep    native  1        healthy

---

tools inspect

Show detailed information about a registered tool.

petalflow tools inspect [flags] <tool-name>

Flags

Flag	Description
--actions	Show detailed action schemas

Examples

# Basic inspection
petalflow tools inspect weather-api

# With action details
petalflow tools inspect weather-api --actions

Output

Tool: weather-api
Type: http
Endpoint: https://api.weather.com/v1
Status: healthy

Actions:
  - get_current: Get current weather conditions
  - get_forecast: Get 7-day forecast

Config:
  api_key: [set]
  timeout: 30s

---

tools unregister

Remove a tool from the registry.

petalflow tools unregister <tool-name>

Examples

petalflow tools unregister weather-api

Caution

Unregistering a tool will cause workflows using that tool to fail. Ensure no active workflows depend on the tool before removing it.

---

tools config

Set or show tool configuration values.

petalflow tools config [flags] <tool-name>

Flags

Flag	Description
--set	Set a config value (key=value)
--set-secret	Set a secret config value (prompted or key=value)
--show	Show current configuration

Examples

# Show current config
petalflow tools config weather-api --show

# Set a config value
petalflow tools config weather-api --set timeout=30s

# Set a secret (will prompt for value)
petalflow tools config weather-api --set-secret api_key

# Set a secret with value
petalflow tools config weather-api --set-secret api_key=sk-...

Tip

Use --set-secret for sensitive values like API keys. Secrets are stored encrypted and won’t be displayed in logs or inspect output.

---

tools test

Test a tool invocation with sample input.

petalflow tools test [flags] <tool-name> <action-name>

Flags

Flag	Description
--input	Inline JSON input
--input-json	Path to JSON input file

Examples

# Test with inline input
petalflow tools test weather-api get_weather --input '{"city": "Seattle"}'

# Test with input file
petalflow tools test code-formatter format --input-json test-input.json

Output

Testing weather-api.get_weather...
Input: {"city": "Seattle"}
Output: {"temperature": 62, "conditions": "Partly Cloudy", "humidity": 75}
Duration: 234ms
Status: success

---

tools refresh

Re-discover actions for MCP tools. Use this after updating an MCP server.

petalflow tools refresh <tool-name>

Examples

petalflow tools refresh mcp-filesystem

This reconnects to the MCP server and updates the action registry with any new or modified tool definitions.

---

tools overlay

Set or clear an MCP overlay configuration. Overlays allow you to customize tool behavior without modifying the original MCP server.

petalflow tools overlay [flags] <tool-name>

Flags

Flag	Description
--set	Set overlay configuration (JSON)
--clear	Clear existing overlay

Examples

# Set an overlay
petalflow tools overlay mcp-filesystem --set '{"allowed_paths": ["/home/user/safe"]}'

# Clear overlay
petalflow tools overlay mcp-filesystem --clear

---

tools health

Run health checks on registered tools.

petalflow tools health [flags] [tool-name]

Flags

Flag	Description
--all	Check all registered tools

Examples

# Check specific tool
petalflow tools health weather-api

# Check all tools
petalflow tools health --all

Output

Checking tool health...

weather-api         OK      (234ms)
code-formatter      OK      (12ms)
mcp-filesystem      OK      (156ms)
broken-tool         FAIL    connection refused

3/4 tools healthy

---

Tool Types

PetalFlow supports four types of tools:

Native Tools

Go functions registered directly with the runtime. These are the fastest but require code changes to add new tools.

registry.Register(tools.Tool{
    Name: "calculate",
    Func: func(ctx context.Context, args CalcArgs) (CalcResult, error) {
        return CalcResult{Sum: args.A + args.B}, nil
    },
})

HTTP Tools

REST API endpoints that accept JSON input and return JSON output.

petalflow tools register api-tool \
  --type http \
  --endpoint https://api.example.com/v1/action

Stdio Tools

Command-line executables that communicate via stdin/stdout.

petalflow tools register formatter \
  --type stdio \
  --command /usr/bin/jq \
  --arg .

MCP Tools

Model Context Protocol servers providing tool capabilities. Supports both stdio and SSE transport modes.

# Stdio transport
petalflow tools register mcp-tool \
  --type mcp \
  --command npx \
  --arg @example/mcp-server \
  --transport-mode stdio

# SSE transport
petalflow tools register mcp-remote \
  --type mcp \
  --endpoint https://mcp.example.com/sse \
  --transport-mode sse

---

Exit Codes

The CLI uses these exit codes:

Code	Name	Description
0	Success	Command completed successfully
1	Validation	Workflow validation failed
2	Runtime	Runtime error during execution
3	FileNotFound	Specified file not found
4	InputParse	Failed to parse input JSON
5	Provider	LLM provider error
6	WrongSchema	Wrong workflow schema type
10	Timeout	Execution timeout exceeded

Using Exit Codes in Scripts

#!/bin/bash
petalflow run workflow.yaml -i '{}'
case $? in
  0) echo "Success" ;;
  1) echo "Validation error - check workflow syntax" ;;
  2) echo "Runtime error - check logs" ;;
  3) echo "File not found" ;;
  4) echo "Invalid input JSON" ;;
  5) echo "Provider error - check API keys" ;;
  6) echo "Wrong schema type" ;;
  10) echo "Timeout - increase --timeout value" ;;
  *) echo "Unknown error" ;;
esac

---

Environment Variables

Variable	Description
PETALFLOW_SQLITE_PATH	Default SQLite database path
PETALFLOW_TOOLS_STORE_PATH	Default tools registry path
PETALFLOW_CONFIG	Default config file path
PETALFLOW_LOG_LEVEL	Log level: debug, info, warn, error
PETALFLOW_NO_COLOR	Disable colored output (1 or true)

Provider API keys can also be set via environment variables:

Variable	Provider
OPENAI_API_KEY	OpenAI
ANTHROPIC_API_KEY	Anthropic
GEMINI_API_KEY	Google Gemini
OLLAMA_HOST	Ollama (local)

---

Configuration File

Create ~/.petalflow/config.yaml for persistent settings:

~/.petalflow/config.yaml

defaults:
  timeout: 60s
  format: json
  store_path: ~/.petalflow/tools.db

providers:
  openai: ${OPENAI_API_KEY}
  anthropic: ${ANTHROPIC_API_KEY}

logging:
  level: info
  format: text

output:
  color: true
  verbose: false

---

Human-in-the-Loop

When running workflows with human-in-the-loop nodes, the CLI operates in auto-approve mode by default. This means approval requests are automatically accepted.

For interactive approval, use the serve command and interact via the REST API or a connected UI client.

# Auto-approve mode (default CLI behavior)
petalflow run workflow-with-approval.yaml -i '{}'

# Interactive mode via server
petalflow serve --port 8080
# Then use UI or API to handle approvals

---

Best Practices

Practice	Recommendation
Validation first	Run validate before run in CI pipelines
Use timeouts	Always set --timeout for production runs
Store provider keys	Use environment variables or config, not CLI flags
Health checks	Run tools health --all periodically
Streaming for long runs	Use --stream for workflows > 30 seconds
Exit code handling	Check exit codes in scripts and automation

Next Steps

Getting Started

Build your first workflow. Getting Started

API Reference

Explore the Go API. API Reference

Examples

Production workflow examples. Examples