CLI reference

Command groups for running the proxy, editing configuration, managing keys and secrets, reading logs, and diagnosing AI routing.

Global usage

Terminal

modelmux --help
modelmux --config /path/to/config.yaml <command>
modelmux version

Use --help on any command or subcommand for the authoritative flags available in the installed version.

Server and TUI

Command	Purpose
`modelmux start`	Start the HTTP proxy server.
`modelmux tui`	Open the terminal dashboard.
`modelmux version`	Print version, commit, and build timestamp.

Configuration commands

Command	Purpose
`modelmux config init`	Create an example configuration file.
`modelmux config validate`	Validate YAML and configuration relationships.
`modelmux config validate --json`	Return machine-readable validation output.
`modelmux config validate --check-provider`	Also test provider connectivity.

Providers, models, and groups

Command	Purpose
`modelmux provider add ...`	Add a provider to configuration.
`modelmux model add ...`	Add a model to configuration.
`modelmux group add ...`	Add a model group to configuration.
`modelmux providers`	List providers; supports JSON output.
`modelmux models`	List models; supports JSON output.
`modelmux groups`	List groups; supports JSON output.

The exact add-command flags can evolve. Use modelmux provider add --help, modelmux model add --help, and modelmux group add --help.

Key commands

Command	Purpose
`modelmux key add ...`	Add a key to configuration.
`modelmux key test --id <key>`	Test a key against its provider.
`modelmux key enable --id <key>`	Enable a key in config and runtime.
`modelmux key disable --id <key>`	Disable a key in config and runtime.
`modelmux keys`	List configured keys; supports JSON output.

Secret-store commands

Command	Purpose
`modelmux secret set --ref name`	Store a value using a hidden prompt.
`modelmux secret set --ref name --value "$TOKEN"`	Store a value non-interactively.
`modelmux secret list`	List stored secret references, not plaintext values.
`modelmux secret delete --ref name`	Delete one stored reference.
`modelmux secret export --output file`	Export an encrypted backup.
`modelmux secret import --input file`	Import an encrypted backup.
`modelmux secret verify`	Check encrypted-store integrity.
`modelmux secret rotate-master-key`	Re-encrypt with a new master key.

Logs and resource lists

Terminal

modelmux logs --limit 50
modelmux logs --model-id example-chat
modelmux logs --status-code 429
modelmux logs --json --limit 100

modelmux providers --json
modelmux models --json
modelmux keys --json
modelmux groups --json

AI diagnostics

Command	Purpose
`modelmux ai classify --file request.json`	Classify a saved request.
`modelmux ai route --file request.json --json`	Preview policy routing.
`modelmux ai explain --request-id <id>`	Explain routing for a recorded request.
`modelmux ai doctor-config`	Validate AI routing configuration.