> ## Documentation Index > Fetch the complete documentation index at: https://executioncontrolprotocol.io/llms.txt > Use this file to discover all available pages before exploring further. # CLI reference > ecp run, ecp validate, and ecp trace 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](https://oclif.io/): 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 --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`). ```bash theme={null} ecp run [options] ``` **Required:** * **context.yaml** — Path to the Context YAML file (also accepts `context.json`). **Common options:** | Option | Description | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--enable ` | Enable a plugin by ID (e.g. model providers `openai`, `ollama`). Repeat for multiple. | | `-i`, `--input` | Set input `key=value`. Repeat for each input (e.g. `-i topic=test`). | | `--provider` | Optional model provider: `openai` or `ollama`. If omitted, it is inferred from the Context. | | `--model` | Override model name (e.g. for Ollama: `llama3.2:3b`). | | `--config` | Path to system config file (e.g. `ecp.config.yaml`). | | `--ollama-base-url` | Ollama API base URL (default `http://localhost:11434`). | | `-t`, `--[no-]trace` | Enable tracing (default) or disable with `--no-trace`. | | `--trace-dir` | Directory for trace files (default `~/.ecp/traces`). | | `--debug` | Enable debug logging. | | `--environment ` | 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):** ```bash theme={null} ecp run examples/single-executor/context.yaml --enable openai -i topic="ECP" ``` **Example (Ollama):** ```bash theme={null} 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: ```bash theme={null} ecp validate [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 `** — Same semantics as `ecp run`: selects the `.env` file for the **`dot.env`** provider (future-proof for validation tooling that resolves secrets). **Example:** ```bash theme={null} ecp validate spec.yaml -i shopifyStoreId=demo -i jiraProject=DEMO ``` ### trace Display a saved execution trace from a previous `ecp run`: ```bash theme={null} ecp trace [--output text|graph] [--trace-dir ] ``` | Option | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `--output` | Render mode: `text` (human log) or `graph` (ASCII visualization). Default: `text`. | | `--trace-dir` | Directory for trace files (default `~/.ecp/traces`). | | `--environment ` | Optional; same as on `run` — selects the `.env` file for **`dot.env`** when trace tooling is wired to secret resolution. | Examples: ```bash theme={null} 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: ```bash theme={null} ecp trace list [--trace-dir ] ``` Accepts **`--environment `** 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](/learn/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 ` 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](https://github.com/executioncontrolprotocol/executioncontrolprotocol/blob/main/SPEC.md#L623), annotated [config/ecp.config.example.yaml](https://github.com/executioncontrolprotocol/executioncontrolprotocol/blob/main/config/ecp.config.example.yaml), and TypeScript [`ECPSystemConfig`](https://github.com/executioncontrolprotocol/executioncontrolprotocol/blob/main/packages/runtime/src/engine/types.ts#L484). See [Security](/learn/security) for the security model and [SETUP.md](https://github.com/executioncontrolprotocol/executioncontrolprotocol/blob/main/SETUP.md) for setup. ## See also * [Quickstart](/getting-started/quickstart) — First run * [Development](/getting-started/development) — Global install and env * [SETUP.md](https://github.com/executioncontrolprotocol/executioncontrolprotocol/blob/main/SETUP.md) — Full setup guide