CLI Tools

Relevant source files

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

• crates/cli/src/main.rs
• crates/cli/Cargo.toml
• Cargo.toml
• AGENTS.md
• IMPLEMENTATION_PLAN.md
• README.md
• crates/error/src/codes.rs

The Horizon CLI is a centralized command-line interface designed to manage the Horizon Configuration Management Database (CMDB) system. It serves as the primary entry point for administrative tasks, including starting the API server, managing database migrations, and validating environment configurations.

The tool is built using the Rust clap framework, providing a structured and type-safe way to interact with the system's backend infrastructure. It integrates directly with the project's migration engine and logging systems to ensure consistent operation across development and production environments.
Sources: crates/cli/src/main.rs:1-15, crates/cli/Cargo.toml:16-20, README.md:120-130

Command Architecture

The CLI follows a subcommand-based architecture. The root command horizon accepts global flags for logging and executes specific operations through subcommands.

The diagram above illustrates the primary command hierarchy and the high-level logic flow for server and migration tasks.
Sources: crates/cli/src/main.rs:75-103

Core Subcommands

Command	Description	Key Arguments
serve	Starts the Axum API server. Automatically runs pending migrations on startup.	--host, --port, --tls
migrate	Manages PostgreSQL schema migrations using the Sea-ORM migrator.	--dry-run, --rollback, --create
validate	Checks if required environment variables (e.g., HORIZON_DATABASE_URL) are present.	N/A
completions	Generates shell completion scripts for Bash, Zsh, Fish, etc.	shell (enum)

Sources: crates/cli/src/main.rs:88-120

Configuration and Environment

The CLI utilizes a hierarchical configuration approach, primarily relying on environment variables prefixed with HORIZON_ for database connectivity and server settings.

Database Configuration

The DatabaseConfig struct aggregates connection details used by both the serve and migrate commands.

pub struct DatabaseConfig {
    pub host:      String,
    pub port:      u16,
    pub database:  String,
    pub username:  String,
    pub password:  String,
    pub ssl_mode:  String,
    pub pool_size: u32,
}

Sources: crates/cli/src/main.rs:20-33

The application builds a standard PostgreSQL connection string from these components to initialize the Sea-ORM connection.
Sources: crates/cli/src/main.rs:59-66

Global Options

All CLI commands support the following global configuration flags:

• --log-level (-L): Sets the tracing level (debug, info, warn, error). Defaults to info.
• --log-format: Sets the output style (json, pretty, compact). Defaults to pretty.

Sources: crates/cli/src/main.rs:79-85

Database Migration Logic

The migrate command provides an interface to the migration crate, allowing developers to apply or revert schema changes.

This sequence shows the interaction between the CLI and the database during a rollback operation.
Sources: crates/cli/src/main.rs:188-233

Migration Operations

• Up (Default): Runs all pending migrations to bring the schema to the latest version. This is also invoked automatically by the serve command.
• Rollback: Executes Migrator::down to revert the single most recent migration.
• Dry Run: Queries the database for pending migrations and logs their names without executing them.
  Sources: crates/cli/src/main.rs:205-231

Error Handling and Validation

The CLI utilizes the error crate's AppError and Result types for consistent error reporting.

Validation Routine

The validate command checks for the presence of critical environment variables required for operation:

• HORIZON_DATABASE_HOST
• HORIZON_DATABASE_PORT
• HORIZON_DATABASE_NAME
• HORIZON_DATABASE_USER
• HORIZON_DATABASE_PASSWORD

If any variables are missing, the CLI returns a Validation error variant defined in the error crate.
Sources: crates/cli/src/main.rs:253-280, crates/error/src/codes.rs:136-150

Implementation Details

The CLI is a workspace member located at crates/cli. Its dependencies include:

• clap: Command line argument parsing.
• tokio: Async runtime for database interactions.
• migration: Internal crate for Sea-ORM migrations.
• logging: Internal crate for structured tracing.
• error: Internal crate for standardized error codes.

Sources: crates/cli/Cargo.toml:22-38, Cargo.toml:5-15

Build Commands

For developers, the CLI can be managed using standard cargo commands:

# Build the CLI tool
cargo build -p cli

# Run the CLI with arguments
cargo run -p cli -- serve --port 3000

# Run CLI unit tests
cargo test -p cli

Sources: AGENTS.md:25-50

The Horizon CLI provides a robust management layer for the CMDB, ensuring that database states and server configurations are handled consistently through a type-safe interface. By centralizing migrations and server startup into a single binary, it simplifies the deployment and maintenance of the Horizon infrastructure.