Secrets
The secrets namespace manages the credentials your tools use in outgoing HTTPS requests. The CLI can create and rotate secrets, change their allowed hosts and bound tools, seal them, read their audit log, and, for a signed-in person with an approved request, reveal a REVEALABLE value once.
What it's for
- Loading keys without pasting them anywhere. Pass a value as
@fileso it never appears in your shell history or a chat transcript. - Rotating keys from a script or a runbook.
- Auditing who used a secret, from which tool, and against which host.
- Approving reveal requests without opening the browser.
Key concepts
Values go in, never come out
create and rotate take a value. No other command returns it: get and list show the name, mode, allowed hosts, bound tools, version, and (if turned on) the last four characters. The only way to read a value back is an approved reveal, and only for REVEALABLE secrets.
@file values
Like other CLI parameters, --value accepts @path to read the value from a file. Use it for every real key:
autessa secrets rotate --secretId <id> --value @new-key.txt
Delete the file when you're done.
Coding agents can manage secrets but can't read them
A coding agent driving the CLI can create, rotate, and audit secrets you ask it to, and wire them into tools by name. It can't learn a value it wasn't given, because nothing returns one. Reveal is for a person, not an agent: don't approve a reveal request so that an automated process can read the value.
Commands
| Command | What it does | Needs |
|---|---|---|
create | Store a new secret | Any member |
list | List secrets you can use | USE |
get | Show one secret, by --secretId or --name | USE |
update | Change the description, allowed hosts, bound tools, or Show last 4 | MANAGE |
rotate | Replace the value; the version goes up by one | MANAGE |
seal | Make a REVEALABLE secret SEALED, permanently | MANAGE |
delete | Delete the secret and erase its value | MANAGE |
audit | Read the audit log | MANAGE |
reveal-request | Ask to see a REVEALABLE secret's value | REVEAL |
reveal-requests | List your requests (--scope MINE, the default) or ones to decide (--scope TO_APPROVE) | |
reveal-approve | Approve someone else's request | MANAGE |
reveal-deny | Deny a request | MANAGE |
reveal-cancel | Withdraw your own request | Requester |
reveal | View the value of your approved request, once. Only with your own CLI login | Requester |
Each command takes the same fields as the matching Poweruser API endpoint, as --field value flags. Pass arrays as JSON in single quotes.
How to create a secret
autessa secrets create \
--name acme-api-key \
--description "Acme production API key" \
--mode SEALED \
--value @acme-key.txt \
--allowedHosts '["api.acme.com"]' \
--showLast4 true
{
"secretId": "3f6c2a9e-8d41-4b7a-9c0e-5b2f1d7a4e10",
"name": "acme-api-key",
"mode": "SEALED",
"last4": "x9Qa",
"allowedHosts": ["api.acme.com"],
"boundToolIds": [],
"version": 1,
"myPermission": "MANAGE"
}
Then reference it by name from a script tool with secrets.ref("acme-api-key"). See Use a third-party API key from a tool.
How to bind a secret to a tool
autessa secrets update --secretId <secretId> --boundToolIds '["<toolId>"]'
Only the listed tools can then use the secret, and they can use it whoever runs them. Send '[]' to unbind. See Bound tools.
How to rotate a secret
autessa secrets rotate --secretId <secretId> --value @new-key.txt
autessa secrets audit --secretId <secretId> --pageSize 20
Check the audit log for a USE event after the ROTATE event before revoking the old key at the provider.
How to reveal a value
Revealing takes two people and works only on REVEALABLE secrets.
The requester asks:
autessa secrets reveal-request --secretId <secretId> \
--reason "Logging in to the vendor portal to download the Q3 invoices."
Someone else with MANAGE finds and approves it:
autessa secrets reveal-requests --scope TO_APPROVE --status PENDING
autessa secrets reveal-approve --requestId <requestId>
Within 15 minutes, the requester views it, once:
autessa secrets reveal --requestId <requestId>
{
"value": "Wint3r-Harbor-2026!",
"secretName": "vendor-portal-password",
"version": 3
}
The request is then used up. reveal only works when the CLI is signed in with your own login from autessa login. It isn't available to scripts or to the Autessa connector that coding agents use, and API keys, poweruser keys, and other automated credentials are refused with MACHINE_IDENTITY_CANNOT_REVEAL.
How to share a secret
Secrets are shared like any other resource, with the resource type SECRET and the levels USE, REVEAL, and MANAGE. See Sharing and Access.