XeroOps Docs — CLI Reference

Command Lifecycle

── First-time setup (run once) ──────────────────────
xeroops activate   Validate and store your license
xeroops init       Generate keys, copy AMIs to your region
xeroops create     Provision VPC, ENIs, S3, IAM (no EC2 yet)
xeroops verify     Confirm all resources exist in AWS
xeroops configure  Upload secrets and config to S3

── Daily workflow ────────────────────────────────────
xeroops deploy     Launch EC2 instances from AMIs
xeroops cleanup    Terminate EC2s (keep everything else)

── Utilities ─────────────────────────────────────────
xeroops status     Show current state (no AWS calls)
xeroops destroy    Permanently delete all AWS resources

activate

xeroops activate Validate license and store it encrypted in ~/.xeroops/

-license-dir <path> Path to your license.json file. Required.

Verifies the RSA-PSS signature on your license, calls AWS STS to get your account ID, and confirms it matches the license's account_id. The validated license is stored encrypted at ~/.xeroops/license.enc.

xeroops activate -license-dir ./license.json

⚠️

Your license is cryptographically bound to one AWS account. Running in any other account will fail with an account mismatch error.

init

xeroops init Generate all cryptographic keys and prepare deployment config

(interactive) Prompts for AWS region and optionally a VPN domain for Route53 DNS.

Generates:

WireGuard server keypair (unique per deployment)
WireGuard bootstrap client keypair
SSH RSA-4096 keypair
CloudFront RSA-2048 keypair for signed URLs

If your region differs from the AMI source region, both AMIs are copied automatically — this takes 5–10 minutes. Public keys are saved to deployment.json; private keys are AES-256-GCM encrypted in state.enc. Your WireGuard client config is written to ~/.xeroops/xeroops.conf.

create

xeroops create Provision all AWS infrastructure except EC2 instances

(no flags) Reads deployment config from state generated by init.

Creates in order, with full rollback on failure:

VPC + public and private subnets
Internet Gateway + route tables
S3 VPC Endpoint (all nodes access S3 without internet)
9 security groups (lb, wireguard, app, postgres, redis, management, internal_communication, internal_ssh, ssh_from_lb)
EC2 KeyPair (imports SSH public key)
IAM Role + Instance Profile with S3, EC2, Route53, SES permissions
4 S3 buckets (uploads, pgdump, walg, logs)
7 ENIs with static private IPs
2 EBS data volumes for db1 and db2

💡

Everything created by create is either free or near-free when idle. VPC, ENIs, security groups, and IAM cost nothing. EIPs cost ~$3.50/month each when unassociated. S3 costs pennies.

verify

xeroops verify Confirm all provisioned resources exist in AWS

(no flags) Makes read-only AWS API calls. Safe to run at any time.

Calls AWS APIs to verify every resource from create still exists. Prints a pass/fail table with resource IDs. Exits with a non-zero code if any check fails — useful in scripts.

configure

xeroops configure Set secrets and upload credential files to S3

(interactive) Prompts for all secrets. Input is hidden.

Prompts for:

Secret	Purpose
PGPASSWORD	PostgreSQL password (min 20 chars)
JWT_SECRET	Auth service JWT signing key (min 32 chars)
LUA_ADMIN_SECRET	Admin API access via nginx Lua WAF
INTERNAL_SERVICE_SECRET	Service-to-service auth token
REDIS_PASSWORD	Redis authentication

Uploads to your S3 uploads bucket:

config/instance-config.env — non-secret instance configuration
config/prod-credentials.env — all secrets
config/service-ports.json — role-to-service mapping

deploy

xeroops deploy Launch EC2 instances and bring the cluster online

(no flags) Pre-flight check verifies S3 config exists before launching any EC2.

Launch sequence:

Pre-flight: verify 3 required S3 config files exist
Check no existing instances (must cleanup first)
Confirm instance list with user
Pre-allocate Elastic IPs
Launch all instances in parallel using pre-created ENIs
Wait for db instances, attach EBS volumes
Associate EIPs to ENIs
Update Route53 DNS (if configured)
Patch ~/.xeroops/xeroops.conf with real WireGuard EIP

After launch, each instance boots from its AMI, pulls config from S3, and starts services automatically. The cluster is fully operational in ~60–90 seconds.

cleanup

xeroops cleanup Terminate EC2 instances only — preserves all other resources

(no flags) Detaches EBS volumes before termination to preserve data.

Terminates EC2 instances, detaches EBS data volumes, disassociates and releases EIPs, cleans Route53 DNS. Preserves: VPC, ENIs, security groups, EBS volumes, S3 buckets, IAM — everything needed to redeploy instantly.

💡

Run this every evening. Your overnight cost drops to ~$7/month (S3 + EIPs). Run xeroops deploy in the morning to get back up in 60 seconds.

status

xeroops status Show current state from local files — no AWS API calls

(no flags) Reads ~/.xeroops/ only. Safe and instant.

Displays: license info, deployment config, infrastructure resource IDs, ENIs, EBS volumes, EIPs.

destroy

xeroops destroy Permanently delete ALL AWS resources. Irreversible.

-confirm Required. Also prompts you to type "destroy" to confirm.

--dry-run Preview what would be deleted without deleting anything.

⚠️

This is permanent. Deletes S3 buckets (empties first), EBS volumes, ENIs, security groups, IAM roles, VPC, and all local state files. Running instances must be cleaned up first. Your data cannot be recovered after this.

# Preview first
xeroops destroy --dry-run

# Actually destroy
xeroops destroy -confirm
  Type "destroy" to confirm: destroy