clover's git

the-knife

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.