Every command accepts --config /path/to/config.toml. Config resolution:
--config > $EGGPOOL_CONFIG > $XDG_CONFIG_HOME/eggpool/config.toml (or
~/.config/eggpool/config.toml when unset, if present) > ./config.toml.
Command list verified against eggpool help (0.8.3).
| Command | Description |
|---|---|
eggpool serve |
Start the proxy server (daemon mode; --verbose for foreground) |
eggpool stop |
Stop the running server |
eggpool restart |
Fully restart the server (stop then start) |
eggpool rehash |
Apply supported config changes live without restart (--json for structured output) |
eggpool onboard |
Interactive onboarding wizard; a fresh database prompts for an initial administrator |
eggpool ensure-running |
Ensure server is running (no full runtime snapshot) |
eggpool croncheck |
Fast-path cron watchdog check (no server connection) |
| Command | Description |
|---|---|
eggpool connect |
Add a provider account interactively |
eggpool connect list |
List supported providers |
eggpool logout |
Remove a configured provider account |
eggpool check-config |
Validate configuration. --local also fails when an external model-info source, pricing catalog, or the update checker is enabled, and prints that those sources are off. It does not rewrite the file or block an operator-configured provider |
eggpool migrate |
Run database migrations |
eggpool models refresh |
Refresh the model catalog |
eggpool accounts list |
List configured provider accounts |
eggpool accounts status |
Show account status (provider, priority, weight, enabled) |
eggpool accounts explain |
Show per-account routing eligibility for a model |
eggpool modelinfo show |
Show enriched model metadata |
eggpool modelinfo list |
List model-info entries |
eggpool modelinfo refresh |
Trigger model-info source refresh |
eggpool modelinfo aliases |
Show model aliases |
eggpool modelinfo repair |
Repair legacy canonical model-info detail blocks |
| Command | Description |
|---|---|
eggpool status |
Concise proxy/provider health summary from the private local control socket (one row per provider; --json for structured output) |
eggpool runtime-status |
Detailed local operator diagnostics from the private control socket (--json for the full snapshot) |
eggpool stats transcoding |
Show protocol transcoding statistics |
eggpool stats repair-costs |
Dry-run/apply repair for suspicious historical request costs |
eggpool stats recompute-costs |
Recompute cost_microdollars on historical requests |
eggpool stats explain-dashboard |
Show EXPLAIN QUERY PLAN for dashboard queries |
| Command | Description |
|---|---|
eggpool audit export |
Write content-free administration and inference rows as JSON lines. --limit defaults to 500 and cannot exceed 2000. --actor must be an active administrator (default admin). A final line reports whether either section was truncated |
The same fields are available to an administrator browser session at
GET /api/admin/audit/export. See the API reference.
| Command | Description |
|---|---|
eggpool set |
Set a config value |
eggpool edit |
Edit config in $EDITOR |
eggpool getkey |
Print the server API key |
eggpool newkey |
Generate and write a new server API key (--show-old, --show-secrets) |
eggpool users bootstrap |
Create the initial local administrator (--password-stdin for unattended input) |
eggpool users add USER |
Create a member with a TTY-hidden or --password-stdin temporary password; optional --profile-id PROFILE or --no-profile; otherwise uses the configured new-member default; --actor ADMIN records the active administrator |
eggpool users defaults show |
Show the default member profile and budget-template behavior |
eggpool users defaults set PROFILE |
Select the profile for future members created without an explicit profile |
eggpool users defaults clear |
Remove the default; future unassigned members remain deny-by-default |
eggpool users show USER |
Show one user's role, state and forced-password-change status without secrets |
eggpool users list |
List local usernames, role and status |
eggpool users disable USER |
Disable a user, revoke their sessions and personal tokens, and withdraw that user's personal upstream accounts |
eggpool users enable USER |
Reactivate a user; previously revoked tokens and withdrawn personal accounts stay withdrawn |
eggpool users token USER |
Issue a personal inference, discovery, and integrations token (--label optional; --show-secret allows non-TTY output). Tool-execution scopes are not issued |
eggpool users revoke USER |
Revoke all personal API tokens for a user |
eggpool users reset-password USER |
Reset a local password and revoke that user's API tokens and browser sessions (--password-stdin supported) |
eggpool users enable-managed |
Explicitly record managed access (--actor ADMIN, default admin); works even when retired legacy settings remain |
eggpool users upstream default allow|deny |
Set the instance personal-upstream self-service default. A fresh database denies it |
eggpool users upstream grant USER allow|deny|inherit |
Set one user's self-service grant. Deny does not withdraw an account that is already bound |
eggpool users upstream add USER --provider ID --name ACCOUNT |
Bind a bundled-provider account to that user. The key comes from a TTY prompt or --secret-stdin and is written only to the config-adjacent .env |
eggpool users upstream list [USER] |
List personal bindings: user, provider, account, state, and environment-variable name. The key is not shown |
eggpool users upstream remove USER --provider ID --name ACCOUNT |
Withdraw the binding and remove the account from config.toml and .env |
eggpool users policy create ID NAME allow|deny |
Create an exact-rule model profile |
eggpool users policy rule PROFILE MODEL allow|deny |
Add or replace one exact model or model/provider rule |
eggpool users policy assign USER PROFILE |
Assign a profile to a local user |
eggpool users policy prefer PROFILE [MODEL] |
Set or clear a profile's allowed client recommendation |
eggpool users budget set USER --window day|month |
Set daily/monthly request, token, microdollar, and concurrency limits (--model-id scopes an exact model; --enforcement hard|estimated, default estimated) |
eggpool users budget remove USER --window day|month |
Remove the matching user/model budget rule |
eggpool users global-budget set --window day|month |
Set an instance-wide ceiling intersected with every per-user rule (--model-id scopes an exact model; --enforcement hard|estimated, default estimated) |
eggpool users global-budget remove --window day|month |
Remove the matching instance-wide ceiling |
eggpool init-config |
Initialize config from template |
eggpool dashboard public --on|--off |
Toggle dashboard key requirement (default public) |
Policy commands remain available as a local operator setup path alongside the
admin dashboard. They write SQLite policy state directly; model IDs are exact
and wildcards are rejected. --actor ADMIN records the active administrator
responsible for each change. Personal tokens are issued with inference,
discovery, and integrations scopes. EggPool does not issue tool-execution
scopes and does not administer or execute tools.
Local member lifecycle commands run from the machine that owns the EggPool
data directory. The first successful users add moves
admin_initialized to managed in the same SQLite transaction as the user,
optional or default initial profile, and audit records. A failed profile assignment does
not leave a user or change the access state. The default applies to future
members only; setting or clearing it never reassigns existing users. There is
no default budget template. Disabling revokes active sessions
and personal tokens; re-enabling does not restore those tokens, so issue a new
one with users token USER. The last active administrator cannot be disabled.
Budget commands are local operator controls. At least one positive limit is required; each rule is keyed by user, optional exact model, and UTC calendar window. Cost limits apply to estimated microdollars, not provider invoices. Rule changes are written to the SQLite audit table.
| Command | Description |
|---|---|
eggpool backup |
Create a timestamped backup (--output-dir override) |
eggpool recover [source] |
Restore from a backup archive (interactive picker when omitted) |
eggpool db vacuum |
Vacuum the SQLite database |
eggpool version |
Show installed version |
| Command | Description |
|---|---|
eggpool deploy systemd |
Print/install systemd unit |
eggpool deploy cron |
Install watchdog cron (non-systemd) |
eggpool deploy backup-cron |
Install daily backup cron job |
eggpool deploy logrotate |
Print/install logrotate config |
eggpool deploy all |
Print every deployment snippet in sequence |
Full deploy commands reference: deployment.md
Personal tokens are stored as digests and can authenticate inference,
/v1/models, and the integration profile; they do not grant dashboard or
administrative access. The shared [server].api_key authenticates only legacy
legacy_unmigrated installations and stops working after local identity
initialization. Browser sessions use HttpOnly cookies and protect logout and
password changes with same-origin checks plus a session-bound CSRF token.
Passwords are never accepted as command-line arguments. Local CLI access is
the recovery authority; password reset revokes API credentials and sessions.
| Command | Description |
|---|---|
eggpool configsetup |
Generate config snippets for coding agents: opencode, codex, claude-code, aider, qwen-code, kilo, continue, cline, roo-code, goose, openhands (see Agent Configuration) |
eggpool configremote <target> |
Export a secret-free epc1 remote profile for Codex/OpenCode on other machines (--format command|token|json, --base-url override) |
eggpool update [VERSION] |
Install the latest or one exact catalogued release (v prefix accepted; --check for dry-run, --from-source for local build) |
eggpool install-provenance |
Show the package manager or standalone update authority |
eggpool uninstall |
Uninstall EggPool from this machine |
For exact upgrades, supported rollback targets, standalone binaries, and ownership failures, see upgrading.md.