CLI Reference

CLI Reference

kinetix is both the proxy and its administration tool. Running it with no subcommand prints help; kinetix serve runs the proxy. Every other subcommand opens the SQLite control plane directly (deriving the master key from the config directory), so it works with the server stopped and needs no admin password.

Global options

Option	Description
--home <DIR>	Root holding config/, data/, state/ — overrides XDG and ignores any .env (env KINETIX_HOME). Use it for isolated/test instances.
--config <FILE>	Explicit config file path.
--bind <ADDR>	Override the bind address (e.g. 127.0.0.1:8080).
--database-url <URL>	Override the database URL (sqlite://...).
-V, --version	Print the version.

Configuration precedence is CLI flag > environment variable > config file > default.

Subcommands

serve

Run the proxy. Same startup sequence as any other deployment.

kinetix serve
kinetix serve --allow-private-upstreams --allow-insecure-tls   # local dev only

Flag	Effect
--log-json	Emit JSON logs.
--allow-private-upstreams	Permit private/internal upstream endpoints (SSRF guard bypass, NFR-3.9). Dev only.
--allow-insecure-tls	Permit plain-HTTP upstreams (NFR-3.12). Dev only.

A boolean flag can only force the value on; leaving it off does not shadow an enabling environment variable.

init

Create the XDG directories and generate + print the admin password once.

status

Print version, resolved paths, limits, and control-plane counts.

doctor

Check that the config/data/state dirs exist, the database is reachable and migrated, and whether a server is responding on the public base URL.

password

kinetix password set <PASSWORD>   # min 8 chars; invalidates all sessions
kinetix password show             # whether a password is configured

key

kinetix key create --name pi --owner me [--tag dev] [--allowed-models '*']
                   [--rpm N] [--tpm N] [--daily-budget N] [--monthly-budget N]
kinetix key list
kinetix key disable <ID> | enable <ID>
kinetix key revoke <ID>           # hard-delete the key AND its usage logs

provider

kinetix provider add --name "My Provider" --base-url https://.../v1 \
  --wire-format openai|anthropic|gemini --auth-scheme bearer|custom_header|query_param \
  [--custom-header-name X] [--custom-param-name key] [--models-path /models] \
  [--timeout-ms 120000] [--api-key sk-...] [--account-label primary]
kinetix provider list
kinetix provider remove <ID>

--api-key + --account-label create the provider's first account in one step.

model

kinetix model add --provider "My Provider" --upstream-id gpt-4o-mini \
  --display-name "GPT-4o mini"
kinetix model list
kinetix model remove <ID>

account

kinetix account add --provider "My Provider" --label primary --api-key sk-... \
  [--priority 1] [--weight 1] [--soft-quota-usd 5.0] [--quota-type daily|monthly|none]
kinetix account list
kinetix account reset <ID>        # clear cooldown/exhaustion/circuit state
kinetix account remove <ID>

route

kinetix route add --name resilient \
  --target "ProviderA/model-x" --target "ProviderB/model-y" \
  [--strategy priority|round-robin|weighted|least-used] \
  [--portability-policy reject|strip_with_warning] [--cache-affinity] \
  [--max-attempts 5]
kinetix route list
kinetix route remove <ID>

--target is repeatable and ordered (provider/upstream_id). See Routing and Fallback.

alias

kinetix alias add --alias coder --target-type model --target "Provider/model-x"
kinetix alias add --alias fast  --target-type route --target resilient
kinetix alias list
kinetix alias remove <ALIAS>      # remove takes the alias NAME, not an id

export

kinetix export run [--day YYYY-MM-DD]   # default: yesterday (UTC)
kinetix export list
kinetix export prune

Writes usage-<day>.jsonl, usage-<day>.csv, and summary-<day>.csv under $KINETIX_DATA_DIR/exports.

backup

kinetix backup run     # VACUUM INTO a consistent snapshot
kinetix backup list

uninstall

kinetix uninstall [--yes] [--remove-binary] [--keep-data] [--dry-run]

Removes the config/state directories (and the data directory unless --keep-data), optionally the binary, with a confirmation prompt unless --yes. See Configuration and the uninstall.sh script.

Examples

# A complete first-time setup in one screen
kinetix provider add --name Gemini --base-url https://generativelanguage.googleapis.com/v1beta \
  --wire-format gemini --auth-scheme custom_header --custom-header-name x-goog-api-key \
  --api-key "$GEMINI_KEY" --account-label primary
kinetix model add --provider Gemini --upstream-id gemini-2.5-flash --display-name "Gemini 2.5 Flash"
kinetix key create --name pi --owner me
kinetix serve