CLI Reference

alien init

Add an Alien workspace to an existing repository:

alien init

Choose a small architectural starting point. Inside an existing repository, Alien creates an alien/ directory containing alien.ts, workload code, and its dependencies. Inside an empty directory, Alien initializes the current directory.

Choose the template and destination explicitly for automation or a custom repository layout:

alien init remote-worker-ts packages/private-runtime
cd packages/private-runtime

The interactive catalog is intentionally small: private workers, data connectors, event pipelines, HTTPS services, and minimal TypeScript workers. Complete applications and provider-specific examples remain available in the tutorials, with links to their source on GitHub.

alien dev

Start the local development environment:

alien dev

Provisions all resources locally (embedded SQLite for KV/Queue, filesystem for Storage) and starts your workers as native processes. Hot-reloads on code changes.

Example:

alien dev
# ✓ worker (worker) → http://localhost:3001
# ✓ data (storage) → local filesystem
# ✓ Server → http://localhost:9090

alien serve

Start the standalone manager for production deployments:

alien serve

Starts an HTTP server backed by SQLite. Manages deployments, dispatches commands, collects telemetry, and hosts an embedded artifact registry.

Options:

Flag	Description
`--init`	Generate a starter `alien-manager.toml` config file
`--config <path>`, `-c`	Path to config file (default: `alien-manager.toml`)
`--port <port>`	Override the HTTP server port
`--host <host>`	Override the HTTP server bind address

Example:

# Generate config
alien serve --init

# Start with defaults
alien serve

# Start with custom config
alien serve --config /etc/alien/manager.toml

On first run, generates an admin API key. See Private manager for manager setup instructions.

alien build

Build your stack into deployable output:

alien build --platform <platform>
alien build --platforms <platform1>,<platform2>

Compiles your TypeScript code or container image, packages the outputs where needed, and validates the stack.

Builds are content-hashed — if your code hasn't changed, the build completes instantly by reusing the previous output.

Options:

Flag	Description
`--platform <platform>`, `--platforms`	Target platform(s): `aws`, `gcp`, `azure` (comma-separated for multiple) (required)
`--config <path>`, `-c`	Path to `alien.ts`/`alien.js`/`alien.json` file or directory
`--output-dir <dir>`, `-o`	Output directory for build files
`--targets <targets>`	Target OS/architecture combinations (comma-separated)
`--cache-url <url>`	Cache URL for build caching (e.g., `s3://bucket/path`)
`--json`	Emit structured JSON output

Examples:

alien build --platform aws
alien build --platforms aws,gcp
alien build --platform aws --targets linux-arm64

alien release

Create a new release:

alien release

Builds your code, pushes images to the registry, and creates a release. Active deployments pick up new releases automatically.

Alien rebuilds during release so the release reflects the code you publish. If nothing changed, content-hash deduplication can reuse the previous output. Pushed images are reused when the same image is already in the registry.

Options:

Flag	Description
`--platforms <platforms>`	Comma-separated list of platforms to release (auto-discovers from manager config if not specified)
`--project <name>`	Project name or ID (skips project linking)
`--channel <name>`	Channel to advance (defaults to `production`)
`--prebuilt`	Skip build and push — uses pre-pushed image URIs from `stack.json`
`--no-git`	Skip git metadata collection
`--json`	Emit structured JSON output

Examples:

alien release
alien release --platforms aws,gcp
alien release --prebuilt
alien release --channel staging

alien releases promote

Promote an existing immutable release to a channel without rebuilding it:

alien releases promote <release-id> --channel production

Promotion is concurrency-safe: the CLI reads the channel's current release and the API only moves the channel if it still points there, so a stale promotion cannot overwrite a newer one. Promoting an earlier release is the standard rollback — the same tested artifacts, no rebuild.

Create and inspect channels with:

alien releases create-channel staging
alien releases channels
alien releases delete-channel staging

alien deployments set-channel

Change the channel an unpinned deployment follows:

alien deployments set-channel <deployment-id> staging

If the deployment is pinned, it stays on the pinned release and starts following the new channel only after it is unpinned.

alien onboard

Onboard a new customer and generate a deployment token:

alien onboard <name>

Creates a deployment group and returns a token the customer uses to set up their environment.

Options:

Flag	Description
`--platform <platform>`, `--platforms <platforms>`	Limit the deployment link to selected platforms; defaults to all platforms in the active release
`--input <id=value>`	Provide a non-secret developer stack input
`--secret-input <id=value>`	Provide a secret developer stack input; redacted in output
`--max-deployments <n>`	Maximum deployments allowed for this deployment group
`--json`	Emit structured JSON output

Example:

alien onboard acme-corp \
  --platforms aws \
  --secret-input controlPlaneApiKey=sk_live_...
# Deployment token: ax_dg_abc123...
# Send this to the customer's admin.

If required developer-provided stack inputs are missing, alien onboard validates them and prompts in interactive terminals. Platform-scoped inputs are required only when the selected platforms need them; use --platforms aws to avoid collecting local-only values for an AWS-only link. Deployer-provided inputs are collected later by the deployment portal or project-branded deploy CLI.

alien deploy

Deploy a release to a cloud platform:

alien deploy --name <name> --platform <platform>

Options:

Flag	Description
`--name <name>`	Deployment name for identification (required)
`--platform <platform>`	Target platform: `aws`, `gcp`, `azure` (required)
`--token <token>`	Deployment API key for authentication
`--channel <name>`	Release channel followed by a new deployment (defaults to `production`)
`--no-heartbeat`	Disable heartbeat capability
`--monitoring <mode>`	Telemetry mode: `auto` (default) or `off`
`--network <mode>`	Network mode: `auto` (default), `use-default`, `create`, or `byo`
`--network-cidr <cidr>`	CIDR block for `--network create`
`--availability-zones <n>`	Number of zones for `--network create`
`--vpc-id <id>`	Existing AWS VPC ID for `--network byo`
`--public-subnet-ids <ids>`	Comma-separated AWS public subnet IDs for `--network byo`
`--private-subnet-ids <ids>`	Comma-separated AWS private subnet IDs for `--network byo`
`--security-group-ids <ids>`	Comma-separated AWS security group IDs for `--network byo`
`--network-name <name>`	Existing GCP VPC network name for `--network byo`
`--subnet-name <name>`	Existing GCP subnet name for `--network byo`
`--network-region <region>`	GCP subnet region for `--network byo`
`--vnet-resource-id <id>`	Existing Azure VNet resource ID for `--network byo`
`--public-subnet-name <name>`	Azure public subnet name for `--network byo`
`--private-subnet-name <name>`	Azure private subnet name for `--network byo`

Example:

alien deploy --name acme-production --platform aws
alien deploy --name bear-test --platform aws --channel staging
alien deploy --name acme-production --platform aws --network create --availability-zones 3

Network flags are converted to deployment stack settings. See Networking and Network.

alien deployments ls

List all active deployments:

alien deployments ls

Shows deployment status, platform, current release, and a separate desired release when a rollout has not converged. Use --json for the generated manager API records without interactive prompts.

alien deployments get

Show one deployment, its current and desired releases, stack resources, and timestamped provider observations for container and daemon images:

alien deployments get <name-or-id>
alien deployments get <name-or-id> --json

An observed image is what the provider last reported, not the desired stack configuration. A mismatch is shown as rollout pending; a stale observation is labeled separately.

alien deployments retry, redeploy, and pin

alien deployments retry <name-or-id> [--json]
alien deployments redeploy <name-or-id> [--json]
alien deployments pin <deployment-id> [release-id] [--json]

retry resumes the failed operation toward the existing desired release.
redeploy starts a fresh rollout of the current release and is intended for a running deployment.
pin selects a release explicitly; omit release-id to unpin and return to the current release of the deployment's channel.

All three commands preserve structured API error codes, remediation hints, retryability, and request IDs. --json emits only the API response and does not prompt.

alien releases ls

List releases selected by production, with immutable commit SHA and source ref. Select another channel explicitly, or opt into release history across all channels:

alien releases ls
alien releases ls --channel staging
alien releases ls --all-channels
alien releases ls --json

alien releases get

Show an immutable release and correlate it with deployments that are targeting or already running it:

alien releases get <release-id>
alien releases get <release-id> --json

alien vault

Manage vault secrets for a deployment:

alien vault <action>

See Environment Variables for details on managing secrets across deployments.

Commands for agents and automation

These commands accept stable, machine-readable output. Use --json when another program will read the result; it also disables interactive prompts where supported.

Inspect the current context

alien whoami
alien projects get --json
alien projects capabilities status --json
alien status --json

alien status <deployment-group>/<deployment> returns one deployment. Without a deployment, it lists the linked project.

Wait for a deployment

alien deployments wait acme/production \
  --for ready \
  --timeout 10m \
  --json

--for accepts ready, terminal, or deleted. Use this instead of writing a polling loop around deployments get.

Inspect resources and machines

alien deployments resources acme/production --json
alien deployments machines acme/production --json

resources returns a safe summary without resource configuration or secrets. machines returns the connected machine inventory and network-health observations.

Configure project capabilities

alien projects capabilities enable ai \
  --model byo/claude-opus-5

alien projects capabilities enable encryption
alien projects capabilities status --json

For AI, repeat --model, --required-model, or --provider to configure more than one value.

Create scoped API keys

alien api-keys create --for ai-gateway
alien api-keys create --for encryption-gateway --json
alien api-keys create --for remote-bindings
alien api-keys list --json
alien api-keys revoke <key-id> --yes

The create command prints the secret once. --for selects a least-privileged project role; it accepts ai-gateway, encryption-gateway, deployments, remote-bindings, or read-only.

Find customer environments

alien deployment-groups list --json
alien deployment-groups get org_123 --json
alien deployment-groups list --search acme

get accepts a deployment-group ID, name, or external ID. customers and customer are aliases for deployment-groups.

Print executable gateway requests

alien examples ai-gateway \
  --protocol openai-chat \
  --model byo/claude-opus-5

alien examples ai-gateway --protocol anthropic-messages
alien examples encryption-gateway --operation encrypt
alien examples encryption-gateway --operation decrypt --json

Generated examples use the active Alien environment. Secrets remain environment-variable references. Add --json to receive the service, endpoint, command, and required environment variables as structured data.

Search gateway diagnostics

alien logs --source ai-gateway \
  --status provider-error \
  --provider anthropic \
  --since 24h \
  --json

alien logs --source encryption-gateway \
  --operation decrypt \
  --status failed

AI diagnostics can be filtered by --model and --provider; Encryption diagnostics by --operation. Both accept --deployment-group and the standard log time filters.

Inspect gateway usage

alien usage ai --range 24h
alien usage encryption --range 30d --json

Ranges are 24h, 7d, and 30d. The command reports that usage is unavailable when the project has no metrics source instead of inventing zeroes.

Invoke an operation directly

alien operations list

alien operations invoke \
  --deployment acme/production \
  --operation kubernetes/get-pods \
  --params '{"namespace":"default","maxResults":10}'

Operations use the <plugin>/<operation> form. The command waits for the result, or reports that approval is pending when the selected operation requires it.

CLI Reference

On this page