The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 340 lines 14.9 KB
Raw
1 ---
2 title: profile
3 description: Create, refresh, rename, edit, inspect, or delete Alchemy authentication profiles.
4 ---
5
6 import Terminal from "../../../components/Terminal.astro";
7
8 ```sh
9 alchemy profile [subcommand] [options]
10 ```
11
12 Inspect and manage authentication settings in
13 `~/.alchemy/profiles.json` and credentials under
14 `~/.alchemy/credentials/<profile>/`.
15 See [Profiles](/environments/profiles).
16
17 The built-in `default` profile always exists — like the AWS CLI's — so
18 first-time flows never need a create step. It cannot be renamed or deleted,
19 and every command uses it unless another profile is named with `--profile`
20 or `$ALCHEMY_PROFILE`. Profiles are not consulted
21 in CI; there, credentials come from
22 [environment variables](/environments/ci) only.
23
24 ## Interactive terminal dashboard
25
26 ```sh
27 alchemy profile
28 ```
29
30 On a terminal, running `alchemy profile` with no subcommand opens the
31 profile dashboard. It shows profiles as tabs, connected providers, credential
32 status, and keyboard shortcuts for each action.
33
34 <Terminal content={`[c]●[/c] default production
35
36 default · active
37
38 │ Cloudflare oauth ✓ ready
39 │ accessToken: Xl06****
40 │ accountId: 123456789
41 │
42 │ GitHub gh-cli ✓ ready
43 │ token: gho_3S****
44
45 ←/→ switch e edit r refresh n new q quit`} />
46
47 Dashboard actions call the same code as the subcommands below. Use the
48 subcommands in scripts. Esc or Ctrl+C leaves a nested prompt; at the top level,
49 either key exits the dashboard.
50
51 In a non-interactive session (no terminal, CI, coding agents) the
52 dashboard can't open and `alchemy profile` prints the subcommand help
53 instead.
54
55 | Option | Description |
56 | ------------------- | ------------------------------------------------------- |
57 | `--env-file <path>` | Load environment variables from a file |
58 | `--config, -c <file>` | Stack entrypoint used to discover custom auth providers |
59
60 ## profile create
61
62 ```sh
63 alchemy profile create <name>
64 ```
65
66 Explicitly create an empty profile. Profile names are unique; the command
67 fails if the name already exists. You do not need to create `default`.
68
69 ```sh
70 alchemy profile create production
71 alchemy profile edit --profile production
72 ```
73
74 ## profile rename
75
76 ```sh
77 alchemy profile rename <name> [new-name]
78 ```
79
80 Rename a profile and move its stored credentials to the new name. Profiles
81 carry a stable internal id, so renames do not orphan credentials. The command
82 refuses to rename the built-in `default` profile and to overwrite either an
83 existing profile or an existing credential directory. Omit the new name to
84 enter it interactively.
85
86 ```sh
87 # Prompt for the new name
88 alchemy profile rename production
89
90 # Rename directly
91 alchemy profile rename production prod
92 ```
93
94 An `ALCHEMY_PROFILE` environment variable is external configuration and is not
95 rewritten; update it separately if it names the old profile.
96
97 ## profile edit
98
99 ```sh
100 alchemy profile edit [flags]
101 ```
102
103 Without action flags, the command shows connected accounts and opens a menu of
104 available auth providers. Space
105 cycles the highlighted row through its states:
106
107 - **Unconnected** providers toggle between untouched and **add**.
108 - **Connected** providers cycle keep → **re-configure** → **remove**.
109
110 <Terminal content={`◆ Manage accounts in profile 'default'
111 │ ○ AWS
112 │ ✚ Axiom add
113 │ ✎ Cloudflare re-configure (oauth)
114 │ ● GitHub (gh-cli)
115 │ ↑/↓ to navigate • Space: change action • Enter: confirm
116 └`} />
117
118 Enter applies the queued changes in order: each add/re-configure runs the
119 provider's configuration flow (the same flow that connects a provider on
120 first deploy), and each removal asks for confirmation before running the
121 provider's logout.
122
123 The `--add`, `--reconfigure`, and `--remove` flags perform changes directly
124 with no prompts (removals are not re-confirmed). Each flag takes a provider,
125 is repeatable, and you can combine them in one invocation. List each provider
126 only once. Provider matching is case-insensitive. Custom auth
127 providers are discovered from the stack entrypoint just as they are for
128 `show`.
129
130 Adding or reconfiguring a provider normally opens its prompts (or a
131 browser, for OAuth). For scripts and agents, token-shaped methods can be
132 configured entirely from flags: `--method` picks the provider's configure
133 method and repeatable `--set` supplies its fields. Values come in three
134 forms so secrets stay out of shell history: a literal (`name=value`), an
135 environment variable (`name=env:VAR`, resolved from the environment and
136 `--env-file`), or stdin (`name=-`, one field at most). `--method` is
137 required whenever `--set` is used. Browser-OAuth and `gh auth` methods stay
138 interactive-only.
139
140 `--method` is the same `method` value the provider writes to its file under
141 `~/.alchemy/credentials/<profile>/`, and `--set` keys are that file's
142 properties. `stored` is the pasted-credential method every provider shares:
143
144 | Provider | `--method` | `--set` fields |
145 | ----------- | ---------- | -------------------------------------------------------------------- |
146 | AWS | `stored` | `accessKeyId`, `secretAccessKey`, `region`, optional `sessionToken` |
147 | AWS | `sso` | `ssoProfile` (from `~/.aws/config`) |
148 | Axiom | `stored` | `token`, optional `orgId`, `apiBaseUrl` |
149 | Cloudflare | `stored` | `accountId` plus either `apiToken`, or `apiKey` and `email` |
150 | Fly | `stored` | `apiKey`, optional `apiBaseUrl` |
151 | GitHub | `stored` | `token`, optional `baseUrl` |
152 | Hetzner | `stored` | `token`, optional `apiBaseUrl` |
153 | Neon | `stored` | `apiKey` |
154 | Planetscale | `stored` | `tokenId`, `token`, `organization` |
155 | Prisma | `stored` | `serviceToken` |
156 | Railway | `stored` | `token`, optional `apiBaseUrl` |
157 | Railway | `env` | none (reads `RAILWAY_API_TOKEN` on every run) |
158
159 In a non-interactive session (no terminal, CI, coding agents), the menu can't
160 open. The command prints its usage and exits non-zero. Use the action flags.
161
162 | Option | Description |
163 | ------------------------- | ---------------------------------------------------------- |
164 | `--profile <name>` | Profile to manage; defaults to the effective current one |
165 | `--add <provider>` | Connect a provider (repeatable) |
166 | `--reconfigure <provider>` | Re-run a connected provider's configuration (repeatable) |
167 | `--remove <provider>` | Log out a provider and disconnect it (repeatable) |
168 | `--method <name>` | Configure without prompts using this method (requires exactly one `--add`/`--reconfigure`) |
169 | `--set <name>=<value>` | Field for `--method`: literal, `env:VAR`, or `-` for stdin (repeatable) |
170 | `--env-file <path>` | Load environment variables and current-profile selection |
171 | `--config, -c <file>` | Stack entrypoint used to discover custom auth providers |
172
173 ```sh
174 # Manage the current profile interactively
175 alchemy profile edit
176
177 # Manage a named profile interactively
178 alchemy profile edit --profile work
179
180 # Direct, non-interactive-friendly forms
181 alchemy profile edit --add cloudflare
182 alchemy profile edit --profile work --reconfigure cloudflare
183 alchemy profile edit --remove cloudflare
184
185 # Several changes at once
186 alchemy profile edit --remove cloudflare --add github
187
188 # Fully non-interactive: an agent connects Cloudflare with an API token
189 alchemy profile edit --add cloudflare --method stored \
190 --set apiToken=env:CLOUDFLARE_API_TOKEN --set accountId=0123456789abcdef0123456789abcdef
191
192 # Secret via stdin
193 op read op://vault/neon/key | alchemy profile edit --add neon --method stored --set apiKey=-
194 ```
195
196 ## profile refresh
197
198 ```sh
199 alchemy profile refresh [options]
200 ```
201
202 Refresh authentication for every connected provider without changing its
203 configured method, account, or scopes. This runs the provider's login flow:
204 for example, AWS SSO invokes `aws sso login`, while Cloudflare OAuth refreshes
205 its token and falls back to browser authorization when necessary. If the
206 stored scopes no longer match the current OAuth client, unknown scopes are
207 dropped with a warning. The command refreshes the remaining scopes. If no
208 valid scopes remain, it fails with a `--reconfigure` hint.
209
210 Use `--provider` one or more times to refresh only selected providers. Provider
211 names are matched case-insensitively.
212
213 | Option | Description |
214 | --------------------- | ---------------------------------------------------------- |
215 | `--profile <name>` | Profile to refresh; defaults to the effective current one |
216 | `--provider <name>` | Refresh only this connected provider; may be repeated |
217 | `--env-file <path>` | Load environment variables and current-profile selection |
218 | `--config, -c <file>` | Stack entrypoint used to discover custom auth providers |
219
220 ```sh
221 # Refresh every connected provider in the current profile
222 alchemy profile refresh
223
224 # Refresh AWS in a named profile
225 alchemy profile refresh --profile production --provider AWS
226 ```
227
228 ## profile current
229
230 ```sh
231 alchemy profile current [options]
232 ```
233
234 Show the effective profile and why it was selected. The source is either
235 `ALCHEMY_PROFILE` or `built-in default`. In a non-interactive session it
236 prints a single `name (source)` line.
237
238 | Option | Description |
239 | ------------------- | -------------------------------------- |
240 | `--env-file <path>` | Load environment variables from a file |
241
242 ## profile list
243
244 ```sh
245 alchemy profile list [options]
246 ```
247
248 Render configured profiles — `default` first, the rest alphabetical —
249 including the active profile, configured providers, and each provider's
250 authentication method.
251
252 <Terminal content={`╭──────────────────────────────────────────────────────╮
253 │ Profiles (2) │
254 ├──────────────────────────────────────────────────────┤
255 │ Profile Providers Authentication │
256 │ ──────────────────────────────────────────────────── │
257 │ ● default AWS, Cloudflare AWS: sso, CF: oauth │
258 │ production Cloudflare CF: api-token │
259 ╰──────────────────────────────────────────────────────╯`} />
260
261 The active profile is resolved from `ALCHEMY_PROFILE` in the environment or
262 `--env-file`, falling back to the built-in `default`.
263 In a non-interactive session each profile prints as one
264 `* name: Provider (method)` line.
265
266 | Option | Description |
267 | ------------------- | -------------------------------------- |
268 | `--env-file <path>` | Load environment variables from a file |
269
270 ## profile show
271
272 ```sh
273 alchemy profile show [options]
274 ```
275
276 Show a profile's providers as a table with authentication method, credential
277 status, and resolved details. Sensitive credentials remain redacted. Built-in
278 auth providers are always available. Alchemy also attempts to load the stack's
279 auth providers so custom integrations can render their entries.
280
281 <Terminal content={`╭────────────────────────────────────────────────────────────╮
282 │ Profile: default (active) │
283 ├────────────────────────────────────────────────────────────┤
284 │ Provider Method Status Details │
285 │ ────────────────────────────────────────────────────────── │
286 │ AWS sso ready accessKeyId: ASIA**** │
287 │ region: us-west-2 │
288 │ source: sso - default │
289 │ ────────────────────────────────────────────────────────── │
290 │ Cloudflare oauth ready accessToken: Xl06**** │
291 │ accountId: 123456789... │
292 ╰────────────────────────────────────────────────────────────╯`} />
293
294 If the profile doesn't exist, the command fails (non-zero exit) and lists
295 the available profile names. If none exist, it suggests
296 `alchemy profile create <name>`.
297
298 | Option | Description |
299 | ------------------- | --------------------------------------------------------------- |
300 | `--profile <name>` | Profile to inspect; defaults to the effective current one |
301 | `--env-file <path>` | Load environment variables from a file |
302 | `--config, -c <file>` | Stack entrypoint used to discover custom auth providers |
303
304 ```sh
305 # Show the current profile
306 alchemy profile show
307
308 # Show a named profile
309 alchemy profile show --profile prod
310 ```
311
312 ## profile delete
313
314 ```sh
315 alchemy profile delete <name> [options]
316 ```
317
318 Render the profile's redacted credentials, ask for confirmation, then delete
319 the profile from `~/.alchemy/profiles.json` **and** remove its credential
320 directory. The built-in `default` profile cannot be deleted.
321
322 | Argument / option | Description |
323 | ------------------- | ------------------------------------------------------- |
324 | `<name>` | Profile to delete |
325 | `--yes`, `-y` | Skip the confirmation prompt |
326 | `--env-file <path>` | Load environment variables from a file |
327 | `--config, -c <file>` | Stack entrypoint used to discover custom auth providers |
328
329 ```sh
330 # Remove the prod profile and its credentials
331 alchemy profile delete prod
332
333 # Delete without prompting
334 alchemy profile delete prod --yes
335 ```
336
337 ## Where next
338
339 - [Profiles](/environments/profiles) — how profiles isolate credentials across accounts and environments.
340 - [CI](/environments/ci) explains how to use environment credentials without a profile.