sailfork / t3code-github / .repos/ alchemy-effect/ website/ src/ content/ docs/ environments/ profiles.mdx

A profile is a named bundle of provider authentication settings. The non-secret manifest lives in ~/.alchemy/profiles.json; secret material lives separately under ~/.alchemy/credentials/<profile>/. Profiles let you:

  • Keep work and personal accounts separate
  • Use a different IAM role for prod vs dev
  • Rotate or refresh tokens without losing other configurations

Profiles are independent from Stages. A stage controls what is deployed; a profile controls how alchemy authenticates to deploy it.

Profile selection

Alchemy selects a profile in this order:

  1. The command's --profile <name> option
  2. $ALCHEMY_PROFILE from configuration: an explicit --env-file first, then the process environment, with .env as a fallback when no file is specified
  3. The built-in default profile

Stacks that explicitly declare secret providers pin ALCHEMY_PROFILE to --profile or the process environment, so a secrets provider cannot redirect credential selection. Stacks that omit secrets retain the existing selection above, including injected configuration.

This is the same model as the AWS CLI: a profile named default always exists, cannot be renamed or deleted, and is what every command uses unless you name another profile explicitly. There is no stored "default selection" to switch — to use a different profile, pass --profile or set ALCHEMY_PROFILE.

alchemy profile edit
# connect accounts to the `default` profile

alchemy profile create work
alchemy profile edit --profile work
alchemy deploy --profile work
# uses profile `work`; plain `alchemy deploy` uses `default`

How credentials get there

Run alchemy profile edit, choose providers to add, reconfigure, or remove, then complete each provider's login flow.

To re-run that flow at any time:

# Add, re-configure, or remove accounts in the current profile
alchemy profile edit

# Re-configure one account directly
alchemy profile edit --profile work --reconfigure Cloudflare

# Log into a separate profile
alchemy profile create prod
alchemy profile edit --profile prod

Refreshing credentials is separate from reconfiguration. Refresh preserves the selected authentication method, account, and scopes:

# Refresh every connected provider
alchemy profile refresh

# Refresh only AWS SSO
alchemy profile refresh --profile work --provider AWS

Alchemy refreshes supported credentials lazily. If interaction is required, the command tells you which alchemy profile refresh command to run.

Profile commands include Alchemy's built-in providers even outside a project. They also import alchemy.run.ts, when present, to discover custom providers. Use --config <path> for another entrypoint. A missing conventional alchemy.run.ts is ignored, but errors in an existing entrypoint or an explicit custom path fail the command instead of hiding its providers. Each provider's prompts and credential resolution are implemented by its Auth Provider.

Inspecting a profile

Use alchemy profile show to see what's stored (credentials are redacted):

alchemy profile show
alchemy profile show --profile prod

Sample output:

Profile: work

── AWS ──
  accessKeyId:     ASIA****
  secretAccessKey: Pj5T****
  region:          us-west-2
  source: sso - company

── Cloudflare ──
  accessToken: Xl06****
  expires: in 59m 58s 999ms
  accountId: 123456789...
  source: oauth

Switching profiles

The default profile is your normal local choice. Use --profile for one command, or ALCHEMY_PROFILE for a shell or automation environment:

alchemy profile current

alchemy deploy --stage prod --profile prod
alchemy destroy --stage pr-42 --profile work

export ALCHEMY_PROFILE=work
alchemy deploy

Rename a profile without disconnecting its accounts (the built-in default profile cannot be renamed):

alchemy profile rename work company

This moves the profile's credential directory. It does not rewrite an ALCHEMY_PROFILE environment variable.

Environment variables outside CI

Provider credentials in the environment always win. When every required variable in a provider's contract is set — in the process environment, a .env file, or --env-file — alchemy resolves that provider from the variables and never consults the profile, whether or not --profile or ALCHEMY_PROFILE selected one. It logs which variables it used:

Cloudflare: using environment variables (CLOUDFLARE_API_TOKEN,
CLOUDFLARE_ACCOUNT_ID) instead of the profile.

The decision is per provider, so mixing is fine: a Cloudflare token in .env overrides only Cloudflare, while AWS, Neon, or any other provider in the same run still resolves from the profile. Unset the variables to use the profile's stored credentials for that provider too. A partial set (a required variable missing) is ignored and the profile applies.

CI

CI does not use profiles. When CI=true, provider credentials are resolved directly from environment variables and nothing is read from or written to ~/.alchemy. GitHub Actions sets CI=true automatically:

- run: bun alchemy deploy --stage prod --yes
  env:
    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

CI environment variables by provider

ProviderRequired credentialsOptional configuration
AWSAWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION or AWS_DEFAULT_REGIONAWS_SESSION_TOKEN; AWS_ACCOUNT_ID avoids an STS GetCallerIdentity lookup
CloudflareCLOUDFLARE_ACCOUNT_ID and either CLOUDFLARE_API_TOKEN, or CLOUDFLARE_API_KEY with CLOUDFLARE_EMAIL/CLOUDFLARE_ACCOUNT_EMAILNone
GitHubGITHUB_ACCESS_TOKEN or GITHUB_TOKEN; enterprise hosts may instead use GH_ENTERPRISE_TOKEN or GITHUB_ENTERPRISE_TOKENGITHUB_BASE_URL, GITHUB_API_URL, or GH_HOST selects a GitHub Enterprise host
NeonNEON_API_KEYNone
PlanetScalePLANETSCALE_API_TOKEN_ID, PLANETSCALE_API_TOKEN, PLANETSCALE_ORGANIZATIONPLANETSCALE_API_BASE_URL
PrismaPRISMA_SERVICE_TOKEN or PRISMA_API_TOKENPRISMA_API_URL or PRISMA_MANAGEMENT_API_URL
AxiomAXIOM_TOKEN or AXIOM_API_KEYAXIOM_ORG_ID (required when the token is a personal access token), AXIOM_URL for self-hosted or regional deployments
FlyFLY_API_TOKENFLY_API_HOSTNAME overrides the Machines API root
HetznerHCLOUD_TOKENHCLOUD_ENDPOINT overrides the API base URL
RailwayRAILWAY_API_TOKEN (account or workspace token)RAILWAY_API_URL overrides the GraphQL host
DopplerDOPPLER_TOKEN, or DOPPLER_IDENTITY_ID to log in with the platform's OIDC tokenDOPPLER_OIDC_TOKEN, DOPPLER_OIDC_AUDIENCE — see Doppler
InfisicalINFISICAL_TOKEN, or INFISICAL_IDENTITY_ID to log in with the platform's OIDC tokenINFISICAL_OIDC_TOKEN, INFISICAL_OIDC_AUDIENCE, INFISICAL_API_URL — see Infisical

These variables are a CI credential source, not a profile authentication method. They are never persisted into profiles.json or the credentials directory. Each provider declares machine-readable environment metadata for the variables its CI resolver consumes. See Custom Auth Providers.

Where profiles live

Profile settings live in ~/.alchemy/profiles.json. Credentials live in permission-restricted files under ~/.alchemy/credentials/<profile>/.

Set ALCHEMY_HOME to relocate profile data.

Profile names are portable filesystem-safe identifiers: they must start with a letter or number, may contain letters, numbers, ., _, and -, and may be at most 64 characters.

Use alchemy profile edit instead of editing the manifest manually.

Where next

  • Auth Providers explains lazy credential resolution and refresh.
  • Stages — environment isolation; profiles pick the credentials, stages pick the instance.
  • Secrets & Config — bind env vars and secrets onto your deploy targets.
  • CI explains deployment with environment credentials and no local profile state.
  • CLI lists every profile subcommand and --profile flag.