CLI Reference

PetalFlow CLI

petalflow supports workflow validation, compilation, execution, daemon hosting, and tool registry management.

Install

go install github.com/petal-labs/petalflow/cmd/petalflow@latest
petalflow --version

Global Flags

Flag	Description
`--verbose`	Enable verbose/debug logging
`--quiet`	Suppress non-error output
`--no-color`	Disable colored output

Commands

run

Execute a workflow file (agent or graph).

compile

Compile Agent/Task workflow into Graph IR JSON.

validate

Validate workflow schema and graph integrity.

serve

Start daemon APIs for workflows, tools, schedules, and events.

tools

`petalflow run`

petalflow run <file> [flags]

Flags

Flag	Description
`--input`, `-i`	Inline JSON input object
`--input-file`, `-f`	Read input JSON/YAML from file
`--output`, `-o`	Write output envelope to file
`--format`	`json`, `text`, or `pretty` (default: `pretty`)
`--timeout`	Run timeout (default: `5m`)
`--dry-run`	Validate + compile only, do not execute
`--env`	Set env var (`KEY=VALUE`, repeatable)
`--provider-key`	Provider credential (`name=key`, repeatable)
`--store-path`	SQLite path for tool registry
`--stream`	Stream `node.output.delta` content

Examples

petalflow run workflow.yaml --input '{"topic":"release notes"}'
petalflow run workflow.yaml --input-file input.json --format json
petalflow run workflow.yaml --dry-run
petalflow run workflow.yaml --provider-key anthropic=sk-ant-...
petalflow run workflow.yaml --store-path /tmp/petalflow.db

`petalflow compile`

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

Flags

Flag	Description
`--output`, `-o`	Output path (stdout if omitted)
`--pretty`	Pretty JSON output (default: `true`)
`--validate-only`	Validate Agent/Task schema without emitting Graph IR

Notes

compile only accepts Agent/Task workflows.
Returns exit code 6 (WrongSchema) if input is Graph IR.

`petalflow validate`

petalflow validate <file> [flags]

Flags

Flag	Description
`--format`	`text` or `json`
`--strict`	Treat warnings as failures

Validation supports both Agent/Task and Graph IR workflows.

`petalflow serve`

petalflow serve [flags]

Flags

Flag	Default	Description
`--host`	`0.0.0.0`	Listen host
`--port`, `-p`	`8080`	Listen port
`--cors-origin`	`*`	Allowed CORS origin
`--sqlite-path`	`~/.petalflow/petalflow.db`	SQLite database path
`--config`	auto-discover	Tool startup config (`petalflow.yaml`)
`--provider-key`	-	Provider key (`name=key`, repeatable)
`--tls-cert` / `--tls-key`	-	TLS cert/key files
`--read-timeout`	`30s`	HTTP read timeout
`--write-timeout`	`60s`	HTTP write timeout
`--max-body`	`1048576`	Max request bytes
`--workflow-schedule-poll`	`5s`	Schedule polling interval

Core Daemon Endpoints

Method	Path
`GET`	`/health`
`GET`	`/api/node-types`
`POST`	`/api/workflows/agent`
`POST`	`/api/workflows/graph`
`GET`	`/api/workflows`
`GET`	`/api/workflows/{id}`
`PUT`	`/api/workflows/{id}`
`DELETE`	`/api/workflows/{id}`
`POST`	`/api/workflows/{id}/run`
`ANY`	`/api/workflows/{id}/webhooks/{trigger_id}`
`GET`	`/api/workflows/{id}/schedules`
`POST`	`/api/workflows/{id}/schedules`
`GET`	`/api/workflows/{id}/schedules/{schedule_id}`
`PUT`	`/api/workflows/{id}/schedules/{schedule_id}`
`DELETE`	`/api/workflows/{id}/schedules/{schedule_id}`
`GET`	`/api/runs/{run_id}/events`

Tool Endpoints

Method	Path
`POST`	`/api/tools`
`GET`	`/api/tools`
`GET`	`/api/tools/{name}`
`PUT`	`/api/tools/{name}`
`DELETE`	`/api/tools/{name}`
`PUT`	`/api/tools/{name}/config`
`POST`	`/api/tools/{name}/test`
`GET`	`/api/tools/{name}/health`
`POST`	`/api/tools/{name}/refresh`
`PUT`	`/api/tools/{name}/overlay`
`PUT`	`/api/tools/{name}/disable`
`PUT`	`/api/tools/{name}/enable`

`petalflow tools`

petalflow tools <subcommand> [flags]

Persistent flag:

--store-path: SQLite path (default: ~/.petalflow/petalflow.db)

Subcommands

Subcommand	Purpose
`register <name>`	Register tool (`native`, `http`, `stdio`, `mcp`)
`list`	List built-in + registered tools
`inspect <name>`	Show manifest/registration details
`unregister <name>`	Remove registration
`config <name>`	Set/show config and secrets
`test <name> <action>`	Invoke tool action with test input
`refresh <name>`	Re-discover MCP actions
`overlay <name> --set <path>`	Set/clear MCP overlay
`health [name]` / `--all`	Run MCP health checks

Examples

petalflow tools list
petalflow tools inspect template_render --actions
petalflow tools register echo_http --type http --manifest ./echo_http.tool.json
petalflow tools config echo_http --set region=us-west-2
petalflow tools config echo_http --set-secret api_key=sk-...
petalflow tools test echo_http echo --input value=hello
petalflow tools refresh s3_fetch
petalflow tools overlay s3_fetch --set ./s3_fetch.overlay.yaml
petalflow tools health --all

Exit Codes

Code	Meaning
`0`	Success
`1`	Validation failure
`2`	Runtime failure
`3`	File not found
`4`	Input parse error
`5`	Provider resolution/auth error
`6`	Wrong workflow schema for command
`10`	Timeout

Environment Variables

Variable	Purpose
`PETALFLOW_SQLITE_PATH`	Default SQLite path for run/tools/serve
`PETALFLOW_TOOLS_STORE_PATH`	Backward-compatible store path fallback
`PETALFLOW_CONFIG`	Optional config path override

Provider credentials can be passed via --provider-key or resolved from environment/config.