CLI Reference

Relevant source files

The following files were used as context for generating this wiki page:

• src/main.rs
• src/config.rs
• ARCHITECTURE.md
• AGENTS.md
• CONTRIBUTING.md
• packaging/homebrew/shunt.rb

The shunt Command Line Interface (CLI) serves as the primary human-facing surface for managing the Claude Code LLM gateway. It provides subcommands for running the gateway process, validating configuration files, managing authentication tokens, and performing diagnostic checks. The CLI is designed to be the entry point for both local development and hosted operations.

Sources: ARCHITECTURE.md, AGENTS.md, src/main.rs

Command Overview

The CLI is structured into several primary subcommands, each handling a specific lifecycle or administrative task. The main.rs file acts as the entry point, parsing commands and initializing the required runtime components such as the Tokio runtime and tracing subscribers.

Primary Subcommands

Command	Purpose	Description
run	Execute Gateway	Starts the local or hosted gateway process, initializing the Axum router and proxy logic.
check	Validate Config	Performs a dry-run validation of the shunt.toml or shunt.yaml configuration.
token	Token Helper	Assists in managing or generating tokens for various providers.
login	Authentication	Initiates login flows for supported providers (e.g., xAI, Cursor, ChatGPT).

Sources: AGENTS.md, src/main.rs, ARCHITECTURE.md

Execution Flow

When a user executes a shunt command, the system follows a structured initialization path. This includes parsing command-line arguments, setting up observability (tracing/OTel), and loading the configuration before dispatching to the specific subcommand logic.

The execution flow ensures that telemetry and configuration are available to all subcommands before any logic is performed.
Sources: src/main.rs, ARCHITECTURE.md, AGENTS.md

Subcommand Details

The run Command

The run command is the core operational mode. It snapshots the live configuration and starts the HTTP server. According to the architecture, it also initializes the SharedState via arc-swap to allow for hot-reloading of configuration without restarting the process.

• Initialization: Sets up the Tokio runtime.
• State: Pins a RuntimeState snapshot including config, inbound_auth, and admin_auth.
• Serving: Launches the Axum router defined in server.rs.

Sources: src/main.rs, ARCHITECTURE.md, AGENTS.md

The check Command

The check command is used for pre-flight validation. It ensures the configuration is semantically correct before deployment. It specifically checks for:

• Unknown or invalid default_provider.
• Mismatched provider kinds.
• Malformed account credentials or pooling configurations.

Sources: src/config.rs, ARCHITECTURE.md

The login and token Commands

These commands handle the interaction with upstream provider authentication systems. The login command facilitates OAuth flows for providers like ChatGPT (Codex), Cursor, and xAI. The gateway manages credential files (e.g., ~/.claude/.credentials.json) and these CLI tools are used to populate or refresh those files.

Sources: ARCHITECTURE.md, AGENTS.md

Operational Integration

The CLI is designed to be compatible with standard package managers and CI/CD environments. For example, the Homebrew formula for shunt uses the CLI's --help output as a basic installation test.

test do
  assert_match "shunt", shell_output("#{bin}/shunt --help")
end

Sources: packaging/homebrew/shunt.rb:45-47

Developer Tooling

For developers, the CLI integrates with standard Cargo commands.

Task	CLI Command
Local Development	cargo run -- run
Configuration Check	cargo run -- check
Token Management	cargo run -- token

Sources: AGENTS.md, CONTRIBUTING.md

The shunt CLI provides a robust interface for managing the gateway's lifecycle, from initial configuration validation via check to persistent operation via run. It centralizes authentication management and provides the necessary hooks for observability and hot-reloading, ensuring the gateway remains transparent and performant for Claude Code clients.