haloy

Complete reference for Haloy CLI commands.

Commands run on your local machine to manage deployments.

Commands

Most commands require a haloy config file. If you don’t specify --config <path>, haloy looks in the current directory for haloy.yaml, haloy.yml, haloy.json, or haloy.toml. See Basic Configuration for more information.

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 multiple targets
haloy deploy --target staging,production

# 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(s) (comma-separated for multiple)
  • --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(s) (comma-separated for multiple)
  • --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(s) (comma-separated for multiple)
  • --all, -a - Stop all targets
  • --remove-containers, -r - 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

exec

Execute commands inside running application containers.

# Run 'ls -la' in the first container
haloy exec -- ls -la

# Run on all containers (useful when app has multiple replicas)
haloy exec --all-containers -- whoami

# Run on a specific container by ID (supports short IDs like 'abc123')
haloy exec --container abc123 -- env

# With target selection (for multi-target configs)
haloy exec --target prod -- ls -la

# Execute on all targets
haloy exec --all -- cat /etc/hostname

# Combine target and container flags
haloy exec --target prod --all-containers -- ps aux

# Run a command with arguments
haloy exec -- cat /app/config.json

# Run a shell command (note: container must have the shell available)
haloy exec -- sh -c "echo hello && ls -la"

Syntax:

haloy exec [flags] -- <command> [args...]

The -- separator is required to distinguish between flags and the command to execute inside the container.

Options:

  • --config, -c <path> - Path to config file or directory (default: current directory)
  • --target, -t <name> - Execute on specific target(s) (comma-separated for multiple)
  • --all, -a - Execute on all targets
  • --all-containers - Execute on all containers (when app has multiple replicas)
  • --container <id> - Execute on a specific container by ID (supports short IDs)

Default Behavior: By default (no container flags), the command runs on the first container of the application The app name and server are read from the haloy configuration file (same as other commands like deploy, stop, status)

Note: This is a non-interactive exec (no TTY support) - suitable for running commands that complete and return output - Commands run with the default user configured in the container image - The -- separator is mandatory - the command will error if omitted

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(s) (comma-separated for multiple)
  • --all, -a - Rollback all targets
  • --server, -s <url> - Override server URL

Arguments:

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

Note: Rollback availability depends on image.history.strategy configuration. See Image Configuration for more information.

server setup

Provision a remote Haloy server over SSH. This requires root access to install dependencies and configure system services.

# Basic setup
haloy server setup <host>

# Setup with API domain and email
haloy server setup 192.168.1.100 --api-domain api.example.com --acme-email admin@example.com

# Setup with specific user and identity file
haloy server setup myserver.com -u ubuntu --ssh-identity ~/.ssh/id_rsa

Arguments:

  • <host> - The hostname or IP address of the server

Options:

  • --user, -u <user> - SSH username (default: root)
  • --port, -p <port> - SSH port (default: 22)
  • --api-domain <domain> - Domain for the haloyd API
  • --acme-email <email> - Email address for Let’s Encrypt
  • --ssh-identity <path> - Path to SSH private key
  • --override - Override existing Haloy data/config
  • --no-services - Don’t start HAProxy and haloyd containers
  • --no-logs - Don’t stream haloyd initialization logs

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

server version

Get the version from a haloyd server.

haloy server version

Flags:

  • --server, -s - Server URL (overrides config file)
  • --config, -c - Path to config file or directory
  • --target, -t <name> - Apply to specific target(s) (comma-separated for multiple)
  • --all, -a - Get version for all targets

version

Display the CLI version.

haloy version

Outputs only the CLI version number in plaintext (e.g., 0.1.0).

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.

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>-tApply to specific targets. Use comma-separated values for multiple targets (e.g., staging,production)
--all-aApply to all targets

Configuration File Discovery

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

  • haloy.yaml
  • haloy.yml
  • haloy.json
  • haloy.toml

You can also specify a directory:

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

Target Selection

The --target flag controls which target(s) your command applies to:

# Single target
haloy deploy --target production

# Multiple targets (comma-separated, no spaces)
haloy deploy --target staging,production

# All targets
haloy deploy --all

Important notes:

  • When using multiple targets, separate them with commas without spaces
  • If your config defines targets, you must use either --target or --all
  • Use --all or -a to target all configured environments at once
  • Multiple targets are applied sequentially in the order specified

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

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 specific environments
haloy deploy --target staging,production

# Deploy to all environments
haloy deploy --all

# Check status of all environments
haloy status --all

Exit Codes

The haloy CLI uses consistent exit codes:

  • 0 - Success
  • 1 - Any error

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