# CLI Reference

Complete documentation for the deployally commands.

# Installation

curl -fsSL https://get.deployally.com/init.sh | sudo bash

Release candidate channel:

curl -fsSL https://get.deployally.com/init.sh | sudo bash -s -- --rc

Direct binary download:

# x86_64
curl -Lo deployally https://get.deployally.com/x86_64/deployally
chmod +x deployally
sudo mv deployally /usr/local/bin/

# aarch64
curl -Lo deployally https://get.deployally.com/aarch64/deployally
chmod +x deployally
sudo mv deployally /usr/local/bin/

# Command Structure

deployally [global-command]
deployally <subcommand> [options]

Global commands (--version, self-update) and the catalog and deploy commands (deploy, validate, template new, templates, apikey) all live at the root level.

# Global Commands

# `--version` / `-V`

Shows the CLI version.

deployally --version

# `--help` / `-h`

Shows help.

deployally --help
deployally deploy --help

# `self-update`

Updates the CLI to the latest version from the CDN.

deployally self-update

The command downloads the binary, validates it (-V), swaps it in, and restores the backup if anything fails.

# Catalog and Deploy Commands

Quick table:

# `validate`

Validates the structure, Reflang references, and archetype contracts of a template.

# Syntax

deployally validate --species <SPECIES> [options]

# Options

# Exit Codes

# Examples

# Validate a catalog template
deployally validate --species memos

# Validate a local template before publishing
deployally validate --species my-app --templates-dir ./templates

# JSON output (programmatic use)
deployally validate --species memos --json

# What is validated

• Template schema (required fields per archetype)
• Every ${input.X}, ${secrets.X}, etc. has a declared origin
• Reflang functions are called with the correct arity
• A healthcheck is declared when the archetype requires it (multi_component_saas)
• HTTP routes reference existing components
• ContractIR predicates satisfy the archetype

# `template new`

Generates a YAML scaffold for a new template, ready for editing.

# Syntax

deployally template new --archetype <A> --species <S> [options]

# Options

# Examples

# Simple application
deployally template new \
  --archetype application \
  --species memos-clone \
  --image neosmemo/memos:0.20 \
  --port 5230 \
  --out memos-clone.yaml

# Asset with a dispatcher for database creation
deployally template new \
  --archetype asset \
  --species my-db \
  --image my-org/db:latest \
  --port 5432 \
  --data-path /var/lib/db \
  --provision-action create-database \
  --out my-db.yaml

# Multi-component SaaS
deployally template new \
  --archetype multi_component_saas \
  --species my-saas \
  --out my-saas.yaml

# `deploy`

Deploys an instance of a template.

# Syntax

deployally deploy --species <S> --instance-uid <UID> [options]

# Options

# Examples

# Basic deploy
deployally deploy --species memos \
  --instance-uid memos-001 \
  --input WEB_HOSTNAME=memos.example.com \
  --apply

# Dry-run to inspect the plan
deployally deploy --species memos \
  --instance-uid memos-001 \
  --input WEB_HOSTNAME=memos.example.com \
  --dry-run

# Production profile
deployally deploy --species mysql \
  --instance-uid mysql-prod \
  --profile production \
  --apply

# Specific variant (MySQL 5.7 instead of 8.4)
deployally deploy --species mysql \
  --instance-uid mysql-legacy \
  --variant mysql-5.7 \
  --apply

# Auto-provision a database for WordPress
deployally deploy --species wordpress \
  --instance-uid blog-001 \
  --input WEB_HOSTNAME=blog.example.com \
  --input ADMIN_EMAIL=admin@example.com \
  --provision-missing-assets \
  --apply

# Deploy a local template
deployally deploy --species my-app \
  --instance-uid my-app-001 \
  --templates-dir ./templates \
  --source local \
  --apply

# Offline mode (no registry calls)
deployally deploy --species memos \
  --instance-uid memos-001 \
  --offline \
  --apply

# Execution Pipeline

1. Fetch: pull the template (local → cache → registry, unless --offline)
2. Build context: apply defaults from declared inputs; merge with --input
3. Wizard: prompt for what's missing (compacted by prefix); skipped when --input is exhaustive
4. Reflang resolve: substitute ${...} across every section
5. Validate: ContractIR + archetype predicates
6. Archetype defaults merge: apply networks, CCS labels, restart policy
7. Preflight: DNS, port conflicts, network existence
8. Auto-provision (when --provision-missing-assets): bring up missing assets in cascade
9. Apply: create volumes, networks, containers (Docker SDK)
10. Wait healthy: poll the declared healthcheck with retry

# `undeploy`

Removes an instance created by deploy — the inverse operation. Dry-run is the default: without --apply, the command only prints the removal plan and doesn't touch anything.

# Syntax

deployally undeploy --instance-uid <UID> [options]

# Options

# Examples

# Preview (dry-run — doesn't touch anything)
deployally undeploy --instance-uid memos-001

# Remove containers + registry, preserving data (redeploy brings everything back)
deployally undeploy --instance-uid memos-001 --apply

# Full removal (irreversible) — requires typing the instance_uid or --yes
deployally undeploy --instance-uid memos-001 --apply --purge-data --yes

# Machine output for integration (CCS)
deployally undeploy --instance-uid memos-001 --apply --purge-data --yes -o json

# What is never removed

• kind: bind volumes (system paths)
• The public network
• Shared assets or tenant databases (declared in deps[])
• Containers that don't carry the instance's ccs.systems/uid label

# Undeploy is local

An instance removed locally may still be registered on the server: running deploy again with the same --instance-uid reprovisions everything (same secrets, same volumes). For a definitive deactivation, unregister the instance on the server.

# Configuration File

Default location: /opt/deployally/config.yaml

api:
  url: https://sys.deployally.com
  api_key: da_xxx

defaults:
  source: remote
  profile: development

logging:
  level: info

# Environment Variables

# Global Exit Codes

# Next Steps

• Reflang Reference — full template language syntax
• Getting Started — first deploy
• Templates — how archetypes work
• API Integration — programmatic use (restricted)