1---
2title: Profiles
3description: Use profiles to select cloud accounts and credentials for each environment.
4---
5
6A **profile** is a named bundle of provider authentication settings.
7The non-secret manifest lives in `~/.alchemy/profiles.json`; secret
8material lives separately under `~/.alchemy/credentials/<profile>/`.
9Profiles let you:
10
11- Keep work and personal accounts separate
12- Use a different IAM role for `prod` vs `dev`
13- Rotate or refresh tokens without losing other configurations
14
15Profiles are independent from [Stages](/environments/stages). A stage
16controls **what** is deployed; a profile controls **how alchemy
17authenticates** to deploy it.
18
19## Profile selection
20
21Alchemy selects a profile in this order:
22
231. The command's `--profile <name>` option
242. `$ALCHEMY_PROFILE` from configuration: an explicit `--env-file` first,
25 then the process environment, with `.env` as a fallback when no file is specified
263. The built-in `default` profile
27
28Stacks that explicitly declare [secret providers](/environments/secret-providers)
29pin `ALCHEMY_PROFILE` to `--profile` or the process environment, so a secrets
30provider cannot redirect credential selection. Stacks that omit `secrets`
31retain the existing selection above, including injected configuration.
32
33This is the same model as the AWS CLI: a profile named `default` always
34exists, cannot be renamed or deleted, and is what every command uses unless
35you name another profile explicitly. There is no stored "default selection"
36to switch — to use a different profile, pass `--profile` or set
37`ALCHEMY_PROFILE`.
38
39```sh
40alchemy profile edit
41# connect accounts to the `default` profile
42
43alchemy profile create work
44alchemy profile edit --profile work
45alchemy deploy --profile work
46# uses profile `work`; plain `alchemy deploy` uses `default`
47```
48
49## How credentials get there
50
51Run `alchemy profile edit`, choose providers to add, reconfigure, or remove,
52then complete each provider's login flow.
53
54To re-run that flow at any time:
55
56```sh
57# Add, re-configure, or remove accounts in the current profile
58alchemy profile edit
59
60# Re-configure one account directly
61alchemy profile edit --profile work --reconfigure Cloudflare
62
63# Log into a separate profile
64alchemy profile create prod
65alchemy profile edit --profile prod
66```
67
68Refreshing credentials is separate from reconfiguration. Refresh preserves the
69selected authentication method, account, and scopes:
70
71```sh
72# Refresh every connected provider
73alchemy profile refresh
74
75# Refresh only AWS SSO
76alchemy profile refresh --profile work --provider AWS
77```
78
79Alchemy refreshes supported credentials lazily. If interaction is required,
80the command tells you which `alchemy profile refresh` command to run.
81
82Profile commands include Alchemy's built-in providers even outside a project.
83They also import `alchemy.run.ts`, when present, to discover custom providers.
84Use `--config <path>` for another entrypoint. A missing conventional
85`alchemy.run.ts` is ignored, but errors in an existing entrypoint or an explicit
86custom path fail the command instead of hiding its providers. Each
87provider's prompts and credential resolution are implemented by its
88[Auth Provider](/environments/auth-providers).
89
90## Inspecting a profile
91
92Use `alchemy profile show` to see what's stored (credentials are
93redacted):
94
95```sh
96alchemy profile show
97alchemy profile show --profile prod
98```
99
100Sample output:
101
102```text
103Profile: work
104
105── AWS ──
106 accessKeyId: ASIA****
107 secretAccessKey: Pj5T****
108 region: us-west-2
109 source: sso - company
110
111── Cloudflare ──
112 accessToken: Xl06****
113 expires: in 59m 58s 999ms
114 accountId: 123456789...
115 source: oauth
116```
117
118## Switching profiles
119
120The `default` profile is your normal local choice. Use `--profile` for one
121command, or `ALCHEMY_PROFILE` for a shell or automation environment:
122
123```sh
124alchemy profile current
125
126alchemy deploy --stage prod --profile prod
127alchemy destroy --stage pr-42 --profile work
128
129export ALCHEMY_PROFILE=work
130alchemy deploy
131```
132
133Rename a profile without disconnecting its accounts (the built-in `default`
134profile cannot be renamed):
135
136```sh
137alchemy profile rename work company
138```
139
140This moves the profile's credential directory. It does not rewrite an
141`ALCHEMY_PROFILE` environment variable.
142
143### Environment variables outside CI
144
145Provider credentials in the environment always win. When every required
146variable in a provider's contract is set — in the process environment, a
147`.env` file, or `--env-file` — alchemy resolves that provider from the
148variables and never consults the profile, whether or not `--profile` or
149`ALCHEMY_PROFILE` selected one. It logs which variables it used:
150
151```text
152Cloudflare: using environment variables (CLOUDFLARE_API_TOKEN,
153CLOUDFLARE_ACCOUNT_ID) instead of the profile.
154```
155
156The decision is per provider, so mixing is fine: a Cloudflare token in
157`.env` overrides only Cloudflare, while AWS, Neon, or any other provider in
158the same run still resolves from the profile. Unset the variables to use the
159profile's stored credentials for that provider too. A partial set (a required
160variable missing) is ignored and the profile applies.
161
162### CI
163
164CI does not use profiles. When `CI=true`, provider credentials are resolved
165directly from environment variables and nothing is read from or written to
166`~/.alchemy`. GitHub Actions sets `CI=true` automatically:
167
168```yaml
169- run: bun alchemy deploy --stage prod --yes
170 env:
171 CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
172 CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
173```
174
175### CI environment variables by provider
176
177| Provider | Required credentials | Optional configuration |
178| --- | --- | --- |
179| AWS | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION` or `AWS_DEFAULT_REGION` | `AWS_SESSION_TOKEN`; `AWS_ACCOUNT_ID` avoids an STS `GetCallerIdentity` lookup |
180| Cloudflare | `CLOUDFLARE_ACCOUNT_ID` and either `CLOUDFLARE_API_TOKEN`, or `CLOUDFLARE_API_KEY` with `CLOUDFLARE_EMAIL`/`CLOUDFLARE_ACCOUNT_EMAIL` | None |
181| GitHub | `GITHUB_ACCESS_TOKEN` or `GITHUB_TOKEN`; enterprise hosts may instead use `GH_ENTERPRISE_TOKEN` or `GITHUB_ENTERPRISE_TOKEN` | `GITHUB_BASE_URL`, `GITHUB_API_URL`, or `GH_HOST` selects a GitHub Enterprise host |
182| Neon | `NEON_API_KEY` | None |
183| PlanetScale | `PLANETSCALE_API_TOKEN_ID`, `PLANETSCALE_API_TOKEN`, `PLANETSCALE_ORGANIZATION` | `PLANETSCALE_API_BASE_URL` |
184| Prisma | `PRISMA_SERVICE_TOKEN` or `PRISMA_API_TOKEN` | `PRISMA_API_URL` or `PRISMA_MANAGEMENT_API_URL` |
185| Axiom | `AXIOM_TOKEN` or `AXIOM_API_KEY` | `AXIOM_ORG_ID` (required when the token is a personal access token), `AXIOM_URL` for self-hosted or regional deployments |
186| Fly | `FLY_API_TOKEN` | `FLY_API_HOSTNAME` overrides the Machines API root |
187| Hetzner | `HCLOUD_TOKEN` | `HCLOUD_ENDPOINT` overrides the API base URL |
188| Railway | `RAILWAY_API_TOKEN` (account or workspace token) | `RAILWAY_API_URL` overrides the GraphQL host |
189| Doppler | `DOPPLER_TOKEN`, or `DOPPLER_IDENTITY_ID` to log in with the platform's OIDC token | `DOPPLER_OIDC_TOKEN`, `DOPPLER_OIDC_AUDIENCE` — see [Doppler](/environments/doppler) |
190| Infisical | `INFISICAL_TOKEN`, or `INFISICAL_IDENTITY_ID` to log in with the platform's OIDC token | `INFISICAL_OIDC_TOKEN`, `INFISICAL_OIDC_AUDIENCE`, `INFISICAL_API_URL` — see [Infisical](/environments/infisical) |
191
192These variables are a CI credential source, not a profile authentication
193method. They are never persisted into `profiles.json` or the credentials
194directory. Each provider declares machine-readable `environment` metadata for
195the variables its CI resolver consumes. See
196[Custom Auth Providers](/environments/custom-auth-provider).
197
198## Where profiles live
199
200Profile settings live in `~/.alchemy/profiles.json`. Credentials live in
201permission-restricted files under `~/.alchemy/credentials/<profile>/`.
202
203Set `ALCHEMY_HOME` to relocate profile data.
204
205Profile names are portable filesystem-safe identifiers: they must start
206with a letter or number, may contain letters, numbers, `.`, `_`, and
207`-`, and may be at most 64 characters.
208
209Use `alchemy profile edit` instead of editing the manifest manually.
210
211## Where next
212
213- [Auth Providers](/environments/auth-providers) explains lazy credential resolution and refresh.
214- [Stages](/environments/stages) — environment isolation; profiles pick the credentials, stages pick the instance.
215- [Secrets & Config](/environments/secrets) — bind env vars and secrets onto your deploy targets.
216- [CI](/environments/ci) explains deployment with environment credentials and no local profile state.
217- [CLI](/cli) lists every `profile` subcommand and `--profile` flag.