skarbiec get

Invocation#

skarbiec get <id|role:<role>> [--field <field> | --revision]

Purpose#

Read one item from the vault that serves this host, or return one exact text field; role:<role> selects the one live item tagged stado:role:<role>.

Required inputs and options#

• Requires an item id or role:<role>. --field selects one exact text field; --revision returns id, item, item_uid and revision without decryption. Without either flag, get returns canonical item JSON. An explicit SKARBIEC_VAULT_FILE selects a local vault. Otherwise a declared secrets.skarbiec.vault_file selects this host's vault; when only secrets.skarbiec.url is declared, every command another product runs against the fleet's vault uses the fleet owner instead: get, list, set-json, status, retag, delete (the owner's trash route), totp-seed-state and grant capability, so a product that runs the CLI stands on any host rather than only on the one holding the vault file. A stado://service/skarbiec?consumer=operator route is resolved by Stado's service directory, not reconstructed from a host name or a copied vault.

Output and state effects#

• Prints the same JSON or exact field text for local and remote vaults. The client neither reads nor writes its leftover default vault copy. skarbiec status identifies the serving vault and, remotely, the declared route and resolved endpoint. Wait progress and dependency failures go to stderr, leaving stdout suitable for credential consumers. The graphical operator API routes to the same owner and shares get/set-json validation with the CLI. Socket failures distinguish writing the request from reading its response, retaining the method, path, destination authority and original I/O cause.

Refusals#

• Missing get or set-json coordinates are local usage refusals with exit 2, before any owner request. A malformed routing declaration names its file and invalid field: the root, secrets and secrets.skarbiec must be objects when present, and a declared vault_file or url must be a non-empty string. Invalid declarations never select another vault. A host that receives a forwarded owner request but itself declares secrets.skarbiec.url refuses it, naming the path and its own route, instead of forwarding it again; the owner must declare its own vault. A forwarded write never waits on the write lock of the host that forwarded it: that lock is taken only around work served from the host's own vault. Every owner-side get failure identifies the serving vault file and requested coordinate, including role resolution, revision lookup, decryption and field selection. Remote failures also identify the declared owner route, resolved endpoint, operation and the owner's cause; an owner release without the item-command API refuses the call instead of opening a leftover client copy. A failed Stado directory resolution retains its exit status and actual stderr in the returned cause, including graphical requests; the client is not told to find a cause only in the server's terminal. The graphical operator API returns the complete cause chain as JSON error, not a dropped connection. Unreadable or malformed vaults retain the parse/read cause. Only an actual missing vault file is reported as uninitialized; permission and I/O failures retain the read operation, vault path and operating-system cause. A missing or ambiguous role is refused without choosing another item. Missing, trashed or undecryptable items retain their cause. --field must name an existing text field: a missing field names available field keys, and a non-text field names its JSON type without exposing values. --field cannot be combined with --revision.

Real fleet qualification#

Real fleet qualification: run node tests/vault/remote_owner.mjs with SKARBIEC naming the candidate executable, SKARBIEC_TEST_SOURCE_REVISION its full source revision, SKARBIEC_TEST_STADO_CONFIG the actual non-owner declaration, and SKARBIEC_TEST_CLIENT_ENDPOINT the real non-owner operator listener. The journey verifies that CLI and listener reach the same serving vault, then checks that a second-forwarded read and write are refused without creating an item. It creates a uniquely named test item on the real owner, reads fields and roles, checks revision and metadata preservation, and verifies graphical API parity. Both CLI and operator API must refuse projecting a recovery-code list as text, name the serving vault and actual field type without leaking the codes, and leave the canonical list readable. It then purges its own item and checks that the client copy stayed untouched. Reports bind source and binary hashes under target/real-tests/remote-owner. No substitute vault or successful dry run qualifies this route.