<tt>kpx</tt> output schemas

kpx supports --format text (default), json and csv for the print, groups, history, otp and --audit commands. The schemas below are stable; new fields may be added, existing fields are not renamed without a major release.

Print (<tt>kpx [options] <database></tt>)

Text

root/
    Internet/
        - Title (username) [url]

--with-passwords adds password: and notes: lines below each entry.

JSON

The print command emits the group tree from Database::ToJson():

{
  "name": "root",
  "groups": [
    {
      "name": "Internet",
      "entries": [
        {"title": "mail", "username": "alice", "url": "https://example.com"}
      ]
    }
  ]
}

Passwords and protected values are omitted from the print JSON. The exact field set is defined by Group::ToJson/Entry::ToJson and covered by the property tests.

CSV

Header: Group,Title,Username,Password,Url,Notes

• Group is the /-joined path including the root group name.
• Password is empty unless --with-passwords is given.
• Fields containing ,, "</tt> or a newline are quoted per RFC 4180 with doubled embedded quotes. @section autotoc_md15 <tt>groups</tt> Text: one group path per line (for example <tt>/root/Internet</tt>). JSON: @icode{json} [{"path": "/root/Internet", "entries": 3, "groups": 1}] @endicode CSV header: <tt>Path,Entries,Groups</tt> @section autotoc_md16 <tt>history</tt> Text: one line per entry with history, followed by its versions. JSON: @icode{json} [{"path": "/root/Internet/mail", "history": [ {"title": "mail", "username": "alice", "modification_time": "2026-01-02T03:04:05Z"} ]}] @endicode CSV header: <tt>Path,Title,Username,ModificationTime</tt> @section autotoc_md17 <tt>otp</tt> Text: <tt>\<path\>: \<seed\> [\<settings\>]</tt>. With <tt>--code</tt>: <tt>\<path\>: \<seed\> [\<settings\>] =\> \<code\> (\<seconds\>s)</tt>. JSON: @icode{json} [{"path": "/root/Internet/mail", "seed": "JBSWY3DPEHPK3PXP", "settings": "30;6", "code": "123456", "remaining": 17}] @endicode CSV header: <tt>Path,Seed,Settings</tt> (without <tt>--code</tt>), otherwise <tt>Path,Seed,Settings,Code,Remaining</tt>. Without <tt>--code</tt> the command displays the stored seed and settings. With <tt>--code</tt> it parses the seed/<tt>otpauth://</tt> URI and emits the current TOTP code plus the seconds until it expires. Entries without a valid TOTP configuration simply omit the <tt>code</tt>/<tt>remaining</tt> members (JSON) or leave the cells empty (CSV). @section autotoc_md18 <tt>--audit</tt> Text: one line per finding, an optional reused-password section with <tt>--with-passwords</tt>, and a summary. JSON: @icode{json} { "audited": 12, "issues": [ {"group": "/root/Internet", "title": "mail", "issues": ["short", "reused"], "password": "..."} ], "reused": [ {"password": "...", "entries": ["/root/Internet/mail"]} ] } @endicode The per-entry <tt>password</tt> field is present only with <tt>--with-passwords</tt>; the reused-password <tt>password</tt> field is <tt>null</tt> without it. CSV header: <tt>Group,Title,Issues,Password</tt> (password column only with <tt>--with-passwords</tt>). @section autotoc_md19 Errors and exit codes Errors go to stderr. With <tt>--format json</tt> they are machine-readable: @icode{json} {"error":{"category":"auth","message":"Invalid password."}} @endicode Categories: <tt>auth</tt>, <tt>format</tt>, <tt>io</tt>, <tt>error</tt>. <table class="markdownTable"> <tr class="markdownTableHead"> <th class="markdownTableHeadNone"> Exit code

Meaning

0

success

1

command/usage error (missing option, unknown group, nothing selected, ...)

3

wrong password or key

4

corrupt or unsupported database

5

I/O error or missing file

Attachments

Print JSON lists attachment names by default:

"attachments": [{"name": "note.txt"}]

With --include-attachments each attachment also carries its payload as base64:

"attachments": [{"name": "note.txt", "data_base64": "aGkh"}]

CSV/text output does not include payloads. Library consumers can use Entry::attachment_names, Entry::FindAttachment and get_binary_property.