CLI Command Reference

Relevant source files

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

• internal/cmd/deploy.go
• internal/cmd/rollout_deploy.go
• internal/cmd/run.go
• internal/cmd/list.go
• internal/cmd/domains.go
• internal/cmd/cache_stats.go
• internal/server/commands.go
• CLAUDE.md

The kamal-proxy CLI provides a suite of commands to manage a high-performance reverse proxy. It operates using a layered architecture where the CLI acts as an RPC client communicating with a long-running proxy server over a Unix domain socket. This reference covers the primary commands used for starting the server, deploying services, and monitoring system state.

Sources: CLAUDE.md:104-108, internal/server/commands.go:138-144

Architecture Overview

The CLI is built using the Cobra library and follows a client-server model. Most commands do not perform logic themselves; instead, they parse flags, validate arguments, and then initiate an RPC call to the kamal-proxy service registered on the Unix socket.

Communication Flow

The following diagram illustrates how a CLI command (e.g., deploy) interacts with the background proxy server.

Core Commands

run

Starts the proxy server. This is the only command that does not require an existing Unix socket, as it creates the socket and begins listening for both traffic (HTTP/HTTPS) and RPC commands.

• Logic: Initializes the router, restores saved state, configures ACME for TLS, and starts the RPC listener.
• Key Flags:
  • --http-port: Port for HTTP traffic (default 80).
  • --https-port: Port for HTTPS traffic (default 443).
  • --acme-email: Required for automatic TLS.
  • --data-dir: Storage for state and certificates.
  • --docker-socket: Enables "scale-to-zero" features.

Sources: internal/cmd/run.go:28-66, internal/cmd/run.go:106-121

deploy

Deploys or updates a service configuration. It supports sophisticated traffic shaping, health checks, and security settings.

• Logic: Parses complex targets (including weights), validates path-based rules, and sends a DeployArgs struct to the server.
• Weights: Targets can be specified as host:port;weight=n to distribute traffic proportionally.
• Header Rules: Allows adding, setting, or removing headers for both requests and responses.

Configuration Summary

Category	Flag Examples	Description
Targets	--target, --read-target	Primary and read-only upstream hosts.
Routing	--host, --path-prefix	SNI and path-based routing rules.
TLS	--tls, --tls-on-demand-url	TLS enablement and dynamic issuance.
Security	--basic-auth, --allow-ip	Access control and authentication.
Resilience	--health-check-path, --deploy-timeout	Health monitoring and rollout safety.

Sources: internal/cmd/deploy.go:34-150, internal/server/commands.go:23-30

rollout

Manages canary deployments and gradual traffic shifting for a service.

• Subcommands:
  • deploy: Sets the target hosts for the rollout group.
  • set: Configures the traffic split percentage and optional allowlists.
  • stop: Aborts the rollout and removes the rollout targets.

Sources: internal/cmd/rollout_deploy.go:16-25, internal/server/commands.go:189-201

Management and Inspection

list (ls)

Retrieves a list of all active services and their current states from the server.

domains

Manages dynamic TLS domains when ACME is enabled.

• domains list: Displays domains, their certification status, and quarantine info.
• domains stats: Provides counters for dynamic domains, queue lengths, and managed certificates.
• domains refresh: Forces an immediate re-poll of all dynamic domain sources.

Sources: internal/cmd/domains.go:20-27, internal/cmd/domains.go:104-118

cache stats

Reports the performance and health of the response cache.

• Functionality: Displays store type (memory, file, or Redis), entry counts, and eviction statistics (fresh vs. stale).
• Flag: --count forces a walk of the keyspace in shared stores (e.g., Redis) to provide accurate sizing.

Sources: internal/cmd/cache_stats.go:25-31, internal/cmd/cache_stats.go:50-70

Command Implementation Details

The CLI uses specific data structures defined in the server package to ensure type safety during RPC communication.

DeployArgs Structure

type DeployArgs struct {
	Service           string
	TargetURLs        []string
	ReaderURLs        []string
	DeploymentOptions DeploymentOptions
	ServiceOptions    ServiceOptions
	TargetOptions     TargetOptions
}

Sources: internal/server/commands.go:23-30

RPC Method Mapping

The CLI commands map to the following methods on the CommandHandler in the server:

CLI Command	RPC Method	Argument Type
deploy	kamal-proxy.Deploy	DeployArgs
list	kamal-proxy.List	bool
pause	kamal-proxy.Pause	PauseArgs
cache purge	kamal-proxy.CachePurge	CachePurgeArgs
domains refresh	kamal-proxy.DomainsRefresh	bool

Sources: internal/server/commands.go:142-230

Summary

The kamal-proxy CLI is a lightweight interface for the proxy server. By offloading heavy logic—such as ACME certificate management, health checking, and traffic buffering—to the background process, the CLI remains responsive. Users interact with services primarily through the deploy and rollout commands, while list, domains, and cache stats provide critical observability into the system's operational state.