CLI Reference

The Alchemy CLI manages the lifecycle of your stacks. Every command operates on an alchemy.run.ts file (or a custom entrypoint) and targets a stage — an isolated environment like dev_sam, prod, or pr-42.

alchemy <command> [file] [options]

If no file is specified, the CLI looks for alchemy.run.ts in the current directory.

Common options

These options are shared across most commands:

Option	Description
--stage <name>	Stage to target. Defaults to dev_$USER (e.g. dev_sam). Must match [a-z0-9][-_a-z0-9]*.
--env-file <path>	Load environment variables from a file before running.

deploy

Compute a plan, ask for approval, and create/update/delete resources to match the desired state.

alchemy deploy [file] [options]

Plan: 2 to create

+ Bucket (Cloudflare.R2Bucket)
+ Worker (Cloudflare.Worker) (1 bindings)
  + Bucket

Proceed?
◉ Yes ○ No
✓ Bucket (Cloudflare.R2Bucket) created
✓ Worker (Cloudflare.Worker) created
  • Uploading worker (14.20 KB) ...
  • Enabling workers.dev subdomain...
{
  url: "https://myapp-worker-dev-you-abc123.workers.dev",
}

On subsequent deploys, only changed resources are updated:

Plan: 1 to update

~ Worker (Cloudflare.Worker)

Proceed?
◉ Yes ○ No
✓ Worker (Cloudflare.Worker) updated
  • Uploading worker (15.10 KB) ...
{
  url: "https://myapp-worker-dev-you-abc123.workers.dev",
}

Option	Description
--stage <name>	Stage to deploy to (defaults to dev_$USER)
--yes	Skip the approval prompt
--dry-run	Show the plan without applying (same as alchemy plan)
--force	Force updates for resources that would otherwise no-op
--env-file <path>	Load environment variables from a file

# Deploy to production, skip the prompt
alchemy deploy --stage prod --yes

# Deploy a different stack file
alchemy deploy stacks/github.ts

# Preview what would change
alchemy deploy --dry-run

plan

Preview what would change without applying anything. Equivalent to alchemy deploy --dry-run.

alchemy plan [file] [options]

Plan: 1 to create, 1 to update

+ Queue (AWS.SQS.Queue)
~ Worker (Cloudflare.Worker)

The plan uses + for creates, ~ for updates, - for deletes, and • for no-ops. No approval prompt is shown and no changes are made.

Option	Description
--stage <name>	Stage to plan against (defaults to dev_$USER)
--env-file <path>	Load environment variables from a file

destroy

Delete every resource in a stack. Computes a plan where all existing resources are marked for deletion, asks for approval, and removes them in dependency order.

alchemy destroy [file] [options]

Plan: 2 to delete

- Worker (Cloudflare.Worker)
- Bucket (Cloudflare.R2Bucket)

Proceed?
◉ Yes ○ No
✗ Worker (Cloudflare.Worker) deleted
✗ Bucket (Cloudflare.R2Bucket) deleted

Option	Description
--stage <name>	Stage to destroy (defaults to dev_$USER)
--yes	Skip the approval prompt
--dry-run	Show what would be deleted without actually deleting
--env-file <path>	Load environment variables from a file

# Destroy a PR preview environment
alchemy destroy --stage pr-42 --yes

dev

Run your stack in development mode with hot reloading.

alchemy dev [file] [options]

Resources are deployed to the cloud while Workers run locally in workerd. File changes trigger automatic rebuilds and hot reloads.

Option	Description
--stage <name>	Stage to use for dev (defaults to dev_$USER)
--env-file <path>	Load environment variables from a file

# Start dev mode
alchemy dev

# Use a custom stage
alchemy dev --stage dev

tail

Stream live logs from deployed resources in real time.

alchemy tail [file] [options]

Tailing: Worker, Api

2026-04-15 14:32:01.123 PST [Worker] GET /hello.txt 200
2026-04-15 14:32:01.456 PST [Worker] PUT /world.txt 201
2026-04-15 14:32:02.789 PST [Api] POST /api/data 200

Logs from multiple resources are interleaved and color-coded by resource. The command streams indefinitely until you interrupt it with Ctrl+C.

Option	Description
--stage <name>	Stage to tail (defaults to dev_$USER)
--filter <ids>	Comma-separated logical resource IDs to include (e.g. Worker,Api)
--env-file <path>	Load environment variables from a file

# Tail only the Worker resource
alchemy tail --filter Worker

# Tail a specific stage
alchemy tail --stage prod

logs

Fetch historical logs from deployed resources.

alchemy logs [file] [options]

Unlike tail, logs fetches a batch of past log entries and exits.

Option	Description
--stage <name>	Stage to fetch logs from (defaults to dev_$USER)
--filter <ids>	Comma-separated logical resource IDs to include
--limit <n>	Number of log entries to fetch (default: 100)
--since <time>	Fetch logs since this time — a duration (1h, 30m, 2d) or ISO date
--env-file <path>	Load environment variables from a file

# Last 50 log entries from all resources
alchemy logs --limit 50

# Logs from the last hour, Worker only
alchemy logs --filter Worker --since 1h

# Logs from a specific stage since a date
alchemy logs --stage prod --since 2026-04-01T00:00:00Z

bootstrap

Set up the AWS assets bucket required for deploying Lambda functions and other AWS resources that need artifact storage.

alchemy bootstrap [options]

Option	Description
--profile <name>	AWS profile to use for credentials (default: default)
--region <region>	AWS region to bootstrap (defaults to AWS_REGION env var)
--destroy	Destroy all bootstrap buckets in the selected region
--env-file <path>	Load environment variables from a file

# Bootstrap with the default profile
alchemy bootstrap

# Bootstrap a specific region and profile
alchemy bootstrap --profile prod --region us-west-2

# Remove bootstrap resources
alchemy bootstrap --destroy

Stages

Every command targets a stage — an isolated instance of your stack. The stage defaults to dev_$USER (e.g. dev_sam), so each developer gets their own environment automatically.

alchemy deploy --stage prod
alchemy deploy --stage pr-42
alchemy destroy --stage dev_sam

Resources are namespaced by stage. Physical names include the stage (e.g. myapp-prod-bucket-abc123), so environments never interfere with each other.