effgen · 1.0.0

29 commands that answer to a pipe as readily as to a terminal

The effgen command line runs an agent, races models, serves an API, watches the traffic going through it and reports what it all cost. Every command has a live view on a terminal and a single structured document on a pipe, and the completion scripts are generated from the parser rather than maintained by hand, so they cannot go stale.

All 29 commandsReference documentation
29
Commands
38
Sub-commands
4
Named themes
3
Completion shells
effgen top

What is running, what it costs, and which panel measured it

Five panels, refreshing in place. Each one names the window and the process it measures, and figures from different sources are never combined: Activity reads the local run history across every process, Traffic and Per-model read one server’s counters since it started, Spend reads the local cost ledger, and GPU reads the physical devices.

effgen top68/68Replay finished.
$ effgen top --once
effGen 1.0.0 — wangserv — 2026-08-20T16:56:29Z
server http://127.0.0.1:8124 reachable

                    Activity — completed runs, local run history (all processes)                    
┏━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Time     ┃ Status ┃ Model                     ┃ Duration ┃ Cost      ┃ Task                      ┃
┡━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 12:56:28 │ error  │ no-such-model             │ 217ms    │ —         │ user: hi                  │
│ 12:56:28 │ ok     │ gemini-3.1-flash-lite     │ 8.91s    │ $0.000008 │ user: What is 9 squared?  │
│ 12:56:19 │ ok     │ gemini-3.1-flash-lite     │ 2.36s    │ $0.000052 │ user: Give me one fact    │
│          │        │                           │          │           │ about Kyoto.              │
│ 12:56:17 │ ok     │ gemini-3.1-flash-lite     │ 713ms    │ $0.000024 │ user: Name one property   │
│          │        │                           │          │           │ of a B-tree.              │
│ 12:56:16 │ ok     │ gemini-3.1-flash-lite     │ 4.15s    │ $0.000010 │ user: What is 25 * 17?    │
│ 12:56:07 │ ok     │ gemini:gemini-3.1-flash-l │ 4.87s    │ $0.000955 │ what does textkit export? │
│          │        │ ite                       │          │           │                           │
│ 12:55:58 │ ok     │ openai:gpt-5-nano         │ 3.49s    │ $0.000177 │ What is 2 ** 40? Use the  │
│          │        │                           │          │           │ calculator tool.          │
│ 12:55:51 │ ok     │ openai:gpt-5-nano         │ 2.86s    │ $0.000129 │ What is the boiling point │
│          │        │                           │          │           │ of water in Fahrenheit?   │
│ 12:55:46 │ ok     │ gemini:gemini-3.1-flash-l │ 11.59s   │ $0.000104 │ Summarise what a B-tree   │
│          │        │ ite                       │          │           │ is, in one sentence.      │
│ 12:55:30 │ ok     │ gemini:gemini-3.1-flash-l │ 2.21s    │ $0.000077 │ What is 18723 * 4409? Use │
│          │        │ ite                       │          │           │ the calculator tool.      │
└──────────┴────────┴───────────────────────────┴──────────┴───────────┴───────────────────────────┘

       Traffic — this server process since start       
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Metric                      ┃ Value                 ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
│ Generation requests         │ 5                     │
│ Errors                      │ 1 (20.0%)             │
│ Latency p50 / p95 / p99     │ 1.75s / 8.75s / 9.75s │
│ Tokens                      │ 136                   │
│ HTTP responses (all routes) │ 200×5, 404×1          │
└─────────────────────────────┴───────────────────────┘

                     Per-model — this server process since start                      
┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━┓
┃ Model                 ┃ Provider ┃ Calls ┃ Errors ┃ Error rate ┃ p95   ┃ Cost      ┃
┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━┩
│ gemini-3.1-flash-lite │ gemini   │ 4     │ 0      │ 0.0%       │ 9.00s │ $0.000094 │
│ no-such-model         │ gemini   │ 1     │ 1      │ 100.0%     │ 242ms │ —         │
└───────────────────────┴──────────┴───────┴────────┴────────────┴───────┴───────────┘

 Spend — local cost ledger, last 24 hours 
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Metric       ┃ Value                   ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Total        │ $0.001536               │
│ Requests     │ 10                      │
│ Daily budget │ $1.00 (0.1% used)       │
│ Burn rate    │ $0.001536/h (last hour) │
└──────────────┴─────────────────────────┘

        GPU — physical devices, all processes         
┏━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━┓
┃ GPU ┃ Name       ┃ Memory           ┃ Mem % ┃ Util ┃
┡━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━┩
│ 0   │ NVIDIA A40 │ 44.33 / 44.42 GB │ 100%  │ 96%  │
│ 1   │ NVIDIA A40 │ 0.26 / 44.42 GB  │ 1%    │ 0%   │
│ 2   │ NVIDIA A40 │ 44.38 / 44.42 GB │ 100%  │ 100% │
│ 3   │ NVIDIA A40 │ 44.38 / 44.42 GB │ 100%  │ 100% │
│ 4   │ NVIDIA A40 │ 44.38 / 44.42 GB │ 100%  │ 100% │
│ 5   │ NVIDIA A40 │ 44.38 / 44.42 GB │ 100%  │ 100% │
│ 6   │ NVIDIA A40 │ 43.93 / 44.42 GB │ 99%   │ 100% │
│ 7   │ NVIDIA A40 │ 43.93 / 44.42 GB │ 99%   │ 100% │
└─────┴────────────┴──────────────────┴───────┴──────┘
Recorded against a real effgen serve on this machine with five requests through it, one of which named a model that does not exist — which is the error row in Activity and the 100% row in Per-model. The GPU panel is this host’s eight cards, most of them busy with other work.$ effgen top --once

It is useful without a server

Activity, Spend and GPU need no server, so the view still says something on a host running only local agents. The server-backed panels then read as unavailable and name the URL they tried, rather than showing zeros that look like quiet. effgen monitor is an alias for the same command.

Piped output, --json, --once, --no-animation and NO_COLOR all print a single snapshot and exit instead of taking over the screen.

docs/cli/top.md

The same snapshot, structured

effgen top --json emits one document carrying the same five panels, so the view is scriptable without parsing a table.

  • .activity
  • .traffic
  • .by_model
  • .spend
  • .gpu
bash
effgen top --json | jq '.spend | {total_cost_usd, requests, daily_budget_usd}'
output
{
  "total_cost_usd": 0.00211725,
  "requests": 13,
  "daily_budget_usd": 1
}
The command surface

All 29 commands, by what they are for

Every summary below is the command’s own, from effgen --help in effGen 1.0.0. 38 sub-commands sit under nine of them.

Give an agent something to do

6

One task, a conversation, a coding session, or a file of tasks.

effgen run

Run an agent with a task

effgen chat

Interactive chat mode

effgen code

Coding agent: writes code, runs it, and fixes what fails

effgen debug

Run an agent in interactive debug mode

effgen batch

Run batch queries from a file

effgen examples

Run example scripts

list · run

Pick work back up

4

A run and a conversation are both durable, and both are addressable by id afterwards — from the command line, from a script and from the server.

effgen workflow

Run a DAG-based workflow

run · validate

effgen resume

Resume an interrupted agent run from a saved checkpoint snapshot (distinct from a conversation session — see `--session-id`)

effgen sessions

Browse and manage saved conversations

list · show · browse · delete · export · cleanup

effgen runs

Browse agent run history

list · show · cleanup

See what is available

4

The model catalog, the tool registry, the presets and the prompt library.

effgen models

Model management

list · browse · info · load · unload · status · refresh

effgen tools

Tool management

list · info · test

effgen presets

List available agent presets

effgen prompts

Prompt library management

list · show · eval · playground · render · run

Measure before you choose

4

A scored suite, an ad-hoc race, a graded evaluation, or a server under load. Each writes a shareable HTML report.

effgen eval

Evaluate an agent against a test suite

effgen compare

Compare multiple models on a test suite

effgen battle

Race several models on one prompt, side by side

effgen loadtest

Run a load test against a local mock or a live provider

Serve it and watch it

4

An OpenAI-compatible server, and a live terminal view of what is going through it.

effgen serve

Start API server

effgen top

Live terminal view of runs, traffic, spend and GPU

effgen monitor

Alias for `effgen top`

effgen health

Check effGen infrastructure health (contacts external services)

Know what it cost

2

The local spend ledger, budgets, and a saved result rendered later.

effgen cost

View cost spend and manage budgets

today · week · by-provider · set-budget · clear-budget

effgen report

Render a saved run/compare/eval/cost/loadtest JSON result as an HTML report

Set a machine up

5

Scaffold a project, check the environment, and read the configuration effGen resolved.

effgen quickstart

Guided first run: pick a model, run an agent, then write and run code

effgen tutorial

Alias of quickstart — the same guided first run

effgen config

Configuration management

show · validate · init · set

effgen doctor

Check provider keys, the system, and what effgen code needs

effgen create-plugin

Generate a plugin project scaffold

The flags that come before the command

FlagTypeDescription
--version—show program's version number and exit
-v, --verbose—Verbose output (show DEBUG/INFO logs)
-q, --quiet—Quiet output (errors only)
--log-file LOG_FILE—Log file path
--no-animation—Disable live spinners/progress animation (also via NO_COLOR or EFFGEN_NO_ANIM=1)
--theme {default,high-contrast,monochrome,light}—Color theme for terminal output (also via EFFGEN_THEME). high-contrast targets low-vision readers; monochrome keeps structure without hue; NO_COLOR still turns color off entirely
--completion {bash,zsh,fish}—Print shell completion script and exit

effgen --help · effGen 1.0.0

Long option names mean the same thing everywhere. Two short flags do not: -c is --concurrency on batch and loadtest but --config on run, and -p is a port on serve, monitor and top but --print on code. Both collisions are frozen and pinned by a test, so a third meaning cannot be added quietly — and in a script the long spelling is the portable one.

Appearance

4 named themes, and NO_COLOR still wins

A theme is a table of semantic roles — heading, success, error, warning, cost, tool, model, metric, muted — mapped onto colours, so one palette drives every table, spinner, panel and status line. Select one with --theme or EFFGEN_THEME. When NO_COLOR is set the console renders the structure with no colour at all, whichever theme is chosen.

These four frames are the same command run under each theme, drawn from the colour codes it emitted rather than from a description of them. They are text, not screenshots — selectable, searchable, and legible at any zoom.

--theme default

The unchanged look: cyan headings and table headers, magenta for a tool or a title, green for a cost and a success, dim for anything secondary.

--theme default
$ effgen --theme default models info gemini:gemini-3.1-flash-lite Model: gemini:gemini-3.1-flash-lite┌───────────────────────────┬───────────────────────┐│ Provider                  │ gemini                ││ Display name              │ gemini-3.1-flash-lite ││ Family                    │ flash-lite            ││ Context window            │ 1,000,000             ││ Max output                │ 32,768                ││ Price ($/1M in / out)     │ $0.25/$1.5            ││ Tool calling              │ yes                   ││ Coding                    │ suitable              ││ Vision                    │ yes                   ││ Audio                     │ yes                   ││ Free tier                 │ yes                   ││ Rate limits (rpm/tpm/rpd) │ 15 / 250000 / 500     ││ Deprecated                │ no                    ││ Price source              │ bundled-catalog       ││ Verified on               │ 2026-08-13            ││ Auth ready                │ no (set key)          │└───────────────────────────┴───────────────────────┘ Use: effgen run --provider gemini -m gemini-3.1-flash-lite "..."
--theme high-contrast

Aimed at low-vision readers. Every role moves to its bright pair and picks up bold, and what the default theme dims becomes plain white instead.

--theme high-contrast
$ effgen --theme high-contrast models info gemini:gemini-3.1-flash-lite Model: gemini:gemini-3.1-flash-lite┌───────────────────────────┬───────────────────────┐│ Provider                  │ gemini                ││ Display name              │ gemini-3.1-flash-lite ││ Family                    │ flash-lite            ││ Context window            │ 1,000,000             ││ Max output                │ 32,768                ││ Price ($/1M in / out)     │ $0.25/$1.5            ││ Tool calling              │ yes                   ││ Coding                    │ suitable              ││ Vision                    │ yes                   ││ Audio                     │ yes                   ││ Free tier                 │ yes                   ││ Rate limits (rpm/tpm/rpd) │ 15 / 250000 / 500     ││ Deprecated                │ no                    ││ Price source              │ bundled-catalog       ││ Verified on               │ 2026-08-13            ││ Auth ready                │ no (set key)          │└───────────────────────────┴───────────────────────┘ Use: effgen run --provider gemini -m gemini-3.1-flash-lite "..."
--theme monochrome

Keeps the structure without hue. Headings underline, an error reverses, a tool and a model italicise — so the same distinctions survive on a terminal with no colour and in a log file.

--theme monochrome
$ effgen --theme monochrome models info gemini:gemini-3.1-flash-lite Model: gemini:gemini-3.1-flash-lite┌───────────────────────────┬───────────────────────┐│ Provider                  │ gemini                ││ Display name              │ gemini-3.1-flash-lite ││ Family                    │ flash-lite            ││ Context window            │ 1,000,000             ││ Max output                │ 32,768                ││ Price ($/1M in / out)     │ $0.25/$1.5            ││ Tool calling              │ yes                   ││ Coding                    │ suitable              ││ Vision                    │ yes                   ││ Audio                     │ yes                   ││ Free tier                 │ yes                   ││ Rate limits (rpm/tpm/rpd) │ 15 / 250000 / 500     ││ Deprecated                │ no                    ││ Price source              │ bundled-catalog       ││ Verified on               │ 2026-08-13            ││ Auth ready                │ no (set key)          │└───────────────────────────┴───────────────────────┘ Use: effgen run --provider gemini -m gemini-3.1-flash-lite "..."
--theme light

For a light terminal, where cyan and yellow wash out. Blue replaces cyan, a darker orange replaces yellow, and the muted role becomes a real grey rather than dimmed white.

--theme light
$ effgen --theme light models info gemini:gemini-3.1-flash-lite Model: gemini:gemini-3.1-flash-lite┌───────────────────────────┬───────────────────────┐│ Provider                  │ gemini                ││ Display name              │ gemini-3.1-flash-lite ││ Family                    │ flash-lite            ││ Context window            │ 1,000,000             ││ Max output                │ 32,768                ││ Price ($/1M in / out)     │ $0.25/$1.5            ││ Tool calling              │ yes                   ││ Coding                    │ suitable              ││ Vision                    │ yes                   ││ Audio                     │ yes                   ││ Free tier                 │ yes                   ││ Rate limits (rpm/tpm/rpd) │ 15 / 250000 / 500     ││ Deprecated                │ no                    ││ Price source              │ bundled-catalog       ││ Verified on               │ 2026-08-13            ││ Auth ready                │ no (set key)          │└───────────────────────────┴───────────────────────┘ Use: effgen run --provider gemini -m gemini-3.1-flash-lite "..."
The --json contract

One document on stdout, on a pipe and on a terminal

--json is not a rendering mode that a terminal can override. The command emits the same single document either way, the live view is skipped, and everything a human reads goes to stderr — so | jq works and a redirect captures the document alone.

CommandTypeDescription
effgen code -p "what does this package export?" --plan --json -m gemini:gemini-3.1-flash-lite—The answer, the files written, every proposed diff, and the full action log.
effgen battle "Explain a B-tree in two sentences." -m openai:gpt-5-nano,gemini:gemini-3.1-flash-lite --json—Every contender's full answer, its cost and latency, the tally and the verdict.
effgen top --json—One snapshot: activity, traffic, per-model, spend and GPU.
effgen runs list --json—The run history, newest first, with the ids `runs show` takes.

Each of these was run for this page and its stdout parsed as one document.

bash
# stdout is the document; the progress display goes to stderr
effgen run "Say the word ok and nothing else." \
  -m gemini:gemini-3.1-flash-lite --json > run.json

# so a redirect captures the document, and nothing else
head -c 60 run.json
jq -r ".success, .output" run.json
what those two commands printed
{
  "task": "Say the word ok and nothing else.",
  "model": 
true
Ok

The same split is why a command that fails still answers in JSON: the document carries "success": false and a typed error rather than leaving a caller to parse a message meant for a person.

effgen battle

Several models, one prompt, side by side

Where compare scores a registered suite against expected answers, battle answers “which of these should I use for this?” in one shot. On a terminal each model gets a column that fills in as its answer streams; the verdict panel reports what was measured — fastest, cheapest, longest — and needs no judge.

effgen battle
$ effgen battle "Explain a B-tree in two sentences." -m openai:gpt-5-nano,gemini:gemini-3.1-flash-lite --no-animation# Model Battle **Prompt:** Explain a B-tree in two sentences. | Model | Result | TTFT | Latency | Tokens (in/out) | Cost ||-------|--------|------|---------|-----------------|------|| openai:gpt-5-nano | answered | 12.13s | 12.89s | 25/1103 | $0.000442 || gemini:gemini-3.1-flash-lite | answered | 2.51s | 3.77s | 21/63 | $0.000100 | ## Verdict - **Fastest**: gemini:gemini-3.1-flash-lite — answered in 3.77s- **Cheapest**: gemini:gemini-3.1-flash-lite — $0.000100 for this run- **Longest**: openai:gpt-5-nano — 348 characters ## openai:gpt-5-nano A B-tree is a self-balancing, multi-way search tree in which each node can contain multiple keys and have many children, keeping the tree shallow for efficient disk access. All leaves are at the same depth, and internal nodes guide searches by key ranges, allowing insert, delete, and search operations to run in logarithmic time on large datasets. ## gemini:gemini-3.1-flash-lite A B-tree is a self-balancing search tree data structure that maintains sorted data and allows searches, sequential access, insertions, and deletions in logarithmic time. It is optimized for systems that read and write large blocks of data by allowing nodes to contain more than two children, which minimizes disk I/O operations. _2/2 answered in 16.40s; total cost $0.000542._

A judge is optional, and is reported apart

--judge MODEL asks a separate model to pick the best answer. That pick is reported apart from the measurements and names the judge, because a quality opinion and a measured latency are not the same kind of claim. On compare, naming no judge means every model grades its own answers — which the tables say, and the JSON records as self_judged.

Loading is timed apart from generating

A local model’s start-up shows as loading rather than being counted as slow generation. A model that fails is reported as failed, does not end the race and cannot win the verdict; the command exits 1 only when no model answered at all.

Which model can do the work

effgen models info carries the catalog’s answer for one id — its context window, its published price, whether it calls tools, and a Coding verdict for effgen code.

effgen models info
$ effgen models info openai:gpt-5-mini Model: openai:gpt-5-mini┌───────────────────────────┬─────────────────┐│ Provider                  │ openai          ││ Display name              │ gpt-5-mini      ││ Family                    │ chat            ││ Context window            │ 1,047,576       ││ Max output                │ 32,768          ││ Price ($/1M in / out)     │ $0.25/$2        ││ Tool calling              │ yes             ││ Coding                    │ suitable        ││ Vision                    │ yes             ││ Audio                     │ no              ││ Free tier                 │ no              ││ Rate limits (rpm/tpm/rpd) │ — / — / —       ││ Deprecated                │ no              ││ Price source              │ bundled-catalog ││ Verified on               │ 2026-06-17      ││ Auth ready                │ yes             │└───────────────────────────┴─────────────────┘ Use: effgen run --provider openai -m gpt-5-mini "..."
Reports, run cards and history

Something to send someone

compare, battle, eval, cost and loadtest each take --report out.html, and run --card writes one run as a single file. Every style, script and chart is inline, so the file opens from disk or an email attachment with no network access — a claim that was checked for this page: the report written here reaches no external host at all.

bash
# one run as a shareable card, alongside the usual output
effgen run "What is 18723 * 4409? Use the calculator tool." \
  -m gemini:gemini-3.1-flash-lite -t calculator --card run-card.html

# a result captured now, rendered later, with no model call
effgen run "Name one property of a B-tree." \
  -m gemini:gemini-3.1-flash-lite -o saved.json
effgen report saved.json -o for-team.html
what those commands printed
✓ Done in 0.8s · 1 tool · 188 tokens · $0.000077
1 tool step — run with --trace to see the timeline
✓ Run card written to run-card.html

HTML report written to for-team.html (run)

A card carries the task, the model that answered it, a succeeded or failed badge, the full answer, every tool step with its input and its result or typed failure, the sources and citations, and the run’s tokens, cost and latency. A model with no published price reads unpriced and an absent metric reads —; neither is rendered as $0. A run already in history exports as a summary card, and says on its face that it is one.

A report is never written blank

Handed a document that carries none of the fields a report needs, effgen report lists the kinds it recognises, exits 2 and writes no file.

effgen report
$ effgen report notaresult.json✗ Could not tell which report this result is. Expected the JSON emitted by `effgen run --json`, `effgen compare --json`, `effgen eval --json`, `effgen cost--json`, or `effgen loadtest`. Pass --kind to say explicitly (run, comparison, eval, cost, loadtest, battle).

What it cost, today

effgen cost today
$ effgen cost today                              effGen Cost Summary — Last 24 hours                               ┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓┃ Provider ┃ Model                 ┃ Requests ┃ Prompt Tokens ┃ Completion Tokens ┃ Cost (USD) ┃┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩│ gemini   │ gemini-3.1-flash-lite │        8 │         3,906 │               169 │  $0.001230 ││ openai   │ gpt-5-nano            │        2 │           439 │               709 │  $0.000306 │├──────────┼───────────────────────┼──────────┼───────────────┼───────────────────┼────────────┤│          │                       │          │               │                   │  $0.001536 │└──────────┴───────────────────────┴──────────┴───────────────┴───────────────────┴────────────┘ Total: 10 requests  $0.001536 USDDaily budget: ░░░░░░░░░░░░░░░░░░░░ $0.0015 / $1.0000 (0%)

Runs are durable and addressable

Every run is recorded with an id, whether it came from the command line, a script or the server. runs show opens one; the run below is the deliberate failure from the effgen top recording above, and its error names the fix rather than only the status code.

effgen runs list
$ effgen runs list --limit 6┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━┳━━━━━━━━┓┃ Run          ┃ When             ┃ Model            ┃ Task            ┃      Cost ┃ Time ┃ Status ┃┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━╇━━━━━━━━┩│ 7bd4e604266d │ 2026-08-20 12:56 │ no-such-model    │ user: hi        │         — │ 0.2s │ error  ││ 1d13a0467f23 │ 2026-08-20 12:56 │ gemini-3.1-flash │ user: What is 9 │ $0.000008 │ 8.9s │ ok     ││              │                  │ -lite            │ squared?        │           │      │        ││ c724d0f7889e │ 2026-08-20 12:56 │ gemini-3.1-flash │ user: Give me   │ $0.000052 │ 2.4s │ ok     ││              │                  │ -lite            │ one fact about  │           │      │        ││              │                  │                  │ Kyoto.          │           │      │        ││ bfb86bca5539 │ 2026-08-20 12:56 │ gemini-3.1-flash │ user: Name one  │ $0.000024 │ 0.7s │ ok     ││              │                  │ -lite            │ property of a   │           │      │        ││              │                  │                  │ B-tree.         │           │      │        ││ f9ed5104a9f8 │ 2026-08-20 12:56 │ gemini-3.1-flash │ user: What is   │ $0.000010 │ 4.1s │ ok     ││              │                  │ -lite            │ 25 * 17?        │           │      │        ││ 0ceb32763836 │ 2026-08-20 12:56 │ gemini:gemini-3. │ what does       │   $0.0010 │ 4.9s │ ok     ││              │                  │ 1-flash…         │ textkit export? │           │      │        │└──────────────┴──────────────────┴──────────────────┴─────────────────┴───────────┴──────┴────────┘                          Stored in: /data/wang/gks/effgen-demo/home/runs                           Open one with: effgen runs show <run-id>
effgen runs show
$ effgen runs show 7bd4e604266dRun:      7bd4e604266dWhen:     2026-08-20T12:56:28-04:00Status:   errorModel:    no-such-model (gemini)Agent:    api:gemini:no-such-modelTokens:   0 in / 0 outCost:     —Duration: 0.22s Task:user: hi Error:Generation failed: 404 NOT_FOUND. {'error': {'code': 404, 'message': 'models/no-such-model is not found for API version v1beta, or is not supported for generateContent. Call ModelService.ListModels to see the list of available models and their supported metho… (516 characters). Model id not found — run `effgen models list` to see ids, `effgen models refresh` to update the catalog, and verify the id/provider prefix.

So are conversations

effgen sessions lists, shows, browses, exports and cleans up saved conversations. It is one store: effgen chat --session-id, effgen code --session-id and the server all read and write the same sessions, so a conversation started in a coding session can be continued in chat.

effgen sessions list
$ effgen sessions list┏━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓┃ # ┃ Session      ┃ Messages ┃ Model                        ┃    Cost ┃ Updated          ┃┡━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩│ 1 │ textkit-tour │        2 │ gemini:gemini-3.1-flash-lite │ $0.0010 │ 2026-08-20 12:56 │└───┴──────────────┴──────────┴──────────────────────────────┴─────────┴──────────────────┘                    Stored in: /data/wang/gks/effgen-demo/home/sessions                    Read one:  effgen sessions show <id>Continue:  effgen chat --session-id <id>

effgen chat carries its own 13 slash commands, a smaller set than a coding session’s 26 because a chat writes no files.

effgen chat
$ effgen chat -m gemini:gemini-3.1-flash-lite effGen v1.0.0 · chatModel: gemini-3.1-flash-liteType your message and press Enter.  End a line with \ for multi-line input.Slash commands (type / for the menu): /help  /model  /tools  /status  /cost  /trace  /reset  /save  /session  /load  /doctor  /exitgemini-3.1-flash-lite › /help                                 Chat commands                                  ┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓┃ Command  ┃ Does                                                              ┃┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩│ /help    │ Show this help (or type just / for the menu)                      ││ /model   │ Hot-swap the active model:  /model gpt-5-nano                     ││ /tools   │ List tools, or toggle one:  /tools calculator                     ││ /status  │ Show the session state: model, persona, tools, running totals     ││ /cost    │ Session token + cost total                                        ││ /reset   │ Clear the conversation memory                                     ││ /save    │ Save this chat to a file:  /save   (see /session to resume)       ││ /session │ Show or name the resumable session id (used by `effgen sessions`) ││ /load    │ Load a saved conversation:  /load                                 ││ /trace   │ Show the last turn's reasoning/tool steps                         ││ /doctor  │ Run a quick environment check                                     ││ /clear   │ Clear the screen                                                  ││ /exit    │ Leave chat (also: /quit, exit, quit)                              │└──────────┴───────────────────────────────────────────────────────────────────┘gemini-3.1-flash-lite › /exitGoodbye!
The first five minutes

Scaffold a project, then check the machine

effgen quickstart --init DIR writes a config, an environment template, a runnable example and a .gitignore, sets a daily spend cap when none is configured, and prints the next three commands. It prompts for nothing and calls no model.

effgen quickstart --init23/23Replay finished.
$ effgen quickstart --init .

effGen project
Directory: /data/wang/gks/effgen-demo/newproject

  wrote    effgen.yaml   model, prompt and per-run caps
  wrote    .env.example  key names, no values
  wrote    example.py    a runnable agent script
  wrote    .gitignore    keeps .env out of git

Model:      cerebras:gpt-oss-120b
            cerebras key detected
            change it on the 'model:' line of effgen.yaml

Spend cap:  $1.00 a day across all runs (already configured)
            'effgen cost set-budget N' changes it
            'effgen cost clear-budget' removes it

Next three commands
  1. cp .env.example .env  # then paste one key into it
  2. effgen doctor  # confirm effGen sees it
  3. effgen run "What is 25 * 17?" -c effgen.yaml

💡 Tip: effgen code --plan proposes the change and its diffs without writing anything.
Four files, the cap it found already configured, and the model it picked because a key for that provider was present on the machine.$ effgen quickstart --init .

effgen doctor is the second of those three commands. It reports which providers have a key and which environment variable each one reads, the system it found, and the three things effgen code needs — the workspace it would use, the sandbox backend and what that backend actually enforces, and whether git is present. Anything not ready comes with the fix.

effgen doctor
$ effgen doctor              effgen doctor — Provider Status              ┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━┓┃ Provider          ┃ Key     ┃ Env Var          ┃ Models ┃┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━┩│ anthropic         │ missing │ —                │     17 ││ cerebras          │ present │ CEREBRAS_API_KEY │      2 ││ fireworks         │ missing │ —                │     16 ││ gemini            │ missing │ —                │      8 ││ groq              │ missing │ —                │     15 ││ hf                │ missing │ —                │    124 ││ openai            │ missing │ —                │     30 ││ openai_compatible │ missing │ —                │      0 ││ replicate         │ missing │ —                │     37 ││ together          │ missing │ —                │    168 │└───────────────────┴─────────┴──────────────────┴────────┘ System┌───────────────────────────┬─────────────────────┐│ Physical GPUs (NVML)      │ 8                   ││ Driver CUDA               │ 13.3                ││ torch CUDA build          │ 13.0                ││ torch.cuda.is_available() │ True                ││ torch                     │ 2.11.0+cu130        ││ vLLM                      │ importable (0.26.0) │└───────────────────────────┴─────────────────────┘ Coding (effgen code)┏━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓┃ Check     ┃ Status        ┃ Detail                                                   ┃┡━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩│ workspace │ ready         │ /data/wang/gks/effgen-demo (from current directory)      ││ sandbox   │ limited       │ subprocess — network isolated, writes confined to the    ││           │               │ workspace                                                ││ git       │ no repository │ git version 2.34.1; /data/wang/gks/effgen-demo is not    ││           │               │ inside a repository                                      │└───────────┴───────────────┴──────────────────────────────────────────────────────────┘  sandbox: Install Docker to confine reads as well; the subprocess sandbox is used untilthen.  git: Run effgen code from a repository (or git init the workspace) for branch/status context.  Try it: effgen code "write fib.py and run it" Missing keys — set in ~/.effgen/.env or export:  export ANTHROPIC_API_KEY=<your-key>  export FIREWORKS_API_KEY=<your-key>  export GOOGLE_API_KEY=<your-key>  export GROQ_API_KEY=<your-key>  export HF_TOKEN or HUGGINGFACE_API_KEY=<your-key>  export OPENAI_API_KEY=<your-key>  export EFFGEN_BASE_URL or OPENAI_BASE_URL or OPENAI_API_BASE=<your-key>  export REPLICATE_API_TOKEN=<your-key>  export TOGETHER_API_KEY=<your-key> 💡 Tip: set EFFGEN_TIPS=0 to silence these tips.

Recorded with no provider keys in the environment, which is what a first run looks like. It names the variables, never a value.

Shell completion

Completion that cannot go stale

The scripts for bash, zsh, fish are generated by introspecting the live parser and the registries, not maintained by hand — so the command list, the --preset choices and the --tools names complete to what this installation actually has.

bash
# Bash — add to ~/.bashrc
eval "$(effgen --completion bash)"
complete -p effgen

# Zsh — add to ~/.zshrc
eval "$(effgen --completion zsh)"

# Fish
effgen --completion fish | source
what complete -p printed after sourcing it
complete -F _effgen_completion effgen

The generated script carries all 29 commands, all 9 presets and all 66 tool names. Install a plugin that registers a tool and the next shell completes it, because the list is read rather than written down.

effgen --completion bash
$ effgen --completion bash _effgen_completion() {    local cur prev commands presets tools    COMPREPLY=()    cur="${COMP_WORDS[COMP_CWORD]}"    prev="${COMP_WORDS[COMP_CWORD-1]}"     commands="batch battle chat code compare config cost create-plugin debug doctor eval examples health loadtest models monitor presets prompts quickstart report resume run runs serve sessions tools top tutorial workflow"    presets="coding general math media minimal multimodal notify rag research"    tools="agentic_search anthropic_bash anthropic_computer anthropic_text_editor arxiv audio_transcribe bash calculator code_execution code_executor crypto_price currency_converter dataframe datetime discord_webhook docker docx email_draft email_imap email_smtp excel file_operations geocode git github google_search hackernews http image_caption image_info json_tool language_detect maps multimodal_describe news notification ocr openai_code_interpreter openai_file_search openai_web_search pdf plot pubmed python_repl qr_generate qr_read reddit retrieval rss_feed semantic_scholar slack_draft slack_webhook stackoverflow stats stock_price system_info text_processing translate url_context url_fetch weather web_search wikipedia wolfram_alpha youtube_metadata youtube_transcript"     case "${prev}" in        effgen|effgen-agent)            COMPREPLY=( $(compgen -W "${commands}" -- "${cur}") )            return 0            ;;        --preset)            COMPREPLY=( $(compgen -W "${presets}" -- "${cur}") )            return 0            ;;        --tools|-t)            COMPREPLY=( $(compgen -W "${tools}" -- "${cur}") )            return 0            ;;        --mode)            COMPREPLY=( $(compgen -W "auto single sub_agents" -- "${cur}") )            return 0            ;;        run|chat)            COMPREPLY=( $(compgen -W "--model --provider --tools --preset --verbose --explain --stream --config --system-prompt --temperature --max-iterations --mode --output --session-id" -- "${cur}") )            return 0            ;;        config)            COMPREPLY=( $(compgen -W "init set show validate" -- "${cur}") )            return 0            ;;        cost)            COMPREPLY=( $(compgen -W "by-provider clear-budget set-budget today week" -- "${cur}") )            return 0            ;;        examples)            COMPREPLY=( $(compgen -W "list run" -- "${cur}") )            return 0            ;;        models)            COMPREPLY=( $(compgen -W "browse info list load refresh status unload" -- "${cur}") )            return 0            ;;        prompts)            COMPREPLY=( $(compgen -W "eval list playground render run show" -- "${cur}") )            return 0            ;;        runs)            COMPREPLY=( $(compgen -W "cleanup list show" -- "${cur}") )            return 0            ;;        sessions)            COMPREPLY=( $(compgen -W "browse cleanup delete export list show" -- "${cur}") )            return 0            ;;        tools)            COMPREPLY=( $(compgen -W "info list test" -- "${cur}") )            return 0            ;;        workflow)            COMPREPLY=( $(compgen -W "run validate" -- "${cur}") )            return 0            ;;    esac     if [[ "${cur}" == -* ]]; then        COMPREPLY=( $(compgen -W "--help --version --verbose --quiet --log-file" -- "${cur}") )    fi}complete -F _effgen_completion effgencomplete -F _effgen_completion effgen-agent

The reference for the command line

Per-command flags and exit codes, the short-flag table, compare and its scoring modes, the report formats, and what each top panel measures.

docs/dx/cli.md