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 (skips protected targets)
haloy deploy --all
haloy deploy -a

# Deploy all targets including protected ones
haloy deploy --all --include-protected

# 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 (skips protected targets unless —include-protected is used)
  • --include-protected - Include protected targets when using —all
  • --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

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

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
  • --remove-volumes - Remove volumes after stopping (requires —remove-containers)
  • --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

tunnel

Create a TCP tunnel to a running container, allowing local connections to be forwarded to the container’s port. This is useful for accessing services like databases that aren’t exposed externally.

# Tunnel to a database container (uses port from haloy.yaml config)
haloy tunnel 15432 -t postgres
# Then connect: psql -h localhost -p 15432

# Override the remote port
haloy tunnel 15432 -t myapp --port 5432

# Tunnel to a specific container (for apps with replicas)
haloy tunnel 15432 -t myapp --container abc123

Syntax:

haloy tunnel <local-port> [flags]

Options:

  • --targets, -t <name> - Target to tunnel to (required for multi-target configs)
  • --port <port> - Remote port to tunnel to (default: port from config)
  • --container <id> - Specific container ID to tunnel to (useful for apps with replicas)
  • --config, -c <path> - Path to config file or directory

How It Works:

  1. Client establishes a TLS connection to the haloyd API server
  2. Sends an HTTP upgrade request to /v1/tunnel/{appName}
  3. Server validates auth, connects to the target container, and responds with 101 Switching Protocols
  4. The connection is upgraded to a raw TCP tunnel
  5. Data flows bidirectionally between the local port and the container

Requirements:

  • Requires exactly one target (use --targets flag for multi-target configs)
  • The target container must be running

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 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

server upgrade

Upgrade the haloyd daemon on a server to the latest version.

# Upgrade via API (recommended)
haloy server upgrade

# Upgrade specific target
haloy server upgrade --target production

# Show manual upgrade instructions
haloy server upgrade --manual

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 - Upgrade all targets
  • --manual - Display manual SSH upgrade instructions instead of performing API upgrade

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, get the API token
sudo haloyd config get 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