The HostAtlas Server CLI is an opinionated on-server tool that fetches infrastructure recipes from your HostAtlas platform, prompts for parameters, executes them locally, and reports the result back for full audit logging.

Think wrangler for Cloudflare — but for server management.

Note

This binary is also named hostatlas, same as the desktop CLI. They’re distinct tools: the desktop CLI runs on your laptop and manages your fleet; the Server CLI runs on a server and executes recipes on that server only. Both use the same conventional command structure so there’s no learning curve when switching between them.

How it works

$ hostatlas create vhost

  Domain: example.com
  Document Root: /var/www/example
  PHP Version: 8.3
  Enable SSL: yes

  → Fetching recipe "create_vhost" from HostAtlas...

  → Step 1: Create document root
    mkdir -p /var/www/example
    ✓ Done

  → Step 2: Generate nginx vhost config
    ✓ Done

  → Step 3: Issue SSL certificate
    certbot certonly --nginx -d example.com
    ✓ Done

  → Step 4: Reload nginx
    systemctl reload nginx
    ✓ Done

  ✓ Recipe completed successfully (4 steps)

The CLI fetches the recipe from your HostAtlas platform, prompts for each parameter, executes each step locally, and reports the full transcript (stdout / stderr / exit codes) back for the audit trail.

Requirements

• HostAtlas Agent installed on the server (/etc/hostatlas/agent.yml must exist)
• Agent must be registered and connected to your HostAtlas instance

The Server CLI uses the same agent token from /etc/hostatlas/agent.yml — no separate login required. If the agent is installed, the CLI works.

Install

curl -sSL https://install.hostatlas.app/server-cli.sh | sudo bash

The installer detects your OS + architecture, downloads the matching binary from install.hostatlas.app/server-cli/latest/, verifies its SHA-256 checksum, and drops it at /usr/local/bin/hostatlas.

The top-level https://install.hostatlas.app/server-cli/version.json carries the full list under binaries[] (filename, size, sha256, url) for scripted installs.

Commands

Show info + available commands

hostatlas

Displays the HostAtlas banner, server info, and all available commands fetched from your platform.

List all recipes

hostatlas list

Shows a detailed table of all available CLI recipes grouped by category.

Run a recipe

hostatlas <group> <action>

The <group> <action> pair maps to the recipe tag <group>_<action>. Examples:

Command	CLI Tag	What it does
hostatlas create vhost	create_vhost	Create nginx / apache virtual host
hostatlas enable ssl	enable_ssl	Issue Let’s Encrypt certificate
hostatlas create database	create_database	Create MySQL / PostgreSQL database + user
hostatlas create user	create_user	Create system user with SSH key
hostatlas enable firewall	enable_firewall	Set up UFW firewall rules
hostatlas deploy laravel	deploy_laravel	Git clone + composer + migrate
hostatlas setup redis	setup_redis	Install and configure Redis
hostatlas run backup	run_backup	Execute a backup script
hostatlas update system	update_system	apt update + upgrade
hostatlas flush caches	flush_caches	Clear Laravel / app caches

The above are examples — actual available commands depend on which recipes are enabled for the CLI in your dashboard.

Version

hostatlas version

Parameters

Recipes can define parameters with placeholders like {{domain}}. The CLI prompts for each interactively:

$ hostatlas create vhost

  Domain: example.com
  Document Root [/var/www]: /var/www/example
  PHP Version [8.3]:
  Enable SSL (y/n) [y]:

• Required parameters must be filled
• Default values shown in [brackets]
• Password fields are masked as they’re typed
• Boolean fields accept y / n

Adding custom commands

Commands are managed in your HostAtlas dashboard under Recipes / Scripts. Any recipe with a CLI Tag set becomes available in the Server CLI:

1. Go to Recipes / Scripts in your HostAtlas dashboard
2. Create or edit a recipe
3. Set the CLI Tag (e.g. deploy_app)
4. Set the CLI Group (e.g. deploy)
5. Set the CLI Description (shown in hostatlas list)
6. The command is immediately available on every server that has the Server CLI installed: hostatlas deploy app

No re-install or restart needed on the server side — the recipe list is fetched at each hostatlas invocation.

Execution logging

Every command execution is reported back to the platform:

• Recipe name and parameters used
• Full stdout / stderr for each step
• Exit code and success / failure status
• Timestamp and hostname

View execution history in Recipes / Scripts → History in your dashboard.

Configuration

The Server CLI reads from the agent’s config file — no additional configuration needed:

/etc/hostatlas/agent.yml

agent_id: "your-agent-id"
agent_token: "your-agent-token"
api_url: "https://api.hostatlas.app"

Security

• Commands execute locally on the server — no remote execution surface, no reverse tunnel
• Only recipes from your HostAtlas tenant are visible or runnable
• All executions logged in the HostAtlas audit trail (parameter values, output, exit code, timestamp, server)
• Agent-token authentication — same security model as the agent’s own communication
• Parameter values escaped before command substitution to defeat injection attempts

Related

• Agent — required prerequisite; provides the auth token
• CLI — desktop counterpart for managing multiple servers from your laptop
• Automations — where recipes are defined and tagged for the CLI