CLI · hostatlas — HostAtlas

— Verbs you'll use daily

42 commands. 12 you'll actually memorize.

Everything follows hostatlas <noun> <verb> [target] [--flags]. If you can spell it, you can guess it.

hostatlas login

browser-based OAuth · stores token in keyring

hostatlas hosts

list, get, ssh, restart, tag, drain

hostatlas ssh

shortcut for hosts ssh with smart fuzzy match

hostatlas deploy

canary or blue/green · streams logs · auto-rollback

hostatlas logs

tail, grep, since, until — across hosts at once

hostatlas why

root-cause assistant in plain English, with citations

hostatlas automation

list, run, dry-run, revert, lint, arm, pause

hostatlas domains

list, add, dns, cert, whois

hostatlas alerts

list, ack, snooze, escalate, history

hostatlas dev

spin a local dev env with prod-shaped data

hostatlas preview

spin / tear down a PR-scoped environment

hostatlas apply

apply a plan (deploy, automation, config patch)

hostatlas backups

list, snapshot, restore, schedule

hostatlas k8s

contexts, pods, exec, logs — kubeconfig-aware

hostatlas audit

tail signed audit log · filter by actor / action

hostatlas cost

spend by host, tag, environment, this month

— Reference

Pinned to the verb you'd type at 2 AM.

A few of the most-used commands, expanded. Every command also has hostatlas <cmd> --help.

hostatlas hosts list

List hosts in your fleet. Filter by tag, region, status, or any custom label. Pipes cleanly into jq or xargs.

Synopsis

$ hostatlas hosts list [--tag <t>] [--region <r>] [--status <s>] [-o table|json|yaml]

Flags

--tag <tag>

Filter by tag. Repeatable. --tag prod --tag region:eu

--region <region>

Filter by region. Glob-friendly: --region eu-*

--status <status>

One of healthy / warn / critical / offline. Comma-separated for multiple.

-o, --output <fmt>

Output format: table (default), json, yaml, names.

--watch, -w

Refresh every 2s in place. Press q to quit.

--limit <n>

Max rows to print (default 100; use 0 for all).

Examples

# All critical EU production hosts, watched live
$ hostatlas hosts list --tag prod --region eu-* --status critical -w

# Pipe names of all warning hosts into a parallel restart
$ hostatlas hosts list --status warn -o names | xargs -P4 -I{} hostatlas ssh {} -- 'sudo systemctl restart api'

# JSON, then jq to find the most disk-pressured host
$ hostatlas hosts list -o json | jq -r 'max_by(.disk_pct) | .name'
keywest

Show full detail for a single host: services, containers, certs, recent metrics, open alerts.

Synopsis

$ hostatlas hosts get <host> [--services] [--alerts] [-o table|json|yaml]

Flags

<host>

Hostname, IP, or UUID. Tab-completes from your synced fleet.

--services

Include the full list of running services + their plugin metrics.

--alerts

Include open and recently-resolved alert events.

-o, --output <fmt>

table (default), json, yaml.

Examples

# Quick health snapshot
$ hostatlas hosts get keywest --alerts

# Full JSON for jq scripting
$ hostatlas hosts get keywest --services -o json | jq .services[].name

Open an SSH session to a host using the right key, the right user, the right jump host — all looked up from the platform.

Synopsis

$ hostatlas ssh <host> [-- <command…>] [--user <u>] [--tunnel <port>]

Flags

<host>

Resolved against your fleet. Hostname, IP, or UUID.

-- <command…>

Run a remote command and exit (non-interactive).

--user <user>

Override the default SSH user for this host.

--tunnel <local:remote>

Set up a port forward for the session.

Examples

# Open an interactive shell
$ hostatlas ssh keywest

# One-shot remote command
$ hostatlas ssh keywest -- sudo tail -f /var/log/nginx/error.log

# Forward Postgres locally for a query session
$ hostatlas ssh db-prod-01 --tunnel 5433:5432

Tail logs from one host, many hosts, or a tag set. Lines are merged + interleaved with source hostname.

Synopsis

$ hostatlas logs <host|tag> [--service <s>] [--grep <pattern>] [--since <duration>]

Flags

<host|tag>

A single host, a tag-set like @prod, or @all.

--service <name>

Limit to one service (nginx, php-fpm, postgres, …).

--grep <pattern>

Server-side regex filter so we ship less over the wire.

--since <duration>

Start point: 5m, 1h, 24h. Default tails live.

-f, --follow

Keep following after backfill.

Examples

# Live tail nginx errors across prod
$ hostatlas logs @prod --service nginx --grep "5\d\d " -f

# Last hour of php-fpm slow log on one box
$ hostatlas logs keywest --service php-fpm --since 1h

Run the configured deploy pipeline for an app: agent-side recipe, health gate, optional canary, audit trail.

Synopsis

$ hostatlas deploy <app> [--ref <branch|sha>] [--canary <pct>] [--dry-run]

Flags

<app>

App key from your pipelines config.

--ref <ref>

Branch name or commit SHA. Default: main HEAD.

--canary <pct>

Roll to this fraction of the fleet first, gate on health.

--dry-run

Print the plan, run no commands.

Examples

# Deploy the API to all prod hosts
$ hostatlas deploy api --ref main

# 10% canary, hold until I press enter
$ hostatlas deploy api --ref release/v4.2 --canary 10

Spin up a preview environment for a branch. Writes a URL, seeds the database snapshot, expires automatically.

Synopsis

$ hostatlas preview <branch> [--ttl <duration>] [--seed <snapshot>]

Flags

Git branch name. Maps 1:1 to the preview slug.

--ttl <duration>

Auto-delete after. Default 7d.

--seed <snapshot>

Restore a named DB snapshot (prod-readonly, last-week, …).

Examples

# Preview the billing feature branch with last week's data
$ hostatlas preview feat/billing-v2 --seed last-week

Apply infrastructure config from a YAML/JSON file: alerts, monitors, channels, schedules. Idempotent, diff-able.

Synopsis

$ hostatlas apply -f <file> [--dry-run] [--diff]

Flags

-f, --file <path>

YAML or JSON config. Repeatable.

--dry-run

Print the planned diff, write nothing.

--diff

Show what would change vs current platform state.

Examples

# Plan a multi-file apply
$ hostatlas apply -f alerts.yaml -f monitors.yaml --diff

Ask the AI assistant a free-form question about your fleet. Returns the answer plus the evidence trail (logs, metrics, deploys).

Synopsis

$ hostatlas why "<question>" [--scope <host|tag>] [--since <duration>]

Flags

Quoted natural-language question.

--scope

Narrow to a host, tag set, or service.

--since <duration>

Time window for the AI to consider.

Examples

# Why did latency spike on api this morning?
$ hostatlas why "what caused the API latency spike around 09:42?" --scope @api --since 4h

List firing alerts, acknowledge them, resolve them, or print the rule that fired.

Synopsis

$ hostatlas alerts [list|ack|resolve|show] [--severity <s>] [--host <h>]

Flags

list (default)

Currently-firing alerts.

ack <id>

Acknowledge an alert event.

resolve <id>

Force-resolve (rule keeps re-evaluating).

show <id>

Full rule + condition + recent history.

--severity

Filter: critical / warning.

Examples

# Live triage view
$ hostatlas alerts list --severity critical -w

# Ack everything on keywest, AI will keep watching
$ hostatlas alerts list --host keywest -o ids | xargs -L1 hostatlas alerts ack

Run the security/compliance audit on a host. Returns failed checks, severity-scored, with remediation hints.

Synopsis

$ hostatlas audit <host> [--profile <name>] [-o table|json]

Flags

<host>

Target host.

--profile <name>

Audit profile: cis, soc2, custom-name.

-o, --output

table (default) or json for piping.

Examples

# CIS-aligned audit on a prod box
$ hostatlas audit keywest --profile cis

Trigger an automation by key. Inputs passed as flags; runs server-side, you watch the live log.

Synopsis

$ hostatlas automation run <key> [--input <k=v>] [-w]

Flags

<key>

Automation key (slug from the UI / config).

--input <k=v>

Input variable. Repeatable.

-w, --watch

Stream the run log to stdout until done.

Examples

# Restart the worker pool on a specific host
$ hostatlas automation run worker-restart --input host=keywest -w

Validate an automation YAML before pushing: syntax, references, permissions.

Synopsis

$ hostatlas automation lint <file> [--strict]

Flags

<file>

Path to the automation YAML.

--strict

Treat warnings as errors.

Examples

# Pre-commit hook lint
$ hostatlas automation lint automations/worker-restart.yaml --strict

Forget the flags. Just say what you want.

Quote any string and hostatlas resolves it to a real command — and shows you the resolution before running. So you learn the syntax by accident.

✓ Always shows the resolved command before executing
✓ Confirms before any write action
✓ Falls back to --dry-run on first try of unfamiliar commands
✓ Works offline with the local model (Phi-3.5)

natural language

$ hostatlas "restart nginx on all eu prod boxes"
→ resolved as:
hosts list --tag prod --region eu-* -o names |
xargs -P4 -I{} hostatlas ssh {} -- 'sudo systemctl reload nginx'
⚠ Will run on 7 hosts. Continue? [y/N] _

$ hostatlas "what changed in prod last hour"
→ resolved as: audit list --tag prod --since 1h
● 14:08 · ansible · chmod /var/log/nginx · @anna
● 14:30 · cron · postgres VACUUM FULL · system
● 14:35 · automation · force-rotate · system

$ hostatlas "show k8s pods that crashed today"
→ resolved as: k8s pods --status crashloop --since today

— Shell completions

Type three letters. Tab. Done.

Completions know your fleet. Tab on hostatlas ssh and you'll see the actual hosts you have, ranked by recency.

zsh

install via brew · also Oh My Zsh plugin

bsh

bash

requires bash-completion ≥ 2.1

fsh

fish

native, dynamic, fuzzy

psh

PowerShell

argument completer · 7.2+

$ hostatlas completions install // auto-detects your shell copy

Discovery & Mapping

For developers

HostAtlas - your fleet, in one keystroke.

42 commands. 12 you'll actually memorize.

Pinned to the verb you'd type at 2 AM.

Forget the flags. Just say what you want.

Type three letters. Tab. Done.

Five seconds to install. The next 10 years to thank yourself.