alias
ak secrets alias
Point one environment-variable name at whichever stored secret you pick, and switch with one command.
Use ak secrets alias when you keep one secret per account and want a single
logical name, such as CLAUDE_API_KEY, to follow whichever of them
(CLAUDE_API_KEY_1, CLAUDE_API_KEY_2) you choose. Running the group command
itself prints help.
Usage
ak secrets alias <command>The group accepts no positional arguments and has no flags of its own.
How an alias is followed
A ${secret:NAME} reference the inject hook resolves, and the REF of
ak secrets run --env VAR=REF, follow an alias when no secret of that name is
stored.
- A stored ref always wins over an alias of the same name.
- An alias is followed one hop. A target that is itself an alias, or that has no stored value, is refused as a missing secret.
- The target does not have to exist when the alias is set: a missing target is a warning, so an alias can be set up before a sync brings the value in. Until then, a release through the alias is refused as a missing secret.
Grants and audit
An alias grants nothing. The grant, approval and audit checks run against the
ref the alias points at, never the alias name, so grant the target
(ak secrets grant CLAUDE_API_KEY_1 ...). The audit row records the alias as
alias:<NAME>. Switching an alias to a secret the agent holds no grant on files
a request for that secret.
Storage
Aliases hold names only, never a value, and live in
~/.agentkit/secrets/aliases.json on this device. They are not synced: the
vault sync carries the values, and which account a machine uses stays that
machine's choice.
Subcommands
| Command | Outcome | Disk effect |
|---|---|---|
ak secrets alias list | List every alias and the ref it points at. | Read-only. |
ak secrets alias set <NAME> <REF> | Point NAME at REF, replacing any earlier target. | Writes the aliases file. |
ak secrets alias unset <NAME> | Remove NAME; the secret it pointed at is untouched. | Writes the aliases file. |
Output
All three subcommands share one JSON envelope:
schema_version: 1
kind: secrets.alias
data.action: list | set | unset
data.aliases[]: name, ref, updatedAt
data.previous?data.aliases is the whole list for list and the one affected alias for
set and unset. data.previous appears on set when the alias already
pointed somewhere. No value ever appears in the output.
Exit behavior
| Exit | Meaning |
|---|---|
0 | Success. |
2 | Invalid NAME or REF, invalid flags or arguments, or an invalid row in the aliases file. |
3 | unset only: no such alias. |
5 | The aliases file could not be read or written. |