Manage secrets

A secret is a key or a token that the keep adds to the requests of one destination. Each lives in a file of its own in ~/.local/share/sandcastle/secrets, which only you can read. The value is never written in the configuration: a destination names its secret in destination.secret.

Set a secret

sandcastle secret set notes

At a terminal, it asks for the value without showing it. Otherwise it reads stdin, so the value can come from a password manager:

pass show sandcastle/notes | sandcastle secret set notes

A value is never taken as an argument, where the shell’s history and ps would keep it.

Replace a secret

Set it again. The keep reads a secret for every request, so the new value is used from the next request on, with no restart.

List the secrets

sandcastle secret list

missing  claude
used     notes
unused   old-token

used is named by a destination, unused is named by none, and missing is named but not set. list never opens a secret.

Delete a secret

sandcastle secret rm old-token

It deletes the file without asking. A backup or a copy of the disk may still hold the value, so revoke the key or the token where it was made.

The rules

A name has only a-z, 0-9, - and _, starts with a letter or a digit, and has at most 64 characters.

The keep refuses a secret whose file:

• is a symbolic link, or not a regular file;
• is not yours, or other users have access to it;
• is empty, larger than 16 KiB, or holds a line break before its end or another control character.

sandcastle secret set writes files that keep these rules. When a file breaks one, check names the secret and the rule, and nothing of its content. How the keep holds the secrets is in How secrets are kept.