himitsu-ipc(5)

📦
version 0.10 · 3 versions
, in alpine 3.24

🦋 himitsu-ipc(5) — the himitsu IPC protocol, explained by your favorite unix bestie 🦋

okay so this is himitsu-ipc, part of the File Formats Manual section, and it's literally the manual page for the IPC protocol that himitsud(1) speaks 💅

✨ NAME ✨

himitsu-ipc — the IPC protocol implemented by himitsud(1) 🎀

🌸 DESCRIPTION 🌸

okay so bestie, picture this: the Himitsu IPC protocol is a line-oriented text protocol. That means it's all text, one line at a time, using UTF-8 encoding and LF line endings. No cap. 🫶

It gets transmitted over a Unix socket, and that socket lives at $XDG_RUNTIME_DIR/himitsu. Write that down. 📝

Interactions with this interface are command/reply oriented — commands are initiated by the client and replies are sent by the server. And here's the cute part: both commands and replies have the same semantic structure. They each begin with a command word (an alphanumeric string) which defines the operation requested. There may or may not be additional arguments provided. 🔥

So like:

  • if there are no additional arguments, the command word is immediately followed by LF.
  • otherwise, after the command word comes a space, then a sequence of arbitrary printable UTF-8 characters until the line terminator is reached. The structure of that argument string depends on the command word. iykyk 💫
this man page assumes knowledge of the KEY FORMAT and QUERY SYNTAX described in himitsu(7). Also note that commands which accept flags process them in a manner compatible with getopt(3). 💜

and ngl, one thing you need to know before you freak out about slow responses: all commands are subject to a significant delay before the reply while the user is prompted to provide consent or to unlock the keyring. That's not a bug, that's the vibe check. 😭

💖 COMMANDS 💖

The following commands are recognized by the server:

  • add key... — Adds a new key to the key store. The server will send a key reply echoing the new key (without secrets), followed by an end reply. ✨
  • del [-s] query... — Removes keys from the key store which match the provided query. The user will be prompted to consent to this operation. The server will send a key reply for each deleted key (without secrets), followed by an end reply. The option -s will enable the strict query mode. 🗑️
  • persist [-rs] query — Persists a query after user consent for the current connection. Private values that match the given query will be decrypted without user consent, if the store is unlocked. The server will answer with a persist reply.
    • -r <remember options> — as a comma separated list that are send to the prompter. Allowed values are the strings session, skip, refuse, or a timeout in section as an integer. Eg.: "-r session,3600,300,refuse". The first value is the default value and should be preselected by the prompter. See the remember command in himitsu-prompter(5) for a description of the options.
    • -s — will enable the strict query mode.
  • query [-drs] query... — Queries the key store for keys matching the provided query. Matching keys are returned via a series of key replies, terminated with an end reply to signal the end of the list. 🔍
    • -d — the private values will be decrypted after requesting user consent.
    • -r <remember options> — as a comma separated list similar to the same option of the persist command. If the user agrees, the entries matched by given query will be remembered for the current connection.
    • -s — will enable the strict query mode.
  • update [-s] query... — Begins an transaction that will update all keys matching the provided query. The server will answer wit the update reply. Requires a set command next, to complete the update. There must be no other command in between update and set. ⚠️
    • -s — will enable the strict query mode.
  • set query... — set must directly follow the update command. It changes the key/value pairs of the keys that are matched by the update command according to the values provided by the query. If a key/value pair doesn't exist, it will be added. Otherwise the existing key will be updated with the new value. If there is a key without a value, then the matching key/value pair will be removed. 🧚 Updated keys are returned via a series of key replies, terminated with and end reply to signal the end of the list.
  • status — Requests the secret store lock status. Responds with the status reply. 📊
  • lock [-s] — Locks the keyring clearing all entries and removes the secret key from memory. The server will answer with the locked reply. 🔒
    • -s — Soft lock: Only the secret key will be cleared. Entries without their secret values can still be accessed.
  • quit — Requests that the daemon terminate itself. This command is only recognized if himitsud(1) was started with the -D flag. No reply is sent. 💀

🌈 REPLIES 🌈

The following replies are sent to the client:

  • key key... — Provides a single key store entry to the user. 🔑
  • end — Signals the end of a list of key replies. 🏁
  • persist session|timeout <value>|skip|refuse — Returns the selected remember option on persist.
  • locked — Indicates that the lock command was successful. 🎀
  • status unlocked|soft_locked|hard_locked — Current key store status as reply to the status command.
  • update — update command has been received without errors. ✨
  • error message... — Indicates that a requested operation resulted in an error. The message is both human-friendly and consistent, such that it can be displayed to the user or matched against an internal database of semantic error strings in the client. 😭

⭐ EXAMPLE SESSION ⭐

An example session, with <= indicating messages from the server to the client, and => vice-versa. Any of the commands may be separated from their replies by several seconds while the user interacts with the prompter. (remember that delay? yeah. that one.) 🫶

=> query proto=web
<= key proto=web host=a.example.org user=jdoe password!
<= key proto=web host=b.example.org user=jdoe password!
<= key proto=web host=c.example.org user=jdoe password!
<= key proto=web host=d.example.org user=jdoe password!
<= end
=> add proto=web host=e.example.org user=jdoe password!=hunter2
<= key proto=web host=e.example.org user=jdoe password!
<= end
=> query -d proto=web host=e.example.org
=> key proto=web host=e.example.org user=jdoe password!=hunter2
<= end

👑 SEE ALSO 👑

💅 AUTHORS 💅

Maintained by Drew DeVault <sir@cmpwn.com>, who is assisted by other contributors. Up-to-date source code can be found at https://git.sr.ht/~sircmpwn/himitsu, and bugs/patches can be submitted by email to ~sircmpwn/himitsu-devel@lists.sr.ht. 🫡

and that's the whole page bestie, mwah 💋 this was himitsu-ipc(5) from the File Formats Manual, dated 2026-02-20 — go forth and speak fluent himitsu, you're gonna slay 🔥👑

📦 where this page comes from