secrets
ak secrets annotate
Set or clear a stored secret's searchable profile without touching its value.
Use ak secrets annotate to describe a stored secret: what it is for, which
provider, environment and account it belongs to, and the fields that help an
agent choose between candidate credentials. The profile is metadata for
ak secrets search and ak secrets describe;
it is never a value and never an instruction.
Usage
ak secrets annotate <ref> [profile flags] [--backend <backend>]Exactly one ref is required, and at least one profile flag must be passed. A
flag left out keeps what is stored; a flag passed empty (--tag "") clears
that field; a list flag replaces the whole list.
| Flag | Description |
|---|---|
--description <text> | What the secret is for. |
--project <name> | Project the secret belongs to; repeat or comma-separate for several. |
--environment <name> | Environment, for example production or staging. |
--provider <name> | Service the secret is for, for example stripe or openai. |
--account <name> | Account or workspace at the provider. |
--tag <tag> | Tag; repeat or comma-separate for several. |
--kind <kind> | One of api_key, token, password, private_key, certificate, connection_string, webhook_secret, client_secret, other. |
--usage-host <host> | Host the credential is meant for; repeat for several. Routing guidance only. |
--when-to-use <text> | When an agent should pick this credential. |
--when-not-to-use <text> | When an agent must not pick this credential. |
--permission <perm> | What the credential can do at its provider, for example read:orders; repeat for several. Not enforced. |
--sensitivity <level> | normal or high. A label in the sync protocol's words; nothing enforces it. |
--alias <name> | Another name the secret is known by; repeat for several. Search only. |
--owner <text> | Person or team responsible for the credential. |
--expires-at <time> | When the provider-side credential expires: RFC 3339 time or YYYY-MM-DD. |
--rotate-url <url> | https page where the credential is rotated; never opened by ak. |
--backend <backend> | Backend whose index is updated: keychain (default), file or memory. |
Each field written here records origin local, which marks it trusted where
imported text is not. Nothing that grants access reads the profile:
--permission, --usage-host and --when-to-use are guidance, not
restrictions.
Never put a secret value in the profile. The text is checked against the fingerprints of the stored values and of the values this device has released, and refused when it contains one.
The command updates the ref's metadata in ~/.agentkit/secrets/index.json. It
never opens the backend or changes the value.
Output
Human stdout prints one line: annotated <ref> followed by a short summary of
the profile, or (no profile) when every field is now empty.
JSON success uses:
schema_version: 1
kind: secrets.annotate
data: the ref's metadata after the editdata carries ref, createdAt, rotatedAt when set, source when known,
and profile, whose fields each hold {value, origin, by, at}. No value is
included.
Exit behavior
| Exit | Meaning |
|---|---|
0 | Success. |
2 | Invalid flags, arguments or metadata, including no profile flag at all or text that contains a stored or released value. |
3 | Ref not found. |
5 | Index failure, or the release manifests could not be read for the value check. |