CLI Reference¶

Argo Proxy v3 uses a subcommand-based CLI. If no subcommand is given, serve is assumed for backward compatibility.

$ argo-proxy server
argo-proxy: unknown command 'server'. Did you mean 'serve'?

Top-Level Usage¶

argo-proxy [-h] [-V] {serve,config,logs,update,models} ...

Global Options¶

serve — Start the Proxy Server¶

The default subcommand. Starts the argo-proxy server in universal mode (all 4 API formats).

argo-proxy serve [config] [options]

Backward-compatible shorthand (no subcommand):

argo-proxy config.yaml --port 8080 --verbose

Positional Arguments¶

Server Options¶

Legacy-Only Options¶

These options only apply when --legacy-argo is enabled:

Examples¶

# Start in universal mode (default)
argo-proxy serve

# Start with custom host and port
argo-proxy serve --host 127.0.0.1 --port 8080

# Start with specific config file
argo-proxy serve /path/to/config.yaml

# Show config on startup
argo-proxy serve --show --verbose

# Start in legacy ARGO gateway mode
argo-proxy serve --legacy-argo

config — Manage Configuration¶

Manage configuration files without starting the server.

argo-proxy config {edit,validate,show,migrate,init,env} [config]

Actions¶

config edit¶

Open the configuration file in the system's default editor.

argo-proxy config edit
argo-proxy config edit /path/to/config.yaml

config validate¶

Validate the configuration file and test connectivity.

argo-proxy config validate

In universal mode, validates connectivity to the native OpenAI models endpoint (GET /v1/models). In legacy mode, validates the ARGO gateway chat and embedding endpoints.

config show¶

Display the fully resolved configuration.

argo-proxy config show

Shows different fields depending on mode:

• Universal mode: argo_base_url, native_openai_base_url, native_anthropic_base_url
• Legacy mode: argo_url, argo_stream_url, argo_embedding_url

config migrate¶

Migrate configuration from v1/v2 format to v3 format.

argo-proxy config migrate
argo-proxy config migrate /path/to/config.yaml

This will:

1. Create a .bak backup of the original file
2. Set config_version: "3"
3. Infer argo_base_url from legacy individual endpoint URLs if not set
4. Remove deprecated keys (use_native_openai, use_native_anthropic, provider_tool_format)
5. Drop stale/unknown fields and produce canonical v3 output

config init¶

Create a new configuration interactively. Reuses the same wizard as first-time setup.

# Create at default location (~/.config/argoproxy/config.yaml)
argo-proxy config init

# Create at custom path
argo-proxy config init /path/to/config.yaml

# Overwrite existing config without confirmation
argo-proxy config init --force

config env¶

Show or switch the upstream ARGO API environment.

# Show current environment
argo-proxy config env

# Switch to production
argo-proxy config env prod

# Switch with explicit config path
argo-proxy config env dev -c /path/to/config.yaml

Available environments:

logs — Collect Diagnostic Logs¶

Collect diagnostic logs for analysis and debugging.

argo-proxy logs {collect} [config] [options]

Actions¶

logs collect¶

Collect diagnostic logs into a timestamped tar.gz archive.

# Collect all diagnostic logs (default)
argo-proxy logs collect

# Collect only leaked tool call logs
argo-proxy logs collect --type leaked-tool

# Collect only stream retry request dumps
argo-proxy logs collect --type stream-retry

Log types and their directories:

update — Check and Install Updates¶

Check for new versions and install updates.

argo-proxy update {check,install} [options]

Actions¶

update check¶

Check for available stable and pre-release versions on PyPI. Shows a table covering both argo-proxy and its critical dependencies (e.g., llm-rosetta).

argo-proxy update check

Example output:

Package      Installed  Stable  Pre     Status
─────────────────────────────────────────────────
argo-proxy   3.0.0      3.0.0   —       ✓ up to date
llm-rosetta  0.5.1      0.5.1   —       ✓ up to date

When updates are available, the Status column shows ⬆ update available and upgrade commands are printed below the table.

update install¶

Install the latest version.

# Install latest stable
argo-proxy update install

# Install latest pre-release
argo-proxy update install --pre

Automatically detects uv, pip, or python -m pip for installation.

models — List Available Models¶

List all available upstream models with their aliases and family classification.

argo-proxy models [config] [--json]

Options¶

Examples¶

# List models in table format
argo-proxy models

# Output as JSON
argo-proxy models --json

Example output:

Available models: 22 models, 50 aliases

  OpenAI (8 models)
    gpt4o                          argo:gpt-4o
    gpt4omini                      argo:gpt-4o-mini
    ...

  Anthropic (5 models)
    claudesonnet4                  argo:claude-4-sonnet, argo:claude-sonnet-4
    claudeopus4                    argo:claude-4-opus, argo:claude-opus-4
    ...

  Google (4 models)
    gemini25flash                  argo:gemini-2.5-flash
    ...

Environment Variables¶

The following environment variables override configuration file settings: