alien-deploy CLI

Your customer's admin runs alien-deploy to set up a deployment with their own credentials, run the Operator, join machines, and carry releases into air-gapped sites. You can white-label it under your product name.

This page is generated from the help output of version 3.3.41. Run alien-deploy <command> --help for the same text in your terminal.

Install

Install the latest stable release on macOS or Linux:

curl -fsSL https://alien.dev/install | sh -s -- --binary alien-deploy

On Windows, run & ([scriptblock]::Create((irm https://alien.dev/install.ps1))) -Binary alien-deploy in PowerShell. Setup links and the alien onboard output include the exact install and deploy command for each customer.

Global flags

These flags work on every alien-deploy command.

Flag	Description
`-v, --verbose`	Verbose logging.

Commands

Command	Description
`alien-deploy deploy`	Deploy the application to a target environment.
`alien-deploy status`	Show deployment status.
`alien-deploy list`	List tracked deployments.
`alien-deploy destroy`	Destroy a deployment and its resources.
`alien-deploy register`	Register an externally-provisioned stack (CloudFormation Outputs, Terraform, …) with a manager.
`alien-deploy operator`	Manage the alien-operator background service.
`alien-deploy join`	Join this Linux host to a Machines deployment.
`alien-deploy leave`	Leave a Machines deployment from this host.
`alien-deploy sync`	Keep an air-gapped deployment up to date (run on both sides of the gap).
`alien-deploy rollback`	Return an air-gapped deployment to its previous release.

Deploy

`alien-deploy deploy`

Deploy the application to a target environment.

alien-deploy deploy [OPTIONS]

Flag	Description
`--token <TOKEN>`	Authentication token (deployment or deployment group token). Env: `ALIEN_TOKEN`.
`--token-file <TOKEN_FILE>`	Read authentication token from a file.
`--manager-url <MANAGER_URL>`	Manager URL override for pull-model platforms. Cloud push deployments resolve their manager and install context from the platform API so setup has the management configuration it needs. Env: `ALIEN_MANAGER_URL`.
`--base-url <BASE_URL>`	Platform API base URL. Used for manager discovery when ALIEN_MANAGER_URL is not set. Env: `ALIEN_BASE_URL`.
`--platform <PLATFORM>`	Target platform (aws, gcp, azure, kubernetes, machines, local).
`--base-platform <BASE_PLATFORM>`	Base cloud platform for managed Kubernetes setup (aws, gcp, azure). Env: `OPERATOR_BASE_PLATFORM`.
`--name <NAME>`	Deployment name (for tracking).
`--setup-item <SETUP_ITEM>`	Setup item to install from the setup link (application, models, keys, storage, registry or sandbox). Defaults to the link's only item. Values: `application` (The application itself), `models` (AI models in the customer's cloud), `keys` (Customer-managed encryption keys), `storage` (A storage bucket in the customer's cloud), `registry` (A container registry in the customer's cloud), `sandbox` (A remote sandbox).
`--encryption-key <ENCRYPTION_KEY>`	Encryption key for operator database (required for pull model). Env: `OPERATOR_ENCRYPTION_KEY`.
`--setup-update`	Rerun setup for the existing deployment's requested release, using setup credentials.
`--deployment-id <DEPLOYMENT_ID>`	Existing deployment ID for setup from a fresh runner.
`--update-operation-id <UPDATE_OPERATION_ID>`	Exact pending update operation to configure and apply setup for.
`--release-id <RELEASE_ID>`	Exact release expected by the setup update.
`-y, --yes`	Skip confirmation prompt.
`--foreground`	Run the operator in the foreground instead of installing as a service. Useful for testing: Ctrl+C to stop.
`--data-dir <DATA_DIR>`	Data directory for operator state (foreground mode only). Defaults to ~/.alien/operator-data.
`--enable-local-debug`	Enable Local runtime debug commands and shells on the installed operator service.
`--local-debug-shell-command <LOCAL_DEBUG_SHELL_COMMAND>`	Override the shell command used by Local runtime debug shells.
`--namespace <NAMESPACE>`	Kubernetes namespace for Helm installs. Env: `ALIEN_KUBERNETES_NAMESPACE`.
`--helm-release <HELM_RELEASE>`	Helm release name for Kubernetes installs. Env: `ALIEN_HELM_RELEASE`.
`--kubeconfig <KUBECONFIG>`	Kubeconfig path for Kubernetes installs. Defaults to KUBECONFIG or kubectl defaults. Env: `KUBECONFIG`.
`--kube-context <KUBE_CONTEXT>`	Kubernetes context for Helm installs. Env: `ALIEN_KUBE_CONTEXT`.
`--operator-image <OPERATOR_IMAGE>`	alien-operator image for Kubernetes Helm installs. Env: `ALIEN_OPERATOR_IMAGE`.
`--external-bindings-secret <EXTERNAL_BINDINGS_SECRET>`	Kubernetes Secret containing external-bindings.json for existing services. The Secret must exist in the install namespace before deployment.
`--config <CONFIG>`	TOML file containing deployment settings.
`--quota-warning-override <QUOTA_WARNING_OVERRIDES>`	Downgrade a quota failure to a visible warning for this deployment (repeatable).
`--clear-quota-warning-overrides`	Remove all saved quota warning overrides from this deployment.
`--validate-only`	Validate the config locally without authentication, API calls, or deployment tracking.
`--input <INPUT_VALUES>`	Stack input value for setup (id=value).
`--public-endpoint <PUBLIC_ENDPOINTS>`	Public URL for an exposed endpoint in <resource-id>.<endpoint-name>=<absolute-url> form. Intended for pull-model deployments where DNS, TLS, and ingress are owned outside Alien. Repeat this flag for multiple endpoints.

Network options:

Flag	Description
`--endpoint-access <ENDPOINT_ACCESS>`	Who can reach public endpoints: internet or private (AWS managed containers only).
`--network <NETWORK_MODE>`	Network mode: auto, use-default, create, byo. auto (system decides (create VPC if containers need it, skip otherwise) use-default ) use cloud provider's default VPC (fast, good for dev) create (create an isolated VPC (production-grade) byo ) bring your own VPC/VNet. Default: `auto`.
`--network-cidr <NETWORK_CIDR>`	VPC CIDR block (create mode only, auto-generated if omitted).
`--availability-zones <AVAILABILITY_ZONES>`	Number of availability zones (create mode only, default: 2).
`--vpc-id <VPC_ID>`	Existing VPC ID (byo mode, AWS).
`--public-subnet-ids <PUBLIC_SUBNET_IDS>`	Comma-separated public subnet IDs (byo mode, AWS).
`--private-subnet-ids <PRIVATE_SUBNET_IDS>`	Comma-separated private subnet IDs (byo mode, AWS).
`--security-group-ids <SECURITY_GROUP_IDS>`	Comma-separated security group IDs (byo mode, AWS, optional).
`--network-name <NETWORK_NAME>`	Existing VPC network name (byo mode, GCP).
`--subnet-name <SUBNET_NAME>`	Subnet name (byo mode, GCP).
`--network-region <NETWORK_REGION>`	Subnet region (byo mode, GCP).
`--vnet-resource-id <VNET_RESOURCE_ID>`	Existing VNet resource ID (byo mode, Azure).
`--public-subnet-name <PUBLIC_SUBNET_NAME>`	Public subnet name (byo mode, Azure).
`--private-subnet-name <PRIVATE_SUBNET_NAME>`	Private subnet name (byo mode, Azure).

Examples:

# Deploy to AWS using a deployment group token
alien-deploy deploy --token ax_dg_abc123... --platform aws

# Deploy using a token file so the token is not exposed in argv
alien-deploy deploy --token-file /run/alien/token --platform local

# Deploy a local pull-model workload behind customer-managed ingress
alien-deploy deploy --token-file /run/alien/token --platform local --public-endpoint gateway.api=https://gateway.example.com

# Deploy with an isolated VPC
alien-deploy deploy --token ax_dg_abc123... --platform aws --network create

# Deploy into an existing VPC
alien-deploy deploy --token ax_dg_abc123... --platform aws --network byo --vpc-id vpc-0abc123 --public-subnet-ids subnet-pub1 --private-subnet-ids subnet-priv1

# Redeploy an existing tracked deployment
alien-deploy deploy --name production

# Deploy to a manager you run
ALIEN_MANAGER_URL=https://manager.example.com alien-deploy deploy --token ax_dg_abc123... --platform aws

`alien-deploy status`

Show deployment status.

alien-deploy status [OPTIONS] --name <NAME>

Flag	Description
`--name <NAME>`	Deployment name.
`--token <TOKEN>`	Authentication token (optional if deployment is tracked). Env: `ALIEN_TOKEN`.
`--token-file <TOKEN_FILE>`	Read authentication token from a file.
`--manager-url <MANAGER_URL>`	Manager URL (optional if deployment is tracked). Env: `ALIEN_MANAGER_URL`.
`--base-url <BASE_URL>`	Platform API base URL used for manager discovery when deployment is not tracked. Env: `ALIEN_BASE_URL`.
`--platform <PLATFORM>`	Platform used only when discovering the manager URL for an untracked deployment.
`--json`	Output status as JSON.

Examples:

# Show status of a tracked deployment
alien-deploy status --name production

`alien-deploy list`

List tracked deployments.

alien-deploy list [OPTIONS]

Flag	Description
`--token <TOKEN>`	Authentication token for remote manager listing. Env: `ALIEN_TOKEN`.
`--token-file <TOKEN_FILE>`	Read authentication token from a file.
`--manager-url <MANAGER_URL>`	Manager URL. If omitted, uses the platform API to discover the manager. Env: `ALIEN_MANAGER_URL`.
`--base-url <BASE_URL>`	Platform API base URL used for manager discovery. Env: `ALIEN_BASE_URL`.
`--platform <PLATFORM>`	Platform used only when discovering the manager URL.

`alien-deploy destroy`

Destroy a deployment and its resources.

alien-deploy destroy [OPTIONS]

Flag	Description
`--name <NAME>`	Locally tracked deployment name.
`--deployment-id <DEPLOYMENT_ID>`	Existing direct-setup deployment ID (for recovery without a local tracker).
`--token <TOKEN>`	Authentication token (optional if deployment is tracked). Env: `ALIEN_TOKEN`.
`--token-file <TOKEN_FILE>`	Read authentication token from a file.
`--manager-url <MANAGER_URL>`	Manager URL (optional if deployment is tracked). Env: `ALIEN_MANAGER_URL`.
`--force-delete-record`	Force deletion: skip resource teardown, only remove the deployment record.
`-y, --yes`	Skip confirmation prompt.

Examples:

# Destroy a tracked deployment
alien-deploy destroy --name production

# Resume direct-setup teardown from a fresh machine
alien-deploy destroy --deployment-id dep_123 --token-file /run/secrets/deployment-token --manager-url https://manager.example.com

# Force-delete an imported deployment record
alien-deploy destroy --name production --force-delete-record

# Destroy a tracked deployment using explicit manager credentials
alien-deploy destroy --name production --token ax_dg_abc123... --manager-url https://manager.example.com

Existing infrastructure

`alien-deploy register`

alien-deploy register [OPTIONS] --import <IMPORT> --token <TOKEN>

Flag	Description
`--import <IMPORT>`	Source the resolved import payload comes from. Values: `cloudformation`.
`--stack-name <STACK_NAME>`	CloudFormation stack name (required when --import cloudformation). Also used as the default deployment name when `--name` is omitted.
`--name <NAME>`	Deployment name. Must be unique within the deployment group; the manager returns 409 on collision. Defaults to the source-specific natural name (CloudFormation: `--stack-name`).
`--region <REGION>`	AWS region the CloudFormation stack lives in. Default: `us-east-1`. Env: `AWS_REGION`.
`--manager-url <MANAGER_URL>`	Standalone manager URL. Omit for hosted registration through Platform. Env: `ALIEN_MANAGER_URL`.
`--base-url <BASE_URL>`	Platform API URL for hosted registration. Defaults to the URL embedded in a packaged CLI, then https://api.alien.dev. Env: `ALIEN_BASE_URL`.
`--token <TOKEN>`	Deployment token authorizing the import. Env: `ALIEN_TOKEN`.
`--input <INPUT_VALUES>`	String stack input for registration (id=value). Repeat for multiple inputs.
`--input-json <JSON_INPUT_VALUES>`	Typed JSON stack input for registration (id=<json>). Repeat for multiple inputs.
`--dry-run`	Print a diagnostic payload to stdout instead of POSTing it.

Examples:

# Register the outputs of an `alien render --format cloudformation` stack
alien-deploy register \
    --import cloudformation \
    --stack-name acme-prod \
    --region us-east-1 \
    --base-url https://api.alien.dev \
    --token dg_... \
    --input region=us-east-1 \
    --input-json replicas=3

Operator service

`alien-deploy operator`

Manage the alien-operator background service.

alien-deploy operator [OPTIONS] <COMMAND>

Subcommand	Description
`install`	Install alien-operator as an OS service.
`start`	Start the alien-operator service.
`stop`	Stop the alien-operator service.
`status`	Show the operator service status.
`uninstall`	Uninstall the alien-operator service.

`alien-deploy operator install`

Install alien-operator as an OS service.

alien-deploy operator install [OPTIONS] --sync-url <SYNC_URL> --sync-token <SYNC_TOKEN>

Flag	Description
`--binary <BINARY>`	Path to the alien-operator binary. If omitted, searches PATH.
`--sync-url <SYNC_URL>`	Manager URL for the operator to sync with.
`--sync-token <SYNC_TOKEN>`	Sync authentication token.
`--deployment-id <DEPLOYMENT_ID>`	Deployment ID this service should manage.
`--operator-name <OPERATOR_NAME>`	Human-readable deployment name this service should manage.
`--platform <PLATFORM>`	Target platform (aws, gcp, azure). Default: `local`.
`--data-dir <DATA_DIR>`	Data directory for operator state.
`--encryption-key <ENCRYPTION_KEY>`	Encryption key (64-char hex). Generated if not provided.
`--enable-local-debug`	Enable Local runtime debug commands and shells.
`--local-debug-shell-command <LOCAL_DEBUG_SHELL_COMMAND>`	Override the shell command used by Local runtime debug shells.

`alien-deploy operator start`

Start the alien-operator service.

alien-deploy operator start [OPTIONS]

`alien-deploy operator stop`

Stop the alien-operator service.

alien-deploy operator stop [OPTIONS]

`alien-deploy operator status`

Show the operator service status.

alien-deploy operator status [OPTIONS]

`alien-deploy operator uninstall`

Uninstall the alien-operator service.

alien-deploy operator uninstall [OPTIONS]

Machines

`alien-deploy join`

Join this Linux host to a Machines deployment.

alien-deploy join [OPTIONS]

Flag	Description
`--token <TOKEN>`	Join token printed by the deployment portal.
`--token-file <TOKEN_FILE>`	Read the join token from a file.
`--capacity-group <CAPACITY_GROUP>`	Capacity group this host should join. Default: `general`.
`--zone <ZONE>`	Optional physical or logical zone label for this host.
`--network-interface <NETWORK_INTERFACE>`	Network interface the machine agent should advertise, or "auto" to clear an override.
`--wireguard-endpoint <WIREGUARD_ENDPOINT>`	WireGuard endpoint advertised to peers (IPv4:port), or "auto" to clear it.
`--public-ip <PUBLIC_IP>`	IP used for public endpoint DNS (including a VPN-reachable private IP), or "auto" to clear it.
`--bundle-url <BUNDLE_URL>`	Machine bootstrap bundle manifest URL. Packaged CLIs embed this.
`--control-plane-url <CONTROL_PLANE_URL>`	Control plane API URL for the machine service.
`--cluster-id <CLUSTER_ID>`	Cluster ID the host should join.
`--dry-run`	Print the resolved join plan without installing anything.

`alien-deploy leave`

Leave a Machines deployment from this host.

alien-deploy leave [OPTIONS]

Flag	Description
`--purge`	Also remove durable machine identity and state.
`--dry-run`	Print the leave plan without stopping or removing anything.

Air-gapped sites

`alien-deploy sync`

Keep an air-gapped deployment up to date (run on both sides of the gap).

alien-deploy sync [OPTIONS]

Flag	Description
`--folder <FOLDER>`	Transfer folder (defaults to the one in the current directory).
`--token <TOKEN>`	Deployment token from the vendor. Needed once on the online machine. Env: `ALIEN_SYNC_TOKEN`.
`--manager <MANAGER>`	Manager URL from the vendor. Needed once on the online machine.
`--registry <REGISTRY>`	Site registry (and optional path) for the images. Needed once inside the site.
`--registry-username <REGISTRY_USERNAME>`	Env: `AIRGAP_REGISTRY_USERNAME`.
`--registry-password <REGISTRY_PASSWORD>`	Env: `AIRGAP_REGISTRY_PASSWORD`.
`--insecure-registry`	The site registry serves plain HTTP.
`-n, --namespace <NAMESPACE>`	Namespace (defaults to the application name).
`-f, --values <VALUES>`	Helm values for the site (infrastructure, inputs). Remembered.
`--kube-context <KUBE_CONTEXT>`	Kubernetes context (defaults to the current one). Remembered.
`--trusted-key <TRUSTED_KEY>`	The vendor's bundle key (`ed25519:...`). Needed for the first install. Env: `ALIEN_TRUSTED_KEY`.
`--dry-run`	Show what would happen without installing or downloading anything.
`--full`	Include every image layer, for sites whose reports never come back.

Examples:

# First run, on the online machine (token and URL from the vendor)
alien-deploy sync --token ax_... --manager https://manager.example.com

# Inside the site, the first time
alien-deploy sync --registry registry.internal/vendor -f values.yaml --trusted-key ed25519:...

# Every time after that, on either side
alien-deploy sync
alien-deploy sync --dry-run

`alien-deploy rollback`

Return an air-gapped deployment to its previous release.

alien-deploy rollback [OPTIONS]

Flag	Description
`--folder <FOLDER>`	Transfer folder (defaults to the one in the current directory).
`--kube-context <KUBE_CONTEXT>`	Kubernetes context (defaults to the one sync remembered).

InstallCopy Anchor Link

Global flagsCopy Anchor Link

CommandsCopy Anchor Link

DeployCopy Anchor Link

alien-deploy deployCopy Anchor Link

alien-deploy statusCopy Anchor Link

alien-deploy listCopy Anchor Link

alien-deploy destroyCopy Anchor Link

Existing infrastructureCopy Anchor Link

alien-deploy registerCopy Anchor Link

Operator serviceCopy Anchor Link

alien-deploy operatorCopy Anchor Link

alien-deploy operator installCopy Anchor Link

alien-deploy operator startCopy Anchor Link

alien-deploy operator stopCopy Anchor Link

alien-deploy operator statusCopy Anchor Link

alien-deploy operator uninstallCopy Anchor Link

MachinesCopy Anchor Link

alien-deploy joinCopy Anchor Link

alien-deploy leaveCopy Anchor Link

Air-gapped sitesCopy Anchor Link

alien-deploy syncCopy Anchor Link

alien-deploy rollbackCopy Anchor Link

On this page

Install

Global flags

Commands

Deploy

`alien-deploy deploy`

`alien-deploy status`

`alien-deploy list`

`alien-deploy destroy`

Existing infrastructure

`alien-deploy register`

Operator service

`alien-deploy operator`

`alien-deploy operator install`

`alien-deploy operator start`

`alien-deploy operator stop`

`alien-deploy operator status`

`alien-deploy operator uninstall`

Machines

`alien-deploy join`

`alien-deploy leave`

Air-gapped sites

`alien-deploy sync`

`alien-deploy rollback`