Skip to main content
The ECP CLI can run Context manifests, validate them, and inspect saved execution traces. Prefer installing the CLI once (via npm link) so you can use the ecp command from your shell.

​
Getting help

The CLI is built on oclif: built-in --help shows the authoritative list of commands and flags for your installed version.
  • ecp --help — Lists top-level commands (run, validate, trace, …).
  • ecp <command> --help — Full flags and arguments for that command, e.g. ecp run --help, ecp validate --help, ecp trace --help.
Use these when you need details beyond this page (short flags, defaults, or newly added options).

​
Commands

​
run

Execute a Context manifest. By default, ecp run enables tracing and saves traces under ~/.ecp/traces (disable with --no-trace). 
ecp run <context.yaml> [options]
Required:
  • context.yaml — Path to the Context YAML file (also accepts context.json).
Common options:
OptionDescription
--enable <name>Enable a plugin by ID (e.g. model providers openai, ollama). Repeat for multiple.
-i, --inputSet input key=value. Repeat for each input (e.g. -i topic=test).
--providerOptional model provider: openai or ollama. If omitted, it is inferred from the Context.
--modelOverride model name (e.g. for Ollama: llama3.2:3b).
--configPath to system config file (e.g. ecp.config.yaml).
--ollama-base-urlOllama API base URL (default http://localhost:11434).
-t, --[no-]traceEnable tracing (default) or disable with --no-trace.
--trace-dirDirectory for trace files (default ~/.ecp/traces).
--debugEnable debug logging.
--environment <path>Path to a .env file for the dot.env secret provider for this run only (overrides secrets.providers.dot.env.path in config). Does not merge into process.env.
Example (OpenAI): 
ecp run examples/single-executor/context.yaml --enable openai -i topic="ECP"
Example (Ollama): 
ecp run examples/single-executor/context.yaml --provider ollama --enable ollama --model llama3.2:3b -i topic="Test"

​
validate

Validate a Context manifest without running it: 
ecp validate <context.yaml> [options]
Options:
  • -i, —input — Provide required inputs so validation can succeed (e.g. -i shopifyStoreId=demo -i jiraProject=DEMO for spec.yaml).
  • —skip-inputs — Validate the Context manifest itself but skip runtime input resolution. Instead of failing, it prints which inputs are required.
  • --environment <path> — Same semantics as ecp run: selects the .env file for the dot.env provider (future-proof for validation tooling that resolves secrets).
Example: 
ecp validate spec.yaml -i shopifyStoreId=demo -i jiraProject=DEMO

​
trace

Display a saved execution trace from a previous ecp run: 
ecp trace <run-id> [--output text|graph] [--trace-dir <path>]
OptionDescription
--outputRender mode: text (human log) or graph (ASCII visualization). Default: text.
--trace-dirDirectory for trace files (default ~/.ecp/traces).
--environment <path>Optional; same as on run — selects the .env file for dot.env when trace tooling is wired to secret resolution.
Examples: 
ecp trace run-123...
ecp trace run-123... --output graph
Notes:
  • ecp graph is a hidden alias for ecp trace --output graph.
  • Traces are stored as JSON files in ~/.ecp/traces.

​
trace list

List locally available trace IDs: 
ecp trace list [--trace-dir <path>]
Accepts --environment <path> like ecp run (dotenv file for dot.env; no merge into process.env).

​
Environment

  • OPENAI_API_KEY — Used by the OpenAI provider when --provider openai (or when the Context implies OpenAI).
  • OLLAMA_BASE_URL — Optional; overrides Ollama base URL (default http://localhost:11434).
Secret bindings in Contexts use provider ids process.env, dot.env, and os.secrets (see Security). --environment only affects the file backing dot.env, not the shell environment.

​
System config

The CLI loads system config from (in order):
  1. --config <path>
  2. ./ecp.config.yaml
  3. ~/.ecp/config.yaml or ~/.ecp/ecp.config.yaml
v0.5 layout: wiring lives under models, tools, loggers, agents, secrets, optional executors / memory, and plugins.installs. Policy lives under the top-level security object, which mirrors those areas (security.models, security.tools, security.plugins, …). Legacy plugins.allowEnable / plugins.security keys are removed; use security.models.allowProviders, security.tools.allowServers, security.plugins, and related subtrees instead. Include version: "0.5" in the file. Use system config to register MCP servers under tools.servers, model providers under models.providers, and to restrict what the runtime may load via security.*. Inspect or update security with ecp config security get, ecp config security plugins update, and the rest of ecp config --help (plugins installs, models, tools, loggers, secrets, …). Contexts control which tools an executor may call via policies.toolAccess; the host still decides which server names exist and are allowed (security.tools.allowServers and configured tools.servers). Full spec: SPEC.md — Host system configuration, annotated config/ecp.config.example.yaml, and TypeScript ECPSystemConfig. See Security for the security model and SETUP.md for setup.

​
See also