> ## 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. # Quickstart: From Install to First Simulation Verdict > Install the Egma CLI, connect your Retell or LiveKit agent, auto-generate a test suite, and see your first simulation verdicts in one wizard session. The fastest path to your first Egma test run is the CLI wizard. Run it from your voice agent's repository and it handles everything in sequence: signing in, registering your agent, generating tests with your existing coding agent, and starting a run. This guide walks you through each step so you know exactly what to expect before you press a key. You need Node 22 or newer and a coding agent installed — Claude Code or Codex both work. You do not need a global `egma` install; `npx` fetches the latest version on each run. ## Step 1 — Install and launch the wizard Open a terminal in the repository that contains your voice agent and run: ```bash theme={null} npx @egma/cli ``` The wizard opens on the terminal's alternate screen. It tells you what it is about to do and waits for one keystroke before it starts. If you are running in CI or want plain output without the interactive UI, pass `--headless`: ```bash theme={null} npx @egma/cli --headless ``` If you self-host Egma, pass `--url` to point the wizard at your instance. The wizard records your instance's verified identity in `egma/config.yaml` and every subsequent command in the repository finds it there automatically. ```bash theme={null} npx @egma/cli --url http://localhost:3101 ``` ## Step 2 — Authenticate with `egma login` The wizard signs this machine in automatically as part of the flow, but you can also run the login step on its own — for example in CI, or to sign in to a self-hosted instance before running `self-host setup`. ```bash theme={null} egma login ``` Egma displays a short code, opens your browser on a page that already has the code in the field, and waits for you to approve it there. No secret is ever typed into the terminal. **Expected 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 ``` The key is written to `~/.egma/credentials`, readable only by you. Set `EGMA_HOME` to store it somewhere else. **On a machine with no browser** — over SSH, in a container — press `[c]` after the code appears and Egma copies the approval URL to your clipboard. Open it in a browser on another machine, approve it, then paste back the full address, the `?user_code=…` part, or just the code. | Code | Meaning | | ----- | ------------------------------------------- | | `0` | Signed in successfully | | `2` | Authentication was denied | | `3` | The device code expired before approval | | `4` | Egma did not answer, or refused the request | | `130` | Interrupted (Ctrl-C) | ## Step 3 — Register your agent with `egma connect` The wizard handles agent registration as part of its flow, but you can run it separately — useful for headless environments or registering an agent without running the full wizard. ```bash theme={null} egma connect ``` The CLI asks for your Retell API key (or LiveKit credentials) and then asks how Egma should reach the agent: * **Text** — Egma exchanges messages with your agent. No phone call, nothing dialled. Exercises the prompt, reasoning, and tools. * **Phone** — Egma dials one of your agent's numbers over the telephone network. Exercises the full speech stack and the carrier path as well. Egma creates the one connection type you choose and never both. If you want both, run `egma connect` twice and choose a different reach each time. The second run reuses the same agent registration and adds the new connection to it. Pass credentials through environment variables rather than as arguments — arguments are visible to every process on your machine and are saved in shell history: ```bash theme={null} EGMA_RETELL_API_KEY=key_… egma connect --reach text # or cat retell-key.txt | egma connect --reach phone --phone-number +14155550111 ``` **Expected output:** ``` url: http://localhost:3101 retell_agents: 1 retell_agent_id: agent_… reach: text agent_id: agt_01K… agent_name: order-line connection_id: con_01K… connection_name: text-1 connection_type: text registration: created agent_registration: created connection_registration: created status: connected ``` | Code | Meaning | | ----- | -------------------------------------------------------------- | | `0` | Agent connected successfully | | `2` | The API key was refused by Retell | | `3` | No agents found on that Retell account | | `4` | Retell or Egma did not answer | | `5` | A required choice was not made (agent, reach, or phone number) | | `6` | No API key provided | | `7` | Not signed in to Egma | | `8` | Retell routes no number to that agent | | `130` | Interrupted (Ctrl-C) | ## Step 4 — Initialize the test folder with `egma init` Egma stores your tests as Markdown files in your repository. `egma init` creates the folder structure: ```bash theme={null} egma init ``` This creates: ``` egma/ config.yaml what this folder points at — instance URL and IDs mock-tools.md default tool mock responses for simulations tests/ one .md file per test scenario ``` Everything in this folder is committed to version control. No secrets ever land here. ## Step 5 — Generate your first test suite Back in the full wizard flow, once your agent is connected and the folder is initialized, the wizard asks your coding agent to read your repository — the prompt, tools, and framework — and write a first suite of tests into `egma/tests/`. Tests arrive one file at a time on screen while the coding agent works. If you already have test cases written down in a spreadsheet or document, pass the path and the wizard converts them first: ```bash theme={null} npx @egma/cli --existing-tests path/to/your-cases.md ``` Each generated test file looks like this: ```markdown theme={null} --- name: missed-appointment-reschedule personas: [impatient-caller] --- ## Scenario The caller missed yesterday's appointment and wants to reschedule this week. They are short on time and irritated. ## Expected behaviors 1. The agent acknowledges the missed appointment without blame. 2. The agent offers at least two concrete alternative slots. 3. The agent confirms the new booking before ending the call. ``` Before starting the run, the wizard shows you the full list of generated tests and pauses: ``` 12 tests generated · suite "first-suite" › quoted-a-price default persona lost-the-order-number default persona open-on-sunday somebody-in-a-hurry … 9 more (↑↓ browse · e opens in $EDITOR) Run these against order-line over text-1? [enter] run [e] edit first [q] quit ``` Press `[e]` to open any test in `$EDITOR` before committing to the run. Press `[q]` to exit with all files saved to your repository — you can push and run them later with `egma push` and `egma run`. ## Step 6 — Run tests with `egma run` Press `[enter]` in the wizard, or run the command directly after pushing your tests: ```bash theme={null} egma push # sync local files to Egma egma run # start a run and follow it ``` The simulator claims each simulation, conducts the conversation, and the grader writes one verdict per expected behavior as each call ends. The wizard follows the run live: ``` run run_01K7QXV2M8 · 12 simulations ◼ quoted-a-price passed ▶ lost-the-order-number in progress ▶ open-on-sunday dialing… ◻ after-hours-emergency queued ✓ First verdict: quoted-a-price passed passed 1 · failed 0 · skipped 0 · errored 0 · waiting 11 ``` The wizard closes after the first verdict arrives. The run continues on Egma — closing your terminal never stops a run. **Full `egma run` output:** ``` url: http://localhost:3101 folder: /repo/egma agent: agt_01K… connection: con_01K… run: run_01K… tests: 12 simulations: 12 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: 0 errored: 0 pending: 11 ``` | Code | Meaning | | ----- | ------------------------------------------- | | `0` | Run finished with no failures or errors | | `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, and said why | | `6` | A simulation errored — nothing concluded | | `130` | Interrupted (Ctrl-C) | Pass `--no-follow` to start a run and return immediately without waiting for verdicts. The run carries on on Egma and you can read results in the dashboard at the URL printed on the `results:` line. ```bash theme={null} egma run --no-follow ``` ## Keeping tests in sync After the first run, use `pull` and `push` to keep your local files and Egma in step: ```bash theme={null} egma pull # write Egma's current versions into your files egma push # upload your local changes to Egma ``` `egma push` refuses when Egma holds a newer version than your local file, naming each conflict. Run `egma pull` first, review what changed, then push again. ## What to read next Every command, option, and exit code — including `egma self-host` for running your own instance. Run Egma on your own infrastructure with Docker Compose.