Commands Reference

Complete reference for Haloy CLI commands.

haloy Commands

Commands run on your local machine to manage deployments.

deploy

Deploy your application to configured servers.

# Deploy with default config
haloy deploy

# Specify config file
haloy deploy --config path/to/config.yaml
haloy deploy -c path/to/config.yaml

# Deploy to specific target
haloy deploy --target production
haloy deploy -t staging

# Deploy to all targets
haloy deploy --all
haloy deploy -a

# Deploy without showing logs
haloy deploy --no-logs

Options:

  • --config, -c <path> - Path to config file or directory (default: current directory)
  • --target, -t <name> - Deploy to specific target
  • --all, -a - Deploy to all targets
  • --no-logs - Skip deployment logs (faster)
  • --server, -s <url> - Override server URL from config

status

Check the status of your deployed applications.

# Check status with default config
haloy status

# Specify config file
haloy status --config path/to/config.yaml

# Check specific target
haloy status --target production
haloy status -t staging

# Check all targets
haloy status --all

Options:

  • --config, -c <path> - Path to config file
  • --target, -t <name> - Status for specific target
  • --all, -a - Status for all targets
  • --server, -s <url> - Override server URL

stop

Stop running application containers.

# Stop application
haloy stop

# Specify config file
haloy stop --config path/to/config.yaml

# Stop specific target
haloy stop --target production

# Stop all targets
haloy stop --all

# Remove containers after stopping
haloy stop --remove-containers

Options:

  • --config, -c <path> - Path to config file
  • --target, -t <name> - Stop specific target
  • --all, -a - Stop all targets
  • --remove-containers - Remove containers after stopping
  • --server, -s <url> - Override server URL

logs

View logs from your deployed application.

# View logs
haloy logs

# Specify config file
haloy logs --config path/to/config.yaml

# Logs from specific target
haloy logs --target staging

Options:

  • --config, -c <path> - Path to config file
  • --target, -t <name> - Logs from specific target
  • --server, -s <url> - Override server URL

validate-config

Validate your configuration file.

# Validate config
haloy validate-config

# Specify config file
haloy validate-config --config path/to/config.yaml

# Show resolved configuration with secrets (use with caution)
haloy validate-config --show-resolved-config

# Both options combined
haloy validate-config --config path/to/config.yaml --show-resolved-config

Options:

  • --config, -c <path> - Path to config file
  • --show-resolved-config - Display resolved config with secrets (displays secrets in plain text!)

Warning: --show-resolved-config displays all secrets in plain text. Only use in secure environments.

rollback-targets

List available rollback targets.

# List rollback targets
haloy rollback-targets

# Specify config file
haloy rollback-targets --config path/to/config.yaml

# Targets for specific deployment
haloy rollback-targets --target production

Options:

  • --config, -c <path> - Path to config file
  • --target, -t <name> - Rollback targets for specific target
  • --server, -s <url> - Override server URL

Note: Rollback availability depends on image.history.strategy configuration.

rollback

Rollback to a specific deployment.

# Rollback using deployment ID
haloy rollback <deployment-id>

# Example
haloy rollback dep_abc123xyz

# Specify config file
haloy rollback --config path/to/config.yaml <deployment-id>

# Rollback specific target
haloy rollback --target production <deployment-id>

Options:

  • --config, -c <path> - Path to config file
  • --target, -t <name> - Rollback specific target
  • --server, -s <url> - Override server URL

Arguments:

  • <deployment-id> - The deployment ID to rollback to (from rollback-targets)

server add

Add a server to your local configuration.

# Add server
haloy server add <server-domain> <token>

# Example
haloy server add haloy.example.com abc123token456

# Force overwrite if exists
haloy server add haloy.example.com abc123token456 --force

Arguments:

  • <server-domain> - Server domain (e.g., haloy.example.com)
  • <token> - API token from the server

Options:

  • --force - Overwrite existing server configuration

server list

List all configured servers.

haloy server list

server delete

Remove a server from your local configuration.

# Remove server
haloy server delete <server-domain>

# Example
haloy server delete staging.haloy.com

Arguments:

  • <server-domain> - Server domain to remove

version

Display version information for the CLI and connected servers.

haloy version

This shows:

  • Local CLI version
  • Connected server versions (from configured servers)
  • Build information

completion

Generate shell completion scripts.

# Bash
haloy completion bash

# Zsh
haloy completion zsh

# Fish
haloy completion fish

# PowerShell
haloy completion powershell

See Shell Completion for setup instructions.

haloyadm Commands

Commands run on the server to manage the Haloy daemon and services.

init

Initialize haloyd and HAProxy (first-time setup).

# Basic initialization
sudo haloyadm init

# Initialize with API domain and SSL

sudo haloyadm init --api-domain haloy.example.com --acme-email you@example.com

# Initialize for non-root installation

haloyadm init --local-install

Options:

  • --api-domain <domain> - Domain for Haloy API with automatic SSL
  • --acme-email <email> - Email for Let’s Encrypt certificates
  • --local-install - Install in user directory (non-root)

start

Start haloyd and HAProxy services.

# Start services
sudo haloyadm start

# Start with local development image
sudo haloyadm start --dev

# Start with debug logging
sudo haloyadm start --debug

# Combine options
sudo haloyadm start --dev --debug

Options:

  • --dev - Use local haloyd image for development
  • --debug - Enable debug mode with verbose logging

stop

Stop haloyd and HAProxy services.

sudo haloyadm stop

restart

Restart haloyd and HAProxy services.

sudo haloyadm restart

Options:

  • --dev - Use local haloyd image
  • --debug - Enable debug mode

api token

Generate a new API token.

sudo haloyadm api token

Returns a token that can be used with haloy server add on local machines.

api domain

Set or update the API domain and SSL configuration.

# Set API domain with automatic SSL
sudo haloyadm api domain <domain> <email>

# Example
sudo haloyadm api domain haloy.example.com admin@example.com

Arguments:

  • <domain> - Domain for the Haloy API
  • <email> - Email address for Let’s Encrypt certificates

Common Flags

These flags are available across multiple commands:

FlagShortDescription
--config <path>-cPath to config file or directory
--server <url>-sHaloy server URL (overrides config)
--target <name>-tTarget specific deployment
--all-aApply to all targets

Configuration File Discovery

When --config is not specified, Haloy looks for config files in the current directory:

  1. haloy.yaml
  2. haloy.yml
  3. haloy.json
  4. haloy.toml

You can also specify a directory:

haloy deploy --config /path/to/config/directory

Examples

Complete Deployment Workflow

# 1. Validate configuration
haloy validate-config

# 2. Deploy to staging first
haloy deploy --target staging

# 3. Check staging status
haloy status --target staging

# 4. View staging logs
haloy logs --target staging

# 5. If good, deploy to production
haloy deploy --target production

# 6. Monitor production
haloy status --target production
haloy logs --target production

Emergency Rollback

# 1. List available rollback targets
haloy rollback-targets --target production

# 2. Rollback to previous deployment
haloy rollback --target production dep_abc123xyz

# 3. Verify rollback succeeded
haloy status --target production

Multi-Server Setup

# On each server, generate token
sudo haloyadm api token

# On local machine, add all servers
haloy server add prod.haloy.com <prod-token>
haloy server add staging.haloy.com <staging-token>
haloy server add dev.haloy.com <dev-token>

# List all servers
haloy server list

# Deploy to all environments
haloy deploy --all

# Check status of all environments
haloy status --all

Exit Codes

All commands follow standard exit code conventions:

  • 0 - Success
  • 1 - General error
  • 2 - Usage error (invalid flags, arguments)

Use in scripts:

#!/bin/bash
if haloy deploy --target production; then
  echo "Deployment successful"
  # Send success notification
else
  echo "Deployment failed"
  # Send failure alert
  exit 1
fi

Next Steps