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).
Required:
  • context.yaml — Path to the Context YAML file (also accepts context.json).
Common options: Example (OpenAI):
Example (Ollama):

​
validate

Validate a Context manifest without running it:
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:

​
trace

Display a saved execution trace from a previous ecp run:
Examples:
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:
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