Getting Started & CLI Commands
Relevant source files
The following files were used as context for generating this wiki page:
Warpgate is a smart bastion host for SSH, HTTPS, MySQL, and PostgreSQL connections. It acts as a gateway that authenticates users locally and forwards traffic to internal targets without requiring special client applications. The system includes a built-in admin web UI for session recording, live viewing, and configuration management.
Sources: README.md:1-12, README.md:73-85
Core CLI Interface
The Warpgate binary provides several subcommands for lifecycle management, ranging from initial configuration to production execution. The CLI is built using clap and supports global arguments for configuration pathing and debug verbosity.
Sources: warpgate/src/main.rs:18-30
Primary Commands
| Command | Description |
|---|---|
setup | Interactive first-time configuration and credential generation. |
unattended-setup | Non-interactive configuration using CLI arguments or environment variables. |
run | Starts the Warpgate service listeners and admin interface. |
check | Validates the current configuration file. |
test-target | Verifies connectivity to a specific defined target host. |
recover-access | Resets passwords or authentication policies for a specific user. |
client-keys | Displays Warpgate's public SSH client keys for target authorization. |
Sources: warpgate/src/main.rs:32-100
Setup and Initialization
The initialization process involves gathering environment specifics, generating a warpgate.yaml configuration, and setting up the initial administrative user.
Setup Flow
The following diagram illustrates the logic within warpgate setup:
Configuration Defaults
During setup, Warpgate establishes default paths and listeners:
- Data Path:
/var/lib/warpgate(Linux) or/usr/local/var/lib/warpgate(macOS). - Database: SQLite via
sea-orm. - Built-in Admin: Username
adminis automatically assigned thewarpgate:adminrole. - Security: Generates self-signed TLS certificates for HTTP/database protocols and host/client keys for SSH.
Sources: warpgate/src/commands/setup.rs:104-118, warpgate/src/commands/setup.rs:240-270, README.md:88-92
Running the Service
The run command initiates the asynchronous service architecture. It loads the configuration and starts protocol listeners for enabled services (SSH, HTTP, MySQL, Postgres).
Administrative Token
When running the service, users can use the --enable-admin-token flag. This allows an API token passed via the WARPGATE_ADMIN_TOKEN environment variable to automatically map to the first administrator, facilitating automated management.
Sources: warpgate/src/main.rs:77-80
Developer Workflows
For contributors building from source, the project uses a justfile to manage the complex build requirements of both the Rust backend and the Svelte frontend.
Build Commands
| Task | Command | Description |
|---|---|---|
| Install Dependencies | just npm | Installs NPM dependencies for the web UI. |
| Build Frontend | just npm run build | Compiles the Svelte application into static assets. |
| Build Backend | cargo build --release | Compiles the Rust binary. |
| Generate SDKs | just openapi-all | Re-generates TypeScript/Python SDKs from OpenAPI schemas. |
Sources: README.md:96-110, warpgate-web/package.json:7-18
Build Requirements
- Rust: System compiler and Cargo.
- NodeJS/NPM: Required for the
warpgate-webfrontend. - Just: Command runner for build automation.
Sources: README.md:96-100
Summary
Warpgate's CLI provides a comprehensive suite for bastion host management. The setup command streamlines the complex task of generating cryptographic keys and database schemas, while the run command provides a resilient service runtime. Development and automation are supported through robust OpenAPI-driven SDK generation and specialized CLI flags for headless environments.
Sources: README.md:120-125, warpgate/src/main.rs:32-85