Skip to content

Commit a94988a

Browse files
SimonSchubertSimonSchubert
committed
Add commands
1 parent 60d9db2 commit a94988a

5 files changed

Lines changed: 443 additions & 63 deletions

File tree

‎assets/commands/egma.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# TAGLINE
2+
3+
CLI for simulation testing and monitoring of voice agents
4+
5+
# TLDR
6+
7+
**Sign in** (opens a browser device-approval page)
8+
9+
```egma login```
10+
11+
Sign in to a **self-hosted** instance
12+
13+
```egma login --url [http://localhost:3101]```
14+
15+
**Initialize** this repository against the logged-in project
16+
17+
```egma init```
18+
19+
**Pull** remote agents, suites, and tests (keeps local drafts)
20+
21+
```egma pull```
22+
23+
**List personas**, then **create a suite** directory
24+
25+
```egma persona list```
26+
27+
```egma suite create [receptionist-core] --name ["Receptionist core"]```
28+
29+
**Push** the repository index and tests (validates first)
30+
31+
```egma push```
32+
33+
**Start a run** of one suite against an agent connection
34+
35+
```egma run create [receptionist-core] --agent [agt_...] --connection [con_...] --name ["Release check"]```
36+
37+
**Cancel** a run
38+
39+
```egma run cancel [run_...]```
40+
41+
Start the **self-hosted** platform from an Egma checkout
42+
43+
```egma self-host up```
44+
45+
# SYNOPSIS
46+
47+
**egma** _command_ [_options_]
48+
49+
# PARAMETERS
50+
51+
**login**
52+
> Browser device login. **--url** _URL_ selects Cloud or a self-hosted origin. Only **login**, **logout**, and **init** accept **--url**.
53+
54+
**logout**
55+
> Revoke the saved device-login key for one origin. Does not revoke **EGMA_API_KEY** or change `egma/` in the repo.
56+
57+
**init**
58+
> 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.
59+
60+
**pull**
61+
> Refresh the remote index, suites, and tests. Local unpushed test drafts are kept.
62+
63+
**push**
64+
> Validate, then upload the complete authored state. There is no separate public `validate` command.
65+
66+
**agent register**
67+
> Register an Egma agent identity. **--platform** `retell`|`livekit`, optional **--name** (default: repository directory name).
68+
69+
**agent connection options**
70+
> Print the platform's connection catalog (and, for Retell, discover provider agents). Needs the provider key on first discovery.
71+
72+
**agent connection add**
73+
> Add a simulation connection to an existing agent. Access and modality are explicit flags; provider secrets come from canonical environment variables or **--credentials-stdin**.
74+
75+
**agent monitoring setup**|**stop**
76+
> Start or stop production call pulls for an agent (**--agent**, **--platform**).
77+
78+
**persona list**
79+
> List personas available to the project.
80+
81+
**suite create** _DIR_ **--name** _NAME_
82+
> Create a suite. Tests are Markdown files under `egma/tests/`_DIR_`/`.
83+
84+
**suite delete** _DIR_
85+
> Delete the remote suite, then the local directory.
86+
87+
**test delete** _PATH_
88+
> Delete a remote test, then the local Markdown file.
89+
90+
**run create** _DIR_ **--agent** _ID_ **--connection** _ID_
91+
> Push, then start a run of every active test in that suite directory. Prints the run ID and results URL and returns.
92+
93+
**run cancel** _RUN_ID_
94+
> Cancel an in-progress run.
95+
96+
**project api-key create** **--name** _NAME_
97+
> Create a project-scoped API key. The secret is printed once and not stored.
98+
99+
**self-host up**
100+
> Start local Egma services. Run this from an Egma **platform** checkout, not from a voice-agent repository.
101+
102+
# DESCRIPTION
103+
104+
**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.
105+
106+
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`).
107+
108+
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.
109+
110+
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**.
111+
112+
# CONFIGURATION
113+
114+
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.
115+
116+
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.
117+
118+
Provider keys used only during setup:
119+
120+
**EGMA_RETELL_API_KEY**
121+
> Retell API key for first-time discovery and the first Retell connection.
122+
123+
**EGMA_LIVEKIT_API_KEY** / **EGMA_LIVEKIT_API_SECRET**
124+
> LiveKit project credentials when adding a project-credentials connection.
125+
126+
**EGMA_LIVEKIT_TOKEN_ENDPOINT_HEADERS**
127+
> JSON headers for a LiveKit token-endpoint connection.
128+
129+
On the platform checkout, copy **`.env.example`** to **`.env`** (mode `600`) before **egma self-host up**. That command also writes internal secrets to **`.egma-platform/platform.env`**; keep that file with database backups.
130+
131+
# CAVEATS
132+
133+
Requires **Node.js 22+**. Output is prose only; there is no `--json` flag.
134+
135+
**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.
136+
137+
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.
138+
139+
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.
140+
141+
**egma self-host up** is the only public command that expects the Egma platform workspace rather than a voice-agent repository.
142+
143+
The GitHub repository is MIT except the **`ee`** directories.
144+
145+
# HISTORY
146+
147+
**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.
148+
149+
# SEE ALSO
150+
151+
[pytest](/man/pytest)(1), [playwright](/man/playwright)(1), [locust](/man/locust)(1), [newman](/man/newman)(1)
152+
153+
# RESOURCES
154+
155+
```[Source code](https://github.com/egma-ai/egma)```
156+
157+
```[Homepage](https://app.egma.ai)```
158+
159+
```[Documentation](https://docs.egma.ai/skills-cli-sdks/skills-and-cli)```
160+
161+
<!-- verified: 2026-09-10 -->

‎assets/commands/filament.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# TAGLINE
2+
3+
CLI for pluggable data replication with checkpoints and integrity checks
4+
5+
# TLDR
6+
7+
Print the **CLI version**
8+
9+
```filament version```
10+
11+
Open the **interactive menu**
12+
13+
```filament -i```
14+
15+
Create a **Postgres source** whose DSN comes from the environment
16+
17+
```filament source create [production] --source-connector postgres --source-connection-method url --source-dsn-env [POSTGRES_DSN]```
18+
19+
Create a **stdout sink** for local debugging
20+
21+
```filament sink create [debug] --sink-connector stdout```
22+
23+
**Discover** resources on a saved source
24+
25+
```filament source discover [production]```
26+
27+
Save a **pipeline** from two connections
28+
29+
```filament pipeline create [users-copy] --source [production] --sink [warehouse] --resources [users,audit] --sync-mode full --write-mode replace```
30+
31+
**Run** a saved pipeline
32+
33+
```filament run [users-copy]```
34+
35+
One-shot **inline copy** to stdout (no saved pipeline)
36+
37+
```filament run --source-connector postgres --source-connection-method url --source-dsn-env [POSTGRES_DSN] --sink-connector stdout```
38+
39+
Keep the local **API and web UI** running
40+
41+
```filament up```
42+
43+
Stop a **detached** local runtime
44+
45+
```filament down```
46+
47+
# SYNOPSIS
48+
49+
**filament** [_--context_ _NAME_] [_--config_ _PATH_] [_-i_] [_COMMAND_]
50+
51+
# PARAMETERS
52+
53+
**-i**, **--interactive**
54+
> Open the terminal menu (or a wizard when combined with a command such as **source create**).
55+
56+
**--context** _NAME_
57+
> Run this invocation against context _NAME_ instead of the current one.
58+
59+
**--config** _PATH_
60+
> Local YAML document to apply (local contexts only).
61+
62+
**--layout** _boxed_|_plain_
63+
> Table drawing style. Also read from **FILAMENT_LAYOUT**.
64+
65+
**source** **create**|**edit**|**list**|**discover**|**delete**
66+
> Manage sources. **ls** is an alias of **list**. Connector fields become `--source-*` flags.
67+
68+
**sink** **create**|**edit**|**list**|**delete**
69+
> Manage sinks. Connector fields become `--sink-*` flags.
70+
71+
**pipeline** **create**|**edit**|**list**|**delete**
72+
> Manage saved pipelines. **create** needs **--source** and **--sink** naming saved connections.
73+
74+
**run** [_PIPELINE_]
75+
> Run a saved pipeline, or an inline transfer with **--source-connector** and **--sink-connector**. **run list** [_PIPELINE_] shows history.
76+
77+
**up**
78+
> Serve the local runtime, API, and web UI (default `127.0.0.1:8080`). **-d**, **--detach** backgrounds it.
79+
80+
**down**
81+
> Stop the detached process started by **up --detach**.
82+
83+
**status**
84+
> Show the selected context and whether its runtime is reachable.
85+
86+
**context** **add**|**list**|**current**|**use**|**rename**|**delete**
87+
> Manage local vs remote targets. **ctx** is an alias.
88+
89+
**auth** **login**|**status**|**logout**
90+
> Service-account login for a remote Filament server.
91+
92+
**config** **path**|**validate**|**edit**
93+
> Inspect, check, or open the local YAML document in `$VISUAL`/`$EDITOR`.
94+
95+
# DESCRIPTION
96+
97+
**filament** is the command-line client for Filament, a Go data-replication engine. It copies data from sources to sinks using full loads, incremental replication, or change data capture. Batches are verified at the sink handoff; resumable runs pick up from the last durable checkpoint instead of starting over.
98+
99+
The same binary talks to a **local** runtime (file-backed SQLite and an in-process event bus; no Postgres or NATS required) or a **remote** Filament server selected by a context. Most management commands work against both.
100+
101+
A **connection** stores connector settings (Postgres, MySQL, S3, ClickHouse, Iceberg, stdout, and several SaaS sources). A **pipeline** routes a source to a sink and names the resources, sync mode, and write mode. **filament run** executes that route and streams progress until it finishes.
102+
103+
`filament up` keeps the embedded API and web UI available on a stable address. Ordinary local commands start the runtime for one operation and stop it.
104+
105+
Filament is **pre-1.0**: public APIs, including connector interfaces, may still change.
106+
107+
# CONFIGURATION
108+
109+
The built-in local context reads **`~/.config/filament/filament.yaml`** (or `$XDG_CONFIG_HOME/filament/filament.yaml`). **filament config path** prints the active file. The YAML is declarative **input** applied when it changes; it is not an inventory. Removing an entry from YAML does not delete the object from local SQLite state.
110+
111+
```yaml
112+
version: 1
113+
114+
sources:
115+
production:
116+
type: postgres
117+
config:
118+
connection_method: url
119+
dsn: env:POSTGRES_DSN
120+
121+
sinks:
122+
warehouse:
123+
type: stdout
124+
125+
pipelines:
126+
users-copy:
127+
source:
128+
ref: production
129+
sink:
130+
ref: warehouse
131+
resources:
132+
- users
133+
sync_mode: full
134+
write_mode: replace
135+
```
136+
137+
Secret fields accept a value or an environment reference (`--source-dsn-env POSTGRES_DSN`, or `--source-dsn '$POSTGRES_DSN'`). Quote `$NAME` forms so the shell does not expand them. On a remote context, secret references belong to the deployment's secret provider, not the CLI process environment.
138+
139+
**NO_COLOR** disables terminal colors. Contexts and credentials are stored with owner-only permissions.
140+
141+
# CAVEATS
142+
143+
The command name **filament** is also used by unrelated projects (Google's Filament rendering engine and Laravel Filament). This page documents the Galaxy **filament** replication CLI (`galaxy-io/filament`).
144+
145+
Inline **filament run --source-connector ...** transfers are **full reads only**. They do not keep run history or checkpoints. Remote contexts run saved pipelines without those inline overrides.
146+
147+
**filament up** only accepts a local context.
148+
149+
Do not put secrets on the process command line; they can appear in shell history and process listings. Prefer `*-env` flags or quoted environment references.
150+
151+
# HISTORY
152+
153+
**Filament** is an Apache-2.0 Go project from **galaxy-io**, first published on GitHub in **June 2026**. It ships as a standalone CLI, an embeddable Go module, and container images (server, control plane, worker, standalone) for larger deployments.
154+
155+
# SEE ALSO
156+
157+
[rsync](/man/rsync)(1), [pg_dump](/man/pg_dump)(1), [mysqldump](/man/mysqldump)(1), [debezium](/man/debezium)(1)
158+
159+
# RESOURCES
160+
161+
```[Source code](https://github.com/galaxy-io/filament)```
162+
163+
```[Homepage](https://filament.getgalaxy.io)```
164+
165+
```[Documentation](https://filament.getgalaxy.io/pages/guides/usage/cli)```
166+
167+
<!-- verified: 2026-09-10 -->

‎assets/commands/index.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2093,6 +2093,7 @@ efivar.md
20932093
eg.md
20942094
eget.md
20952095
eglinfo.md
2096+
egma.md
20962097
ego.md
20972098
egrep.md
20982099
eim.md
@@ -2327,6 +2328,7 @@ fido2-token.md
23272328
fierce.md
23282329
figlet.md
23292330
figlist.md
2331+
filament.md
23302332
file-hierarchy.md
23312333
file-rename.md
23322334
file-roller.md

0 commit comments

Comments
 (0)