Quickstart: From Install to First Simulation Verdict

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:

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:

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.

npx @egma/cli --url http://localhost:3101

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.

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.

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:

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

Connect exit codes

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:

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:

npx @egma/cli --existing-tests path/to/your-cases.md

Each generated test file looks like this:

---
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:

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

Run exit codes

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.

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:

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.

CLI Reference

Every command, option, and exit code — including egma self-host for running your own instance.

Self-Hosting

Run Egma on your own infrastructure with Docker Compose.

Get Started

Core Concepts

Integrations

CLI Reference

Configuration

Quickstart: From Install to First Simulation Verdict

Step 1 — Install and launch the wizard

Step 3 — Register your agent with `egma connect`

Step 4 — Initialize the test folder with `egma init`

Step 5 — Generate your first test suite

Step 6 — Run tests with `egma run`

Keeping tests in sync

What to read next

CLI Reference

Self-Hosting

​Step 1 — Install and launch the wizard

​Step 2 — Authenticate with egma login

​Step 3 — Register your agent with egma connect

​Step 4 — Initialize the test folder with egma init

​Step 5 — Generate your first test suite

​Step 6 — Run tests with egma run

​Keeping tests in sync

​What to read next

CLI Reference

Self-Hosting

Step 1 — Install and launch the wizard

Step 2 — Authenticate with `egma login`

Step 3 — Register your agent with `egma connect`

Step 4 — Initialize the test folder with `egma init`

Step 5 — Generate your first test suite

Step 6 — Run tests with `egma run`

Keeping tests in sync

What to read next