cloak

cloak

You can use secrets without ever reading them. A secret's plaintext must never enter your context. You only ever work with an opaque handle (a name like openai_api_key).

Commands below use the cloak command. This plugin puts it on the Bash PATH automatically — there is no install step. Just call cloak ....

How the user gives you a secret (they type it in chat)

The user registers a secret by typing, on its own line in the chat box:

secret-set openai_api_key sk-realkey...

A UserPromptSubmit hook intercepts that line before it reaches you: it stores the plaintext and blocks the message, so the raw value never lands in your context or the transcript. You will instead receive a short receipt naming the handle (e.g. "stored handle openai_api_key"). That is expected — just acknowledge it and continue; do not ask the user to repeat the value.

You never need to register secrets yourself, and you must never ask the user to paste a secret as ordinary chat text outside this secret-set line.

How you decide which secret to use (you decide)

List the available handles — this returns names only, never values:

cloak list

Pick the handle whose name fits the task. If the one you need is missing, ask the user to register it with a secret-set <handle> <value> line in chat.

How you use a secret

Two ways, both keep the plaintext out of your context:

1. Inline placeholder — put {{secret:NAME}} where the value goes and run the command through the resolver:

   cloak run -- \
     curl -s -H "Authorization: Bearer {{secret:openai_api_key}}" \
     https://api.openai.com/v1/models
   

2. Environment injection — declare the handle with --secret NAME; it is exposed to the child process as $CLOAK_NAME (uppercased, non-alphanumerics become _):

   cloak run --secret openai_api_key -- \
     bash -c 'curl -s -H "Authorization: Bearer $CLOAK_OPENAI_API_KEY" https://api.openai.com/v1/models'
   

The command's stdout/stderr come back to you redacted — any occurrence of the resolved value (and common encodings of it) is replaced with ***.

Hard rules — do not break these

• Never read the store, e.g. cat/grep/less on the store file, python -c to load it, or base64 -d its contents. (A PreToolUse hook also blocks this.)
• Never print, echo, or log a resolved value. Don't add --debug/-v flags whose purpose is to dump the secret. Don't write it to a file you then read. Don't expand $CLOAK_* outside cloak run.
• Never ask the user to paste a secret as plain chat. The only way in is a secret-set line, which the hook intercepts.
• Treat the handle name as the only secret-related thing you may see or repeat. Handles are inert: knowing a handle grants no access to the value.

Managing handles

• List handle names: cloak list
• Remove a handle: cloak rm openai_api_key
• (Low-level / scriptable) register without the chat hook — plaintext via env or hidden prompt, never via argv: CLOAK_VALUE='...' cloak set openai_api_key

What is safe to do

• Print, log, and commit handles ({{secret:openai_api_key}}) freely.
• Build commands containing placeholders and run them via run.
• Show redacted output to the user.