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.

On this page