CLI

Alchemy’s CLI provides a convenient way to manage your infrastructure and create new projects.

Embedding Alchemy

Alchemy is designed to be an embeddable library. The alchemy CLI is an optional convenience wrapper around the library.

When you initialize your app, Alchemy will automatically parse CLI arguments:

const app = await alchemy("my-app")

The alchemy CLI passes through these arguments when it invokes your program.

deploy

alchemy deploy [script] [options]

Deploy an Alchemy project by running alchemy deploy.

• script (optional): Path to the entrypoint file. Defaults to ./alchemy.run.ts or ./alchemy.run.js
• --app - (optional) Specify which application to deploy. Defaults to all apps.
• --stage - Specify which stage/environment to target. Defaults to your username ($USER, or $USERNAME on Windows)
• --profile - The Alchemy profile to use for authoriziing requests (default: default)
• --env-file - Path to environment file to load
• --watch - Watch for changes to infrastructure and redeploy automatically (default: false)
• --force - Apply updates to resources even if there are no changes (default: false)
• --adopt - Adopt existing resources that are not yet managed by your Alchemy app (default: false)
• --cwd - Path to the project directory (defaults to current directory)
• --quiet - Suppress Create/Update/Delete messages (default: false)
• -h, --help - Display help for command

Tip

Here are some examples of how to use the deploy command:

# deploy the default stage
alchemy deploy

# specify a stage
alchemy deploy --stage prod

# deploy the default stage
alchemy deploy --profile prod

# adopt existing resources
alchemy deploy --adopt

# use a custom script
alchemy deploy ./my-infra.ts

# use an environment file
alchemy deploy --env-file .env.prod

# watch and deploy changes to the cloud
alchemy deploy --watch

# force update all resources even without changes
alchemy deploy --force

Equivalent Runtime Commands

You can also run the deploy command directly with your preferred JavaScript runtime:

bun

bun ./alchemy.run.ts
bun --watch ./alchemy.run.ts

tsx

tsx ./alchemy.run.ts
tsx --watch ./alchemy.run.ts

node 22+

node ./alchemy.run.ts
node --watch ./alchemy.run.ts

node 20

node --experimental-strip-types ./alchemy.run.ts
node --experimental-strip-types --watch ./alchemy.run.ts

deno

deno run -A ./alchemy.run.ts
deno run -A --watch ./alchemy.run.ts

destroy

alchemy destroy [script] [options]

Destroy all resources in an Alchemy project.

• script (optional): Path to the entrypoint file. Defaults to ./alchemy.run.ts or ./alchemy.run.js
• --app - (optional) Specify which application to deploy. Defaults to all apps.
• --stage - Specify which stage/environment to target. Defaults to your username ($USER, or $USERNAME on Windows)
• --profile - The Alchemy profile to use for authoriziing requests (default: default)
• --cwd - Path to the project directory (defaults to current directory)
• --quiet - Suppress Create/Update/Delete messages (default: false)
• --env-file - Path to environment file to load
• -h, --help - Display help for command

Tip

Here are some examples of how to use the destroy command:

# destroy the default stage
alchemy destroy

# specify a stage
alchemy destroy --stage prod

# use a custom script
alchemy destroy ./my-infra.ts

# use an environment file
alchemy destroy --env-file .env.prod

Equivalent Runtime Commands

You can also run the destroy command directly with your preferred JavaScript runtime:

bun

bun ./alchemy.run.ts --destroy

tsx

tsx ./alchemy.run.ts --destroy

node 22+

node ./alchemy.run.ts --destroy

node 20

node --experimental-strip-types ./alchemy.run.ts --destroy

deno

deno run -A ./alchemy.run.ts --destroy

dev

alchemy dev [script] [options]

Run an Alchemy program in dev-mode with local simulation and hot reloading.

• script (optional): Path to the entrypoint file. Defaults to ./alchemy.run.ts or ./alchemy.run.js
• --app - (optional) Specify which application to deploy. Defaults to all apps.
• --stage - Specify which stage/environment to target. Defaults to your username ($USER, or $USERNAME on Windows)
• --profile - The Alchemy profile to use for authoriziing requests (default: default)
• --env-file - Path to environment file to load
• --force - Apply updates to resources even if there are no changes (default: false)
• --adopt - Adopt existing resources that are not yet managed by your Alchemy app (default: false)
• --cwd - Path to the project directory (defaults to current directory)
• --quiet - Suppress Create/Update/Delete messages (default: false)
• -h, --help - Display help for command

Tip

Here are some examples of how to use the dev command:

# run dev mode with default settings
alchemy dev

# specify a profile
alchemy dev --profile prod

# specify a stage
alchemy dev --stage dev --profile dev

# use a custom script
alchemy dev ./my-infra.ts

# use an environment file
alchemy dev --env-file .env.dev

# force update all resources even without changes
alchemy dev --force

# adopt existing resources
alchemy dev --adopt

Equivalent Runtime Commands

You can also run the dev command directly with your preferred JavaScript runtime:

bun

bun --watch ./alchemy.run.ts --dev

tsx

tsx --watch ./alchemy.run.ts --dev

node 22+

node --watch ./alchemy.run.ts --dev

node 20

node --experimental-strip-types --watch ./alchemy.run.ts --dev

deno

deno run -A --watch ./alchemy.run.ts --dev

run

alchemy run [script] [options]

Run an Alchemy program with read-only access to your infrastructure. No changes will be applied to your resources.

• script (optional): Path to the entrypoint file. Defaults to ./alchemy.run.ts or ./alchemy.run.js
• --app - (optional) Specify which application to deploy. Defaults to all apps.
• --stage - Specify which stage/environment to target. Defaults to your username ($USER, or $USERNAME on Windows)
• --profile - The Alchemy profile to use for authoriziing requests (default: default)
• --env-file - Path to environment file to load
• --watch - Watch for changes to infrastructure and redeploy automatically (default: false)
• --cwd - Path to the project directory (defaults to current directory)
• --quiet - Suppress Create/Update/Delete messages (default: false)
• -h, --help - Display help for command

Tip

Here are some examples of how to use the run command:

# run a script in read-only mode
alchemy run ./scripts/my-script.ts

# watch for changes and re-run
alchemy run ./scripts/my-script.ts --watch

# specify a stage
alchemy run ./scripts/my-script.ts --stage dev

# use an environment file
alchemy run ./scripts/my-script.ts --env-file .env.prod

Equivalent Runtime Commands

You can also run the run command directly with your preferred JavaScript runtime:

bun

bun ./alchemy.run.ts --read
bun --watch ./alchemy.run.ts --read

tsx

tsx ./alchemy.run.ts --read
tsx --watch ./alchemy.run.ts --read

node 22+

node ./alchemy.run.ts --read
node --watch ./alchemy.run.ts --read

node 20

node --experimental-strip-types ./alchemy.run.ts --read
node --experimental-strip-types --watch ./alchemy.run.ts --read

deno

deno run -A ./alchemy.run.ts --read
deno run -A --watch ./alchemy.run.ts --read

create

alchemy create [name] [options]

Create a new Alchemy project from a template.

• name (optional): Project name or path
• --template - Project template type (choices: “typescript”, “vite”, “bun-spa”, “astro”, “react-router”, “sveltekit”, “tanstack-start”, “rwsdk”, “nuxt”)
• --yes - Skip prompts and use defaults (default: false)
• --overwrite - Overwrite existing directory (default: false)
• --install - Install dependencies after scaffolding
• --pm - Package manager to use (choices: “bun”, “npm”, “pnpm”, “yarn”, “deno”)
• --vibe-rules - Setup vibe-rules for the specified editor (choices: “cursor”, “windsurf”, “vscode”, “zed”, “claude-code”, “gemini”, “codex”, “amp”, “clinerules”, “roo”, “unified”)
• -h, --help - Display help for command

Tip

Here are some examples of how to use the create command:

# create a new project interactively
alchemy create my-app

# create with a specific template
alchemy create my-app --template vite

# skip prompts and use defaults
alchemy create my-app --yes

# specify package manager
alchemy create my-app --pm bun

# overwrite existing directory
alchemy create my-app --overwrite

# create without installing dependencies
alchemy create my-app --no-install

init

alchemy init [options]

Initialize Alchemy in an existing project. This command adds Alchemy infrastructure to projects that were created using other tools (like bun init, vite create, npm create astro, etc.).

• --framework - Force a specific framework instead of auto-detection (choices: “typescript”, “vite”, “bun-spa”, “astro”, “react-router”, “sveltekit”, “tanstack-start”, “rwsdk”, “nuxt”, “nextjs”)
• --yes - Skip prompts and use defaults (default: false)
• -h, --help - Display help for command

Tip

Here are some examples of how to use the init command:

# auto-detect framework and initialize interactively
cd my-existing-project
alchemy init

# initialize with a specific framework
alchemy init --framework bun-spa

# skip prompts and use auto-detected framework
alchemy init --yes

The init command will:

• Auto-detect your framework from package.json dependencies
• Create an alchemy.run.ts file with framework-specific configuration
• Add Alchemy scripts to your package.json (deploy, destroy, alchemy:dev)
• Install Alchemy and any required framework adapters as dev dependencies
• Update configuration files as needed (e.g., vite.config.ts, bunfig.toml, etc.)

Note

For BunSPA projects specifically, alchemy init will validate or create a bunfig.toml file with the required env='BUN_PUBLIC_*' configuration.

configure

alchemy configure [options]

Configure the login method for a cloud provider.

• -p, --profile - The profile to configure (default: default)
• -h, --help - Display help for command

login

alchemy login [options]

Login to a configured cloud provider. Run alchemy configure to configure a provider.

• -p, --profile - The profile to login to (default: default)
• -h, --help - Display help for command

logout

alchemy logout [options]

Logout of a configured cloud provider.

• -p, --profile - The profile to logout from (default: default)
• -h, --help - Display help for command

util create-cloudflare-token

alchemy util create-cloudflare-token

A utility for creating Cloudflare tokens.

• -p, --profile - Create a cloudflare token mirroring the oauth scopes in the specified profile
• --god-token - Create a “god token” with full write access to everything in a cloudflare account