Skip to content

Latest commit

 

History

History
159 lines (135 loc) · 10.8 KB

cli-reference.md

File metadata and controls

159 lines (135 loc) · 10.8 KB

CLI Reference

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).

Lifecycle

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)

Providers & models

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

Stats & insight

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

Gateway audit

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.

Config & keys

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.

Maintenance

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

Deploy

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.

Agents & updates

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.