> ## Documentation Index > Fetch the complete documentation index at: https://docs.egma.ai/llms.txt > Use this file to discover all available pages before exploring further. # Egma CLI Command Reference — All Commands and Flags > Full reference for every Egma CLI command: usage syntax, key flags, exit codes, and environment variables for scripting and CI pipelines. Every Egma command prints one fact per line and exits with a numeric code you can branch on. This makes every command safe to call from a CI pipeline, a shell script, or a coding agent — no screen-scraping required. Commands that need a real terminal (the interactive wizard) refuse piped or redirected input and tell you to pass `--headless` instead. ## Global flags These flags work with every command. | Flag | Description | | --------------------- | --------------------------------------------------------------------------------------------------- | | `--coding-agent ` | Which coding agent to drive, using the name from the agent registry. Default: `claude-acp` | | `--cwd ` | The folder to operate in. Default: the current directory | | `--url
` | Which Egma instance this command talks to. Overrides any value in `egma/config.yaml` | | `--force` | With `login`: sign in again even when this machine already holds a key | | `--no-follow` | With `run`: start the run and return immediately, without waiting for a verdict | | `--headless` | Run with no terminal interaction: plain output, and the coding-agent task treated as already agreed | | `-h`, `--help` | Print the help text | | `-v`, `--version` | Print the package version | ## Environment variables Set these in your shell or CI environment to avoid repeating flags on every command. | Variable | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `EGMA_HOME` | The folder Egma stores this machine's credentials in. Default: `~/.egma` | | `EGMA_RETELL_API_KEY` | Your Retell API key for `egma connect`. `RETELL_API_KEY` is also accepted, so an environment that already exports it needs no change | | `EGMA_RETELL_AGENT_ID` | Which Retell agent to register, equivalent to `--retell-agent` | | `EGMA_REACH` | `text` or `phone`, equivalent to `--reach` | | `EGMA_PHONE_NUMBER` | Which phone number to dial, equivalent to `--phone-number` | | `EGMA_RETELL_URL` | The Retell API base URL. Default: `https://api.retellai.com` | | `EGMA_EXISTING_TESTS` | Path to your existing test cases, equivalent to `--existing-tests` | | `VISUAL`, `EDITOR` | The editor opened when you press `[e]` at the test-review gate | *** ## Commands Opens the full interactive wizard. It signs you in, discovers your voice agent using your coding agent, connects the agent to Egma, generates a first test suite, and starts a run — all in one guided flow. The wizard draws on your terminal's alternate screen. When it closes it leaves a single results URL and a plain summary in your normal terminal buffer, each item on its own line so a triple-click selects it whole. **Usage** ```bash theme={null} npx @egma/cli [options] ``` **Key flags** | Flag | Description | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `--url
` | Which Egma instance to use for this run | | `--coding-agent ` | Which coding agent to drive. Default: `claude-acp` | | `--headless` | Run non-interactively; treats the task as already agreed | | `--existing-tests ` | Path to your existing test cases inside this folder. Your coding agent converts them to test files before generating new ones | | `--reach ` | Required in headless mode: how Egma should reach the agent | **Exit codes** | Code | Meaning | | ----- | -------------------------------- | | `0` | Completed successfully | | `130` | Stopped partway through (Ctrl-C) | The wizard requires a real terminal to display the consent keystroke. Pass `--headless` to run it in CI or from a script — this treats the coding-agent task as already agreed and produces plain line output. Signs this machine in to Egma. Opens a browser to a device-approval page pre-filled with a short code. Once you approve it, Egma stores a credential at `~/.egma/credentials` (or `$EGMA_HOME/credentials`), readable only by you. No secret is ever typed into the terminal. If the machine already holds a valid credential, `egma login` says so and exits without changing anything. **Usage** ```bash theme={null} egma login [options] ``` **Key flags** | Flag | Description | | ----------------- | ---------------------------------------------------------------------- | | `--url
` | Sign in to a specific Egma instance | | `--force` | Sign in again even when this machine already holds a key, replacing it | **Example output** ``` url: http://localhost:3101 code: WDJBMJHT approve_url: http://localhost:3101/device?user_code=WDJBMJHT browser: opened waiting: for this code to be approved in a browser status: stored credentials: /home/you/.egma/credentials ``` **Exit codes** | Code | Meaning | | ----- | ------------------------------------------- | | `0` | Signed in successfully | | `2` | Approval was denied | | `3` | The device code expired before approval | | `4` | Egma did not answer, or refused the request | | `130` | Stopped partway through | On a machine without a browser (SSH, devbox, container), press `[c]` during the wait and Egma copies the approval URL to your local clipboard. Approve it in a browser, then paste the full URL, the `?user_code=…` portion, or just the code — all three work. Registers your voice agent with Egma and creates a connection for running simulations. Reads a Retell API key from standard input or from the environment — never as a command-line argument, because arguments appear in process lists and shell history. Running `egma connect` twice against the same agent is safe. Egma detects the existing registration and reports whether it `created`, `reused`, or `connection_added` on the `registration:` line. **Usage** ```bash theme={null} # Key on standard input cat retell-key.txt | egma connect [options] # Key from environment EGMA_RETELL_API_KEY=your_key egma connect [options] ``` **Key flags** | Flag | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--reach ` | **Required** in non-interactive mode. `text` for message-based simulation; `phone` to dial a real number. Egma creates exactly one connection and never both | | `--retell-agent ` | Which Retell agent to register when the account holds more than one | | `--phone-number ` | Which number to dial when `--reach phone` and the agent has more than one number | | `--repo-prompt ` | The prompt file in your repository, so Egma can report whether it and Retell have drifted apart | **Environment variables** | Variable | Equivalent flag | | ---------------------- | -------------------------------------- | | `EGMA_RETELL_API_KEY` | Retell API key (also `RETELL_API_KEY`) | | `EGMA_RETELL_AGENT_ID` | `--retell-agent` | | `EGMA_REACH` | `--reach` | | `EGMA_PHONE_NUMBER` | `--phone-number` | **Example output** ``` url: http://localhost:3101 retell_agents: 1 retell_agent_id: agent_… retell_response_engine: retell-llm prompt_characters: 2140 tools: 7 reach: phone phone_number: +14155550111 agent_id: agt_01K… agent_name: order-line connection_id: con_01K… connection_name: phone-1 connection_type: phone connection_modality: voice registration: created agent_registration: created connection_registration: created drift: no grounded_in: retell status: connected ``` **Exit codes** | Code | Meaning | | ----- | ------------------------------------------------------------------------------- | | `0` | Connected successfully | | `2` | The Retell API key was refused | | `3` | No agents found on the Retell account | | `4` | Retell or Egma did not answer, or refused | | `5` | A required choice was not made: which agent, `text` or `phone`, or which number | | `6` | No API key was provided | | `7` | Not signed in to Egma | | `8` | Retell routes no phone number to that agent | | `130` | Stopped partway through | Creates the `egma/` folder structure in your repository. Everything `init` creates is safe to commit — nothing secret ever lands in the folder. Run it again safely at any time; it will not overwrite files that already exist. When you pass `--url`, `init` contacts that Egma instance, verifies its identity, and records the result in `egma/config.yaml`. Every subsequent command run from this repository then finds the instance address automatically, with no `--url` flag required. **Usage** ```bash theme={null} egma init [options] ``` **Key flags** | Flag | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `--url
` | Which Egma instance to bind this repository to. Egma verifies the instance's identity and writes it to `egma/config.yaml` | | `--agent ` | What to call the voice agent this folder's tests are for | | `--connection ` | What to call the connection Egma uses to reach it | | `--suite ` | What to call this folder's test suite | **Exit codes** | Code | Meaning | | ---- | ------------------------------------------------------------- | | `0` | Folder created or already in good shape | | `4` | Egma did not answer, or refused (only when `--url` is passed) | Writes Egma's current versions of every test in the `egma/` folder into your local files, updating the `version:` field in each file's front matter. Use `pull` to get changes made by teammates in the Egma dashboard before you start editing locally. **Usage** ```bash theme={null} egma pull [options] ``` **Example output** ``` url: http://localhost:3101 folder: /repo/egma test: missed-appointment-reschedule file: egma/tests/missed-appointment-reschedule.md version: tstv_01K… status: updated ``` **Exit codes** | Code | Meaning | | ----- | ------------------------------- | | `0` | All tests pulled successfully | | `1` | No `egma/` folder found | | `2` | Not signed in to Egma | | `4` | Egma did not answer, or refused | | `130` | Stopped partway through | Uploads the tests in your `egma/` folder to Egma, creating a new version of each test and writing the new version ID back into the file's front matter. A successful push never overwrites previous versions — results from last week still reference exactly what they ran. `push` refuses when Egma holds a version newer than the one your file last synced at. It names every conflicting file on a `conflict:` line, uploads nothing, and exits `5`. Run `egma pull` first, review what changed, then push again. **Usage** ```bash theme={null} egma push [options] ``` **Example output (conflict)** ``` conflict: missed-appointment-reschedule file: egma/tests/missed-appointment-reschedule.md uploaded: nothing status: refused ``` **Exit codes** | Code | Meaning | | ----- | ------------------------------------------------------- | | `0` | All tests pushed successfully | | `1` | No `egma/` folder found | | `2` | Not signed in to Egma | | `4` | Egma did not answer, or refused | | `5` | Push refused: Egma has moved on — run `egma pull` first | | `6` | Egma rejected a test (e.g. no expected behaviors) | | `130` | Stopped partway through | Egma will not store a test with no expected behaviors — a test with none can never fail, which makes it meaningless. Fix the file and push again. Egma's refusal reason is printed verbatim. Runs every test in your `egma/` folder against your connected voice agent. Each test is pinned to its current version before the run starts, so the run record is an exact snapshot of what executed. The command follows the run, printing every change as it arrives. Before starting, `egma run` checks that your local folder and Egma agree on every test file's content. Any file Egma has never seen is listed on an `unknown:` line; any file whose content differs from Egma's version appears on a `not-pushed:` line. Either condition refuses the whole run — the fix is `egma push`. **Usage** ```bash theme={null} egma run [options] ``` **Key flags** | Flag | Description | | ------------- | ---------------------------------------------------------------------------------------------- | | `--no-follow` | Start the run and return immediately, without waiting for a verdict. The run continues on Egma | **Example output** ``` url: http://localhost:3101 folder: /repo/egma agent: agt_01K… connection: con_01K… pin: quoted-a-price tstv_01K… pin: lost-the-order-number tstv_01K… run: run_01K… tests: 2 simulations: 2 results: http://localhost:3101/runs/run_01K… simulation: quoted-a-price default-persona running verdict: quoted-a-price default-persona passed first-verdict: quoted-a-price default-persona passed passed: 1 failed: 0 skipped: 1 errored: 0 pending: 0 simulations: 2 status: completed ``` **Exit codes** | Code | Meaning | | ----- | -------------------------------------------------------- | | `0` | Run finished; nothing failed or errored | | `1` | No tests found in the `egma/` folder | | `2` | Not signed in to Egma | | `3` | At least one test failed | | `4` | Egma did not answer, or refused | | `5` | Egma refused to start the run (reason printed) | | `6` | At least one simulation errored — no conclusion possible | | `130` | Stopped partway through | A `skipped` result is not a failure. It means the test required something the connection cannot do (e.g. DTMF on a text connection). A `failed` result means the agent did not meet an expected behavior. Only `errored` means something went wrong with the simulation infrastructure itself. Starts a full local Egma instance using Docker Compose: Postgres, ClickHouse, the API, the web UI, the simulator, the grader, and (for phone simulations) a LiveKit server, SIP gateway, and Redis. Run this from your Egma platform checkout, not from your agent repository. After the stack is up, the command prints the address to point your agent repository at, and lists any platform configuration still missing. **Usage** ```bash theme={null} # From your Egma platform checkout npx @egma/cli self-host up ``` **Exit codes** | Code | Meaning | | ---- | ------------------------------------------ | | `0` | Instance started successfully | | `4` | Docker or a required service did not start | Configures a running Egma instance by asking for provider credentials and writing them through the platform API. Run this after `egma self-host up` and after signing in with `egma login --url
`. The command asks the platform what it is missing, then prompts you for exactly that — in a fixed order: the model provider (for persona reasoning), the speech provider (TTS and STT), and the telephony carrier (for phone simulations). A setting the platform already holds is never asked for again, so a second run only asks about what is still missing, and on a fully configured platform it changes nothing and says so. For the phone setup, Egma asks for a Twilio account, an existing voice number on that account, and the account's Auth Token. It shows a plan before writing anything to your carrier, and it never buys, ports, or registers a number. The Auth Token is used once and stored nowhere — what runs afterward holds a SIP credential for one trunk. **Usage** ```bash theme={null} # Sign in first, then configure egma login --url http://localhost:3101 egma self-host setup ``` **Exit codes** | Code | Meaning | | ---- | -------------------------------------------- | | `0` | Configuration complete (or already complete) | | `2` | Not signed in as an organization owner | | `4` | The platform API did not answer, or refused |