himitsu-prompter(5)

🌸 NAME 🌸

himitsu-prompter — the protocol used for the himitsu(7) prompter, and bestie this is the himitsu-prompter(5) File Formats Manual page. It’s giving secure little group-chat energy between the daemon and your prompter UI. ✨

🫶 DESCRIPTION 🫶

Okay so himitsud(1) will invoke the user-configured prompter program in order to interactively obtain information from the user, such as the password to unlock the keyring, or consent to the use of a secret key. The prompter may use whatever means is appropriate to the host environment to obtain this information, such as using a system-specific UI toolkit. Slay. 💅

The prompter is executed by himitsud(1) and communicates with the daemon over the stdin and stdout file descriptors. The protocol is a series of line-oriented commands and replies encoded as UTF-8 text with LF terminators. Commands are sent from the daemon to the prompter via stdin and the prompter writes replies to stdout. No cap. 🫶

Both commands and replies have the same semantic structure. Each begins with a command word (an alphanumeric string) which defines the operation requested. There may or may not be additional arguments provided. If there are no additional arguments the command word is immediately followed by LF. Otherwise, following the command word is a space, then a sequence of arbitrary printable UTF-8 characters until the line terminator is reached. The structure of the argument string depends on the command word. Iconic protocol design honestly. 🎀

In this document, examples are provided with the convention that => indicates messages from the daemon to the prompter via stdin, and <= vice-versa via stdout. Iykyk. 👑

---

🎀 HANDSHAKE 🎀

The first message the daemon sends is the version command, which identifies the protocol version in use by the daemon and requests the protocol version in use by the client. The version number follows the word version in the reply, and is a series of three integers separated by dots (.), indicating respectively the major, minor, and patch version of the protocol.

=> version
<= version 1.0.0

The protocol number uses semantic versioning to determine compatibility between different versions of the daemon and prompter. The daemon will determine at its discretion if this protocol version is suitable, and if so, proceed to issue additional commands; if not, it will close stdin and the prompter should exit with status code 1.

🚨 Bestie, if the daemon closes stdin after the version check, that’s your cue: prompter exits with status code 1. Do not linger. 💀

The current protocol number is 0.0.2.

💀 EXIT STATUS 💀

The prompter’s exit status is semantically meaningful. The exit status is interpreted by the daemon as follows:

• 0 — the user consented to the operation
• 1 — the user did not consent to the operation
• 2-126 — reserved for future use
• 127 — an internal error occured with the prompter

🕹️ COMMANDS 🕹️

The following commands are sent from the daemon to the prompter via stdin.

• key key... — Provides a key to the prompter which is related to this transaction, in the format described by KEY FORMAT in himitsu(7).
• query query — Provides a query to the prompter which is related to this transaction, in the format described by QUERY SYNTAX in himitsu(7). A query command preceeds the prompt persist command.
• password correct|incorrect — Provides feedback in response to the password reply sent from the prompter to the daemon. Note that following the password reply from the prompter, there may be a substantial delay while the password is verified. The prompter is encouraged to display some kind of indication to the user that this process is underway. Like a lil spinner or “verifying… bestie hold on” moment. 🌀
• remember session|timeout <value>|skip|refuse — Optional commands to notify the prompter of available options for remembering user consent. The prompter should preselect the first option received and reply with the selected one, after the prompt command. The user consent is remembered for the client requesting it.
  • session: Until the daemon stops.
  • timeout <value>: Until value as seconds have passed or until the session ends, if latter happens earlier.
  • skip: Do not remember for now, but may be asked next time.
  • refuse: Do not remember and do not ask again for current session. In this case, no remember commands will be send during the remaining session for the query or keys in question.
• prompt disclose|delete|persist|update — Sent when the prompter should obtain consent from the user for the desired operation, specified by the given parameter. Preceeding this command will be one or more key commands describing the keys implicated in this operation, in the case of disclose or delete. On persist a query command preceeds.
  • disclose: the specified keys will be disclosed to the client, including secret values.
  • delete: the specified keys will be removed from the key store
  • persist: the user is asked if the specified query should be remembered. If so, future disclosures of secrets that are matched by the query will be allowed without user consent depending on the selected remember option defined at the remember command.
  • update: the user is asked, if the entries provided by key should be updated according to the query provided by update.

Following this command, the daemon will wait for a answer to given remember options and/or close stdin and will wait for the prompter to exit with a meaningful status code as described by EXIT STATUS above.

• unlock — The daemon will send this command when the user must unlock the keyring before proceeding. The keyring may be in one of three states:
  • hard locked: all key/value pairs are encrypted
  • soft locked: only secret values are encrypted
  • unlocked: the keyring is fully unlocked

The keyring is hard locked on startup. In this state, the user cannot perform any queries before entering their password. If the prompter receives an unlock command before any key or prompt commands are sent, the keyring is in this state. The prompter should present the unlock UI and send password commands until the daemon replies with password correct. Following this, the keyring will enter the unlocked state. If no other operations are required, stdin will be closed after password correct is sent. However, if a query is pending, the daemon will continue normally, sending key commands and a prompt command to complete the desired operation.

The soft locked mode is entered after the user’s configured keyring timeout expires. The encryption keys are unloaded from RAM, but the decrypted key/value pairs are kept. Queries which do not request decryption may proceed normally in this state. However, if decryption of secret values is requested, the keyring must be unlocked first. In this state, the daemon will send one or more key commands, followed by the unlock command, followed by the prompt command. The daemon may choose to implement a different unlocking UI in this mode, for instance to allow the user to both unlock and consent in a single UI action.

🫶 In either situation, if the user declines to unlock the keyring, the prompter should exit with status code 1. Respect the no. 💅

• update query — Sends an update request to the prompter. The query contains the changes that will be applied to all entries that follow using the key command.

The query contains all pairs that will be changed in the entries in question. If a pair has a value it will be changed or added. If it doesn’t have a value, it will be removed from the entries. Note that private values won’t be sent to the prompter and will have the placeholder changed.

• version — See HANDSHAKE above.

💌 REPLIES 💌

The following replies are sent from the prompter to the daemon via stdout:

• password password... — The password reply is sent in response to the unlock command after the user provides a suitable password. The daemon will send a password command with feedback on the outcome; see the description of the unlock command for details. The password itself may contain only printable UTF-8 characters.

Note that the password verification process may require several seconds to complete. The prompter implementation is encouraged to provide feedback to the user to indicate that the operation is underway. This is your “bestie I promise it’s working” moment. 😭

• remember session|timeout <value>|skip|refuse — Notifies the server that the user indicated a desire to remember their consent for this operation.
• version major.minor.patch — See HANDSHAKE above.

🌈 EXAMPLES 🌈

Scenario 1: the keyring is hard locked and the daemon wishes to unlock it.

=> version
<= version 0.0.0
=> unlock
<= password hunter3
=> password incorrect
<= password hunter2
=> password correct
(daemon closes stdin)
(prompter exits with status code 0)

Scenario 2: the keyring is unlocked and a client would like to view the user’s secret keys.

=> version
<= version 0.0.0
=> key proto=web host=example.org user=jdoe password!
=> key proto=web host=example.com user=jdoe password!
=> prompt disclose
(daemon closes stdin)

Scenario 3: the keyring is hard locked and a client would like to view the user’s secret keys.

=> version
<= version 0.0.0
=> unlock
<= password hunter1
=> password incorrect
<= password hunter2
=> password correct
=> key proto=web host=example.org user=jdoe password!
=> key proto=web host=example.com user=jdoe password!
=> prompt disclose
(daemon closes stdin)
(prompter exits with status code 0)

Scenario 4: the keyring is unlocked and a client wants to persist a query.

=> version
<= version 0.0.1
=> query proto=web
=> remember session
=> remember timeout 300
=> remember refuse
=> prompt persist
<= remember session
(daemon closes stdin)
(prompter exits with status code0)

Scenario 5: the keyring is unlocked and a client would like to delete the comment and change the values of user and password. Note that when changing a secret key, it will have the placeholder string changed instead of the actual secret.

=> version
<= version 0.0.2
=> update user=johndoe password!=changed comment
=> key proto=web host=example.org user=jdoe password! comment=old
=> prompt update
(daemon closes stdin)

🧚 VERSION CHANGELOG 🧚

• 0.0.1 — Introduces the remember command and the persist option for prompt.
• 0.0.2 — Introduces the update command and the update option for prompt.

👀 SEE ALSO 👀

himitsu(7)

🌟 AUTHORS 🌟

Okay so this whole thing is maintained by Drew DeVault <sir@cmpwn.com> — and before you ask, yes, he's the main character here, but he's lowkey got a whole squad of other contributors helping out 🫶 so it's giving team effort, not solo era.

The up-to-date source code lives at https://git.sr.ht/~sircmpwn/himitsu — bookmark it bestie, that's where the fresh stuff is ✨

Got bugs? Got patches? 👀 You can submit both by email to ~sircmpwn/himitsu-devel@lists.sr.ht — that's the move, fr fr. No cap, they actually want your emails 💖

ngl sending a bug report is basically main character energy — do it, slay, the maintainers will love you for it 💅

---

✨ that's the whole page, bestie ✨ this was himitsu-prompter(5), dated 2026-02-20 — go forth and prompt responsibly 🎀🦋💜