Skip to content

Commands Reference

This page provides a complete reference for all Go Overlay CLI commands. Commands are organized by category for easy navigation.

Management Commands

Commands for controlling and managing services.

restart

Restart one or more services managed by the supervisor.

Syntax:

go-overlay restart <service-name> [service-name...]

Description:

The restart command stops and then starts the specified service(s). This is useful when you need to reload service configuration or recover from a failed state. The command will:

  1. Send a stop signal to the service
  2. Wait for the service to terminate (respecting timeout settings)
  3. Start the service again

Arguments:

  • <service-name>: Name of the service to restart (as defined in your configuration file)
  • You can specify multiple service names separated by spaces

Examples:

Restart a single service:

go-overlay restart nginx

Restart multiple services:

go-overlay restart nginx mariadb redis

Expected Output:

Restarting service: nginx
Service nginx restarted successfully

Service Dependencies

When restarting a service that other services depend on, those dependent services may also be affected. Consider the dependency chain before restarting critical services.

Information Commands

Commands for querying service status and information.

list

List all services managed by the supervisor.

Syntax:

go-overlay list

Description:

The list command displays all services defined in your configuration file, along with their current status. This provides a quick overview of your entire service stack.

Examples:

go-overlay list

Expected Output:

Services:
  - nginx (RUNNING)
  - mariadb (RUNNING)
  - redis (RUNNING)
  - worker (STOPPED)
  - api (FAILED)

The output shows each service name followed by its current state in parentheses.

Possible States:

  • PENDING: Service is waiting to start
  • STARTING: Service is in the process of starting
  • RUNNING: Service is running normally
  • STOPPING: Service is in the process of stopping
  • STOPPED: Service has stopped
  • FAILED: Service has failed and is not running

status

Get detailed status information for one or more services.

Syntax:

go-overlay status [service-name...]

Description:

The status command provides detailed information about the specified service(s), including their current state, process ID (if running), and other relevant details. If no service name is provided, it shows status for all services.

Arguments:

  • [service-name...]: Optional. Name(s) of specific service(s) to check. If omitted, shows status for all services.

Examples:

Check status of a specific service:

go-overlay status nginx

Check status of multiple services:

go-overlay status nginx mariadb

Check status of all services:

go-overlay status

Expected Output:

Service: nginx
  Status: RUNNING
  PID: 1234
  Uptime: 2h 15m
  Command: /usr/sbin/nginx -g "daemon off;"

Service: mariadb
  Status: RUNNING
  PID: 1235
  Uptime: 2h 15m
  Command: /usr/bin/mysqld

Daemon Commands

Commands for running the supervisor daemon.

daemon

Start the supervisor in daemon mode to manage services.

Syntax:

go-overlay daemon [flags]

Description:

The daemon command starts Go Overlay in daemon mode, which is the main process that manages and monitors all configured services. This is typically the command you use as the entrypoint in a Docker container or as a system service.

When started, the daemon will:

  1. Load the configuration file
  2. Validate service definitions
  3. Start services according to their dependencies
  4. Monitor service health
  5. Handle graceful shutdown on termination signals

Flags:

  • --config <path>: Path to configuration file (default: /services.toml)
  • --log-level <level>: Set logging level (debug, info, warn, error)

Examples:

Start daemon with default configuration:

go-overlay daemon

Start daemon with custom configuration:

go-overlay daemon --config /app/config/services.toml

Start daemon with debug logging:

go-overlay daemon --log-level debug

Expected Output:

[INFO] Starting Go Overlay daemon
[INFO] Loading configuration from /services.toml
[INFO] Starting service: redis
[INFO] Starting service: mariadb
[INFO] Starting service: nginx
[INFO] All services started successfully
[INFO] Daemon running, press Ctrl+C to stop

Running as Entrypoint

In Docker containers, the daemon command is typically used as the ENTRYPOINT or CMD instruction.

Installation Commands

Commands for installing the Go Overlay binary.

install

Install the Go Overlay binary to the system.

Syntax:

go-overlay install [flags]

Description:

The install command copies the Go Overlay binary to a system location (typically /usr/local/bin/) and makes it executable. This allows you to run Go Overlay commands from anywhere in your system without specifying the full path.

Flags:

  • --path <path>: Custom installation path (default: /go-overlay)
  • --force: Overwrite existing installation

Examples:

Install to default location:

go-overlay install

Install to custom location:

go-overlay install --path /opt/bin/go-overlay

Force reinstall:

go-overlay install --force

Expected Output:

Installing Go Overlay to /go-overlay
Installation successful
You can now run 'go-overlay' from anywhere

Permissions

You may need to run this command with sudo or as root to install to system directories: 

sudo go-overlay install

Command Categories Summary

Category Commands Purpose
Management restart Control and manage running services
Information list, status Query service status and information
Daemon daemon Run the supervisor daemon process
Installation install Install the binary to the system

Common Usage Patterns

Starting the Supervisor

# Start daemon with default config
go-overlay daemon

# Start with custom config
go-overlay daemon --config /path/to/services.toml

Monitoring Services

# List all services
go-overlay list

# Check detailed status
go-overlay status

# Check specific service
go-overlay status nginx

Managing Services

# Restart a service
go-overlay restart nginx

# Restart multiple services
go-overlay restart nginx mariadb redis

Exit Codes

All CLI commands return standard exit codes:

  • 0: Success
  • 1: General error
  • 2: Command usage error
  • 3: Service not found
  • 4: Daemon not running

You can use these exit codes in scripts to handle errors:

if go-overlay status nginx; then
    echo "nginx is running"
else
    echo "nginx is not running or failed"
fi

Troubleshooting

Command Not Found

If you get a "command not found" error:

  1. Ensure Go Overlay is installed: go-overlay install
  2. Check if the binary is in your PATH
  3. Try using the full path to the binary

Cannot Connect to Daemon

If CLI commands fail with connection errors:

  1. Verify the daemon is running: ps aux | grep go-overlay
  2. Check IPC socket permissions
  3. Ensure you're running commands as the correct user

Permission Denied

If you get permission errors:

  1. Check file permissions on the binary
  2. Verify IPC socket permissions
  3. Run with appropriate user privileges

See Also