CLI command
skarbiec field
Change one field of an item, a password or a seed, without reading the whole item out and writing it back with set, or remove an optional field.
Invocation#
printf '%s' '<new value>' | skarbiec field set <id> <field>
skarbiec field unset <id> <field>Purpose#
Change one field of an item, a password or a seed, without reading the whole item out and writing it back with set, or remove an optional field.
Required inputs and options#
- set takes an item id and a field name, and the new value on standard input, never in argv; one trailing line ending, which echo and a heredoc add, is taken off, and nothing else. unset takes an item id and a field name. Which fields an item takes is skarbiec kinds <kind>'s answer. POST /v1/operator/items/field/set takes id, field and value in the body and stores the value as sent; POST /v1/operator/items/field/unset takes id and field.
Output and state effects#
- Writes the item's next revision with the field set or removed, keeping every other field, the context, kind, tags and recipients; the value replaced stays in the item's saved versions (skarbiec history <id>) and is never printed or journalled. Prints ok, item, field, removed, changed and revision; unsetting a field the item does not hold prints changed false and writes nothing. Desktop's Items inspector shows it as Set a field…: the fields the item's kind takes, the value in a secure field, Set the field and Remove this field.
Refusals#
- Each refusal leaves the vault as it was. field reads no flag: one given exits 2 as arguments-flag-unknown, `field takes no --<flag>, so it cannot do what the flag asks`. A verb that is not set or unset, or one not followed by exactly one item and one field, exits 2 as arguments-form-missing, arguments-form-unknown, arguments-missing or arguments-extra under /docs/errors, naming the usage. Standard input that cannot be read to its end, or is not UTF-8 text, is stdin-unread or stdin-not-text, exit 1, observed `nothing was written to <id>`. An empty value is field-empty, exit 1: `setting <field> of <id>: standard input held no value, and an empty field would read as a value nobody gave; observed: nothing was written to <id>; fix: give the value on standard input; skarbiec field unset <id> <field> removes the field`; the route refuses a body with no value, one that is not text or an empty one as field-body-empty, naming POST /v1/operator/items/field/unset. A route body without id or field is refused with status 400 naming the member. A field the kind does not take is field-not-of-kind, exit 1: `changing <field> of <id>: <id> is a <kind>, and a <kind> takes no field <field>; observed: nothing was written to <id>; fix: skarbiec kinds <kind> lists the fields a <kind> takes`; a field named context is refused the same way in every kind, since a grant, a route and the items API read context as the item's context and never as a field. A change after which the item would not pass its kind's schema (a required field removed, such as a login's username, the last of a set the kind needs one of, or a value of a form the field does not hold) is field-payload-invalid, exit 1: `changing <field> of <id>: <id> with that change would not be a <kind> the schema accepts: <what the schema says>; observed: nothing was written to <id>; fix: keep every field a <kind> requires and one of each set it needs one of, and give <field> a value of the form the refusal names; skarbiec kinds <kind> lists the fields a <kind> requires and the sets it needs one of`. An id the vault does not hold, or holds trashed, damaged or sealed to other keys, is refused by the item-open causes, an item this host may not write by the owner-write causes, and a vault that does not open or a write that does not land by the vault-access causes.
- skarbiec.field field-empty — exit 1: setting {field} of {id}; fix: give the value on standard input; skarbiec field unset {id} {field} removes the field
- skarbiec.field field-body-empty — exit 1: setting {field} of {id}; fix: send the new value as the body's value; POST /v1/operator/items/field/unset, as skarbiec field unset {id} {field}, removes the field
- skarbiec.field field-not-of-kind — exit 1: changing {field} of {id}; fix: skarbiec kinds {kind} lists the fields a {kind} takes
- skarbiec.field field-payload-invalid — exit 1: changing {field} of {id}; fix: keep every field a {kind} requires and one of each set it needs one of, and give {field} a value of the form the refusal names; skarbiec kinds {kind} lists the fields a {kind} requires and the sets it needs one of
- skarbiec.item-payload payload-kind-unknown — exit 1: checking a payload written as a {kind}; fix: write it as one of the kinds skarbiec kinds lists, each with the fields it takes
- skarbiec.item-payload payload-kind-missing — exit 1: checking a payload written as a {kind}; fix: add kind to the payload, one of the kinds skarbiec kinds lists
- skarbiec.item-payload payload-not-object — exit 1: checking a payload written as a {kind}; fix: write the payload as one JSON object holding schema skarbiec.item.v2, kind, fields and context, as skarbiec kinds {kind} describes
- skarbiec.item-payload payload-property-unknown — exit 1: checking a payload written as a {kind}; fix: take {property} out of the payload, or move what it says into context
- skarbiec.item-payload payload-schema-wrong — exit 1: checking a payload written as a {kind}; fix: set the payload's schema to skarbiec.item.v2
- skarbiec.item-payload payload-kind-mismatch — exit 1: checking a payload written as a {kind}; fix: make the payload's kind {kind}, or write the item as a {stated} (set --type names the item's kind)
- skarbiec.item-payload payload-fields-not-object — exit 1: checking a payload written as a {kind}; fix: write fields as one object from field name to value; skarbiec kinds {kind} names the fields
- skarbiec.item-payload payload-fields-empty — exit 1: checking a payload written as a {kind}; fix: write at least the fields skarbiec kinds {kind} names as required
- skarbiec.item-payload payload-field-not-of-kind — exit 1: checking a payload written as a {kind}; fix: write the value under one of {takes}, or as a kind that takes {name}; skarbiec kinds {kind} says which are required
- skarbiec.item-payload payload-field-shape — exit 1: checking a payload written as a {kind}; fix: write fields.{name} as {shape}
- skarbiec.item-payload payload-field-required — exit 1: checking a payload written as a {kind}; fix: add fields.{name}; skarbiec kinds {kind} names every field a {kind} requires
- skarbiec.item-payload payload-field-set-missing — exit 1: checking a payload written as a {kind}; fix: add one of {named}
- skarbiec.item-payload payload-field-name-invalid — exit 1: checking a payload written as a {kind}; fix: rename the field to letters, digits, '.', '_' and '-'
- skarbiec.item-payload payload-context-not-object — exit 1: checking a payload written as a {kind}; fix: write context as one JSON object, {} when it says nothing
- skarbiec.item-payload payload-host-account-unnamed — exit 1: checking a payload written as a {kind}; fix: set context.account_ref to the account as <user>@<host>
- skarbiec.item-payload payload-card-expiry — exit 1: checking a payload written as a {kind}; fix: write fields.expiry as YYYY-MM, for example 2031-04
- skarbiec.item-payload payload-sso-identity-missing — exit 1: checking a payload written as a {kind}; fix: set context.identity to the id of the identity item it signs in as; skarbiec list --kind identity names them
- skarbiec.item-payload payload-identity-reference-invalid — exit 1: checking a payload written as a {kind}; fix: set context.identity to an identity item's id; skarbiec list --kind identity names them
- skarbiec.item-payload payload-identity-names-identity — exit 1: checking a payload written as a {kind}; fix: take identity out of the identity's context; the logins that sign in as it name it
- skarbiec.item-payload payload-extensions-not-object — exit 1: checking a payload written as a {kind}; fix: write extensions as one JSON object, or leave them out
- skarbiec.item-payload payload-second-factor-invalid — exit 1: checking a payload written as a {kind}; fix: write context.second_factor as an object of factor (none, totp, push, sms, email or security-key), by (owner or weles) and at (seconds since the Unix epoch), or record it with skarbiec login factor set <id> --factor <factor>
- skarbiec.item-payload payload-verification-invalid — exit 1: checking a payload written as a {kind}; fix: write context.verification as an object of outcome (accepted, rejected or locked), by (owner or weles) and at (seconds since the Unix epoch), and context.enrolled as provider (google), at and an optional run, or record an outcome with skarbiec totp verified <item> --outcome <outcome>
- skarbiec.item-payload payload-field-absent — exit 1: reading the field {name} of a {kind}; fix: name one of the fields it holds, or write {name} with skarbiec field set