egma

egma command [options]

egma is the command-line client for Egma, an open-source platform that simulation-tests voice agents and monitors them in production. The npm package is egma-cli; it installs the egma binary. Node.js 22 or newer is required.The CLI is built for both humans and coding agents: each invocation is one named operation with no wizard, no JSON mode, and no interactive setup state machine. Workflow (which agent to connect, which tests to write) stays in the repository and in optional agent skills (`integrate-egma`, `write-egma-tests`).Tests are ordinary Markdown files that live next to the voice-agent source. A file is one test: scenario, expected behaviors, personas, optional `## Mock tools`, and optional `## Env`. Suites are directories. egma push is the publish step; egma run create always pushes first and creates no run if that push fails.Egma Cloud is the default origin. Self-hosting uses the same CLI against `--url` (local default port 3101). LiveKit workers pointed at a self-hosted instance need EGMA_URL and a project-scoped EGMA_API_KEY.

login

Browser device login. --url URL selects Cloud or a self-hosted origin. Only login, logout, and init accept --url.

Revoke the saved device-login key for one origin. Does not revoke EGMA_API_KEY or change `egma/` in the repo.

Bind this repository to a project and pull its agents, connections, suites, and tests into `egma/`. --project ID is only needed for credentials that do not already identify one project.

Refresh the remote index, suites, and tests. Local unpushed test drafts are kept.

Validate, then upload the complete authored state. There is no separate public `validate` command.

Register an Egma agent identity. --platform `retell`|`livekit`, optional --name (default: repository directory name).

Print the platform's connection catalog (and, for Retell, discover provider agents). Needs the provider key on first discovery.

Add a simulation connection to an existing agent. Access and modality are explicit flags; provider secrets come from canonical environment variables or --credentials-stdin.

Start or stop production call pulls for an agent (--agent, --platform).

List personas available to the project.

Create a suite. Tests are Markdown files under `egma/tests/`DIR`/`.

Delete the remote suite, then the local directory.

Delete a remote test, then the local Markdown file.

Push, then start a run of every active test in that suite directory. Prints the run ID and results URL and returns.

Cancel an in-progress run.

Create a project-scoped API key. The secret is printed once and not stored.

Start local Egma services. Run this from an Egma platform checkout, not from a voice-agent repository.

Repository-local, non-secret selectors live in `egma/config.yaml` (format 4): platform origin, project id, and agent/connection ids. Provider agent ids, credentials, and connection secrets are not stored there; Egma seals those on the platform.Machine-local login state defaults to `~/.egma/`. Set EGMA_HOME to move it. EGMA_API_KEY, when set, takes precedence over a saved device login.Provider keys used only during setup:EGMA_RETELL_API_KEY

Retell API key for first-time discovery and the first Retell connection.

LiveKit project credentials when adding a project-credentials connection.

JSON headers for a LiveKit token-endpoint connection.

Requires Node.js 22+. Output is prose only; there is no `--json` flag.login / init / logout are the only commands that take --url. Every other repository command reads origin and project from `egma/config.yaml` and will refuse to run without it.Do not put provider secrets in CLI arguments. Prefer the canonical environment variables or --credentials-stdin (a JSON object on stdin). Arguments show up in shell history and process listings.A real phone run can incur carrier and model cost. The CLI does not prompt for that approval; the docs require a human to confirm before the coding agent starts it.egma self-host up is the only public command that expects the Egma platform workspace rather than a voice-agent repository.The GitHub repository is MIT except the `ee` directories.

Egma is an open-source voice-agent testing and monitoring platform from egma-ai, first published on GitHub in August 2026. The CLI is distributed as the egma-cli npm package and is meant to be driven by developers or coding agents from the agent repository.

pytest(1), playwright(1), locust(1), newman(1)

Source code · Homepage · Documentation