CLI Reference

alien upgradeCopy Anchor Link

Upgrade the Alien CLI to the latest stable release:

alien upgrade

alien update is an alias. The command verifies standalone downloads before replacing the executable. npm and Homebrew installations are upgraded through their package manager so the CLI does not overwrite package-managed files.

Use alien upgrade --dry-run to check what would happen without making changes, or alien upgrade --force to reinstall the current stable version.

alien loginCopy Anchor Link

Authenticate in the browser and select a default workspace:

alien login

New accounts do not receive an automatically named workspace. Create one explicitly in the dashboard or with alien workspaces create.

To use a manager you run instead of alien.dev, pass its URL and an API key:

alien login --manager https://manager.example.com --token ax_admin_...

Every command then targets that manager until alien logout or the next alien login. In CI, set ALIEN_MANAGER_URL and ALIEN_API_KEY instead. See Self-hosting.

alien workspacesCopy Anchor Link

Create, list, and select workspaces:

alien workspaces create acme-prod
alien workspaces ls
alien workspaces set acme-prod
alien workspaces current

The workspace name is permanent and appears in dashboard URLs and CLI commands. Use 4–100 lowercase letters, numbers, and hyphens.

alien initCopy Anchor Link

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 devCopy Anchor Link

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.

Restarting the command preserves the deployment and local data. Use alien dev destroy --name default when you want to delete them.

Example:

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

alien destroyCopy Anchor Link

Remove a deployment's resources with access to its project and cloud setup credentials:

alien --project my-project destroy --name dep_0123456789012345678901234567 --platform aws

The target can be a deployment ID, <group>/<name>, or a unique name in the selected project. An Alien login can resolve the deployment even if this machine did not install it. Local tracking remains supported.

For deployment-token authentication, supply the deployment's own token. Prefer its immutable deployment ID; a group-qualified name requires the manager to include the parent group name in the authorized deployment response. Deployment tokens cannot list deployments:

alien destroy --name production --platform aws --token "$ALIEN_DEPLOYMENT_TOKEN"

--force forgets the deployment record without removing cloud resources. Use the normal command to finish a deployment in teardown-required status.

alien serveCopy Anchor Link

Run a manager on this machine:

alien serve

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

Options:

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 and prints the alien login command to connect to it. To run a manager in production, see Self-hosting.

alien buildCopy Anchor Link

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:

Examples:

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

alien releaseCopy Anchor Link

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:

Examples:

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

alien releases promoteCopy Anchor Link

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-channelCopy Anchor Link

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 onboardCopy Anchor Link

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:

Example:

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

For Kubernetes, alien onboard prints the helm install command for the customer, pulling the chart from your manager, and a values.yaml for their infrastructure. With --airgapped, it prints the site's token, the key the site verifies updates with, and the alien-deploy sync command that starts the first sync. See Kubernetes.

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 deployCopy Anchor Link

Deploy a release to a cloud platform:

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

Options:

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.

For a public AWS container, configure a customer domain under its resource ID (gateway in this example):

name = "production"
platform = "aws"

[domains.customDomains.gateway]
domain = "api.example.com"

[domains.customDomains.gateway.certificate.aws]
certificateArn = "arn:aws:acm:us-west-2:123456789012:certificate/REPLACE"

Run alien deploy --config deploy.toml. The ACM certificate must be issued, cover the hostname, and belong to the load balancer's AWS account and region. Point your DNS record to the load balancer endpoint reported by the deployment.

The config supplies domains when creating a deployment. Resuming setup with different domain settings fails explicitly; it does not silently change an existing deployment. For CloudFormation setup, use DomainName and CertificateArn. When the stack has multiple public HTTP resources, DomainResource selects which one receives that hostname.

alien deployments lsCopy Anchor Link

List all active deployments:

alien deployments ls

Shows deployment status, platform, current release, and a separate desired release when a rollout has not converged. --json returns deployment records, including workspace, project, and deployment-group identifiers. Local and standalone modes return manager deployment records. JSON output never prompts.

alien deployments getCopy Anchor Link

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 pinCopy Anchor Link

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 lsCopy Anchor Link

List releases that have been selected by production, with immutable commit SHA and source ref. This includes the channel's rollout history, not only its current release. 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 getCopy Anchor Link

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 tokensCopy Anchor Link

Create, list, and revoke scoped tokens on a manager you run:

alien tokens create --tunnel                    # calls tunnels only
alien tokens create --tunnel --customer acme    # only acme's deployments
alien tokens ls
alien tokens revoke <id>

The token is shown once. See Tokens and Tunnels.

alien vaultCopy Anchor Link

Manage vault secrets for a deployment:

alien vault <action>

See Environment Variables for details on managing secrets across deployments.

Commands for agents and automationCopy Anchor Link

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 contextCopy Anchor Link

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 deploymentCopy Anchor Link

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 machinesCopy Anchor Link

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 capabilitiesCopy Anchor Link

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

alien projects capabilities enable encryption

alien projects capabilities enable remote-sandbox \
  --base-image public.ecr.aws/example/analysis:v1 \
  --max-session-lifetime-seconds 3600 \
  --json

alien projects capabilities status --json

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

For remote sandboxes, both --base-image and --max-session-lifetime-seconds are required. Use a public container image and a session limit between 1 and 28800 seconds (8 hours). The CLI validates these flags before looking up your workspace or project. This command configures the project's sandbox capability; it does not start a sandbox session.

Create scoped API keysCopy Anchor Link

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 environmentsCopy Anchor Link

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 requestsCopy Anchor Link

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 diagnosticsCopy Anchor Link

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 usageCopy Anchor Link

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 directlyCopy Anchor Link

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. When the project policy requires approval and you have no approved access request for the operation, the command does not run it and prints how to request access.

Request accessCopy Anchor Link

alien access-requests create \
  --deployment acme/production \
  --operation kubernetes/restart-pod \
  --params '{"namespace":"default","pod":"api-123"}' \
  --duration 1h

alien access-requests create \
  --deployment acme/production \
  --operation 'kubernetes/*' --max-risk read-only --duration 1h

alien access-requests create \
  --deployment acme/production \
  --debug-tool kubectl --debug-namespace my-product --duration 30m

alien access-requests get ar_123
alien access-requests wait ar_123

An access request asks the customer for time-limited access to one operation, to every operation of a plugin up to a risk tier, to a debug session, or to operations and a debug session together. --duration is at most 6h. The customer approves in their environment. No CLI command approves a request.

alien access-requests wait waits up to --timeout seconds (default: 3600).

Only the principal that created a request can use its approval, for alien operations invoke and for alien debug. A user's request does not cover an API key, and an API key's request does not cover a user.

Debug a deploymentCopy Anchor Link

alien debug acme/production --request-access -- kubectl get pods -n my-product
alien debug acme/production --access-request ar_123 -- kubectl get pods -n my-product
alien debug acme/production --access-request ar_123

alien debug runs a local command, or a shell when you give no command, against a deployment. See Remote debugging.

A session ends when its access request expires.

Preview operation permissions offlineCopy Anchor Link

Compile a plugin's metadata.json into the operation grants used during setup:

alien operations permissions ./my-plugin --cloud aws \
  --s3-bucket-arn arn:aws:s3:::customer-data \
  --sqs-queue-arn arn:aws:sqs:us-east-1:123456789012:customer-events \
  --json

alien operations permissions ./my-plugin --cloud gcp \
  --gcs-bucket customer-data --json

alien operations permissions ./my-plugin --cloud kubernetes \
  --permission diagnostics --json

This command needs no login or network connection. Repeat the bucket or queue flags to allow several resources. Missing resource limits, unknown capabilities, and unsupported wildcard grants fail instead of producing broader access.

The JSON result contains plugin, cloud, and permissions. AWS returns IAM statements with their reasons and operation sources. Google Cloud separates project grants from bucket grants and lists the selected buckets. Kubernetes returns RBAC grants; --permission remediation includes supported writes. Setup places these grants in the installation's selected namespace or cluster scope and adds the operator's own permissions, which are not in this output. See Kubernetes permissions.

Custom plugins declare reviewed AWS capabilities by name, such as operations/s3/head-object. Their inline AWS grants are rejected. Use --builtin only when inspecting reviewed built-in source definitions. Azure operation permissions are not supported yet.

Build and publish a custom operations pluginCopy Anchor Link

alien operations init my-plugin
alien operations check ./my-plugin
alien operations test ./my-plugin
alien operations package ./my-plugin
alien operations publish ./my-plugin/my-plugin-0.1.0.zip

init, check, test, docs, and package need no login. cargo may download the plugin's dependencies. See Build a custom plugin.