CLI reference

The ecp CLI runs workflows in configured environments on Node.js.

Install

npm install -g @executioncontrolprotocol/cli

From a monorepo build: pnpm link --global inside packages/cli after pnpm run build. See Build from source.

Commands

`ecp run`

ecp run examples/01-echo/workflow.ts --env examples/01-echo/environment.ts
ecp run examples/07-accepts-returns/workflow.ts --env examples/07-accepts-returns/environment.ts --input examples/07-accepts-returns/input.json
ecp run workflow.json --env environment.ts --input input.json
ecp run workflow.ts --env environment.ts --dry-run

Flag	Role
`--env`	Environment module (default export)
`--input`	JSON object validated against `workflow.accepts` before execute
`--dry-run`	Same accepts gate, then complete without invoking capabilities

Invalid --input exits non-zero with Workflow accepts validation failed (including --dry-run). Extra unused keys on a valid object are allowed.

`ecp validate`

Checks the workflow graph and environment (bound capabilities). It does not check run input against workflow.accepts — use ecp run or --dry-run for that.

ecp validate examples/01-echo/workflow.ts --env examples/01-echo/environment.ts

`ecp compile`

Compile Fluent/TS (or JS) workflow source to portable JSON. No --env required.

ecp compile examples/01-echo/workflow.ts -o dist/workflow.json

`ecp describe` / `ecp search`

Bare ecp describe returns a light inventory (id, label, summary). Pass --capability or --extension with an exact id for full metadata and JSON Schema I/O. Search returns ranked ids; follow up with describe for detail.

ecp describe --env examples/01-echo/environment.ts
ecp describe --env examples/01-echo/environment.ts --capability @executioncontrolprotocol/test.echo
ecp describe --env examples/01-echo/environment.ts --extension @executioncontrolprotocol/test
ecp search "echo" --env examples/01-echo/environment.ts

`ecp encode` / `ecp decode`

Require an environment that binds the format extension you use.

ecp encode workflow.json --format toon --env environment.ts -o workflow.toon
ecp encode workflow.json --format fluent --env environment.ts -o workflow.generated.ts
ecp decode workflow.toon --format toon --env environment.ts -o workflow.json

Fluent decode is not supported — use ecp compile instead. JSON is the canonical manifest format.

`ecp invoke`

Call a single capability outside a workflow run:

ecp invoke @executioncontrolprotocol/test.echo --env examples/01-echo/environment.ts --input input.json
ecp invoke @executioncontrolprotocol/harness-browser-nano.evaluate --env environment.ts --input in.json --uses @executioncontrolprotocol/ollama.generate

Flag	Role
`--env`	Environment module
`--input`	JSON capability input
`--uses`	Optional provider capability override (harness `.uses`)

`ecp serve`

Serve a bound environment over loopback HTTP (POST /v1/invoke, no auth). For the Ollama browser demo bridge with pairing, use ecp up instead.

ecp serve --env examples/01-echo/environment.ts
ecp serve --env environment.ts --port 3090 --cors-origin http://localhost:5173

Default host 127.0.0.1, port 3090.

`ecp up`

Start a loopback HTTP daemon that bridges Ollama for the browser demo (CORS + Private Network Access), then open the demo with a pairing token:

ecp up
# Opens https://demo.executioncontrolprotocol.io/?token=<uuid>&bridge=http://127.0.0.1:3090

ecp up --open-url http://localhost:5173/
ecp up --no-open

Default port 3090
GET /health — { ok, version, ollamaReachable } (no auth)
POST /v1/invoke — Bearer token; body { capability, input?, provider? }

Hosted HTTPS demos need Chromium for Private Network Access. Add origins with --cors-origin when needed. Local Vite or monorepo linking for the Graph Editor is documented in the browser-demo repository.

`ecp test`

Drive a workflow with a persistent test session that freezes state between operations. This is distinct from monorepo unit tests (npm run test:unit) or harness eval matrices.

ecp test start examples/01-echo/workflow.ts --env examples/01-echo/environment.ts -o session.json
ecp test run --to echo --env examples/01-echo/environment.ts --session session.json
ecp test rerun echo --env examples/01-echo/environment.ts --session session.json
ecp test status --session session.json

Subcommand	Role
`start`	Create an idle session snapshot (`-o` / `--output` required; optional `--input`)
`run --to <step-id>`	Inclusive run-through; skip completed prior steps; rewrite `--session`
`rerun <step-id>`	Rerun one step; clear downstream history and `.as` state
`status`	Print session snapshot summary

`ecp config secrets`

OS keychain helpers:

ecp config secrets add KEY
ecp config secrets add KEY --value …
ecp config secrets list
ecp config secrets get KEY
ecp config secrets remove KEY

Bind stored secrets into environments with secrets("KEY") — see Security and Environments.

Getting started

Learn

Build

Alternatives

AI tools

Reference

CLI reference

CLI reference

Install

Commands

`ecp run`

`ecp validate`

`ecp compile`

`ecp describe` / `ecp search`

`ecp encode` / `ecp decode`

`ecp invoke`

`ecp serve`

`ecp up`

`ecp test`

`ecp config secrets`

Next steps

​CLI reference

​Install

​Commands

​ecp run

​ecp validate

​ecp compile

​ecp describe / ecp search

​ecp encode / ecp decode

​ecp invoke

​ecp serve

​ecp up

​ecp test

​ecp config secrets

​Next steps

CLI reference

Install

Commands

`ecp run`

`ecp validate`

`ecp compile`

`ecp describe` / `ecp search`

`ecp encode` / `ecp decode`

`ecp invoke`

`ecp serve`

`ecp up`

`ecp test`

`ecp config secrets`

Next steps