Main CLI Interface

Relevant source files

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

• lib/kamal/cli/main.rb
• lib/kamal/commander.rb
• lib/kamal/configuration.rb
• lib/kamal/cli/app.rb
• lib/kamal/cli/accessory.rb
• CLAUDE.md

The Main CLI Interface serves as the primary entry point and orchestrator for the Kamal deployment tool. It is implemented using the Thor framework, providing a structured set of commands for managing the lifecycle of web applications, including initial setup, deployment, rollbacks, and infrastructure maintenance.

At its core, the interface coordinates between high-level user intentions and the underlying technical layers: Kamal::Commander for execution orchestration, Kamal::Configuration for environment processing, and specific subcommands for specialized tasks like accessory management or image building.

Sources: lib/kamal/cli/main.rb:1-5, CLAUDE.md:38-45

Architecture and Command Hierarchy

The CLI is structured into a main class Kamal::Cli::Main which delegates specialized responsibilities to several subcommands. This "cake" architecture separates command definitions from execution logic and configuration management.

CLI Layer Structure

The diagram above illustrates the delegation flow from the executable entry point down to the specialized subcommands and the underlying logic layers.
Sources: lib/kamal/cli/main.rb:259-286, CLAUDE.md:38-45

Key Subcommands

The Main class registers several namespaces to handle specific domains of the deployment environment:

Subcommand	Class	Purpose
accessory	Kamal::Cli::Accessory	Manage databases, redis, and other backing services.
app	Kamal::Cli::App	High-level application container management (start/stop/logs).
build	Kamal::Cli::Build	Handles Docker image creation and registry delivery.
proxy	Kamal::Cli::Proxy	Manages kamal-proxy instances for request routing.
server	Kamal::Cli::Server	Bootstraps raw servers with Docker and dependencies.

Sources: lib/kamal/cli/main.rb:259-286

Core Deployment Workflows

The interface defines three primary workflows for application lifecycle management: setup, deploy, and redeploy.

The Deployment Flow

The deploy command is the central operation, involving secret validation, image delivery, and container orchestration.

This sequence shows the synchronous progression of a standard deployment, highlighting the integration of hooks and sub-invocations.
Sources: lib/kamal/cli/main.rb:21-65

Workflow Comparison

Feature	setup	deploy	redeploy
Bootstrap Servers	Yes	No	No
Boot Accessories	Yes	Optional	No
Build/Push Image	Yes	Yes	Yes
Boot Proxy	Yes	Yes	No
Prune Images	Yes	Yes	No

Sources: lib/kamal/cli/main.rb:2-101

Execution Orchestration (Kamal::Commander)

Kamal::Commander acts as the singleton backend for the CLI, handling target resolution (hosts/roles) and maintaining global state like deployment locks.

Logic and Data Flow

1. Configuration Initialization: The CLI triggers KAMAL.config, which loads deploy.yml and merges destination-specific overrides.
2. Target Resolution: Commander filters specific_roles and specific_hosts based on CLI flags (--roles, --hosts).
3. SSHKit Integration: Commander configures the global SSHKit backend with connection options defined in the configuration.
4. Locking: The modify method ensures that destructive operations are wrapped in a deployment lock to prevent concurrent modifications.

Sources: lib/kamal/commander.rb:26-50, lib/kamal/commander.rb:141-155, lib/kamal/configuration.rb:26-55

# Example of Commander resolution logic in lib/kamal/commander.rb
def specific_primary!
  @specifics = nil
  if specific_roles.present?
    self.specific_hosts = [ specific_roles.first.primary_host ]
  else
    self.specific_hosts = [ config.primary_host ]
  end
end

Sources: lib/kamal/commander.rb:58-65

Configuration and Documentation

The CLI provides built-in tools for introspecting the calculated environment and accessing documentation.

• kamal config: Renders the combined configuration (merging base and destination files) while redacting sensitive secrets for safe terminal viewing.
• kamal docs [SECTION]: Accesses the internal Validation module documentation to show available configuration keys and their purposes directly in the terminal.
• kamal doctor: Runs a series of readiness checks against servers, registries, and network ports to diagnose deployment issues.

Sources: lib/kamal/cli/main.rb:141-155, lib/kamal/cli/main.rb:157-171, lib/kamal/configuration.rb:263-271

Summary

The Main CLI Interface provides a robust, Thor-based command set that abstracts the complexity of multi-server Docker deployments. By delegating to a multi-layered architecture—from high-level subcommands down to SSHKit execution—it maintains a clear separation between user intent and infrastructure implementation. Key workflows like deploy and rollback are guarded by locking mechanisms and hook systems, ensuring reliable operations across diverse server environments.

Sources: lib/kamal/cli/main.rb:1-101, CLAUDE.md:38-45