custodian records

A record holds field values in one collection of the schema. Each record has an identifier, which create prints and which get, update and delete take. Be signed in first, and have a schema applied.

A field is addressed by its collection and its name, so the same field name in two collections is a distinct field. If you create or update a record and name a field the applied schema does not hold in that collection, the command names both the field and the collection and stops:

The applied schema declares no sensitivity for field "holder_tax_id" in collection "policies". Apply it with `custodian schema apply` or correct the field name.

get and delete do not stop on a field the schema no longer holds: they leave the token in place and carry on, since a record may predate the field being removed from the schema.

custodian records create

custodian records create policies --set policy_number=PY-4471 --set holder_tax_id=@-

--set field=value sets a field, and is repeatable. For anything sensitive, do not put the value on the command line, where it is readable from the process table; read it from standard input or a file instead:

• --set field=@- reads the value from standard input
• --set field=@<path> reads it from a file

For a client_encrypted field, Custodian seals the value on your machine before sending it, so its plaintext never reaches the server. If you pass such a value as a plain argument, it warns:

warning: the value for client_encrypted field "holder_tax_id" was passed as a literal --set argument, which is readable from the process table while the command runs. Prefer --set holder_tax_id=@- (standard input) or --set holder_tax_id=@<path> (a file).

Other options: --parent <id> links this record as a child of another; --external-ref <ref> sets an external reference. On success:

Created record rec_8VN2QJ4KpR in collection policies.

custodian records get

Reads a record and shows, for each field, how it resolved for you:

custodian records get rec_8VN2QJ4KpR --collection policies

policy_number  PY-4471          revealed
holder_tax_id  tok_…            tokenised
premium        ****             masked
notes          —                withheld

The last column is the resolution — how the server resolved the field for the credential you used:

• revealed — the value itself
• tokenised — an opaque token that stands in for the value
• masked — a masked form of the value
• withheld — nothing; you may not read this field

A field you are not permitted to read at all is simply absent from the output — it is never shown blank. Because get shows exactly what the server returned and nothing more, it is a trustworthy check that a field's sensitivity is set the way you intended.

--children includes the one level of child records the read route can expand.

--reveal

--reveal turns the tokens back into values. A tokenised field comes back resolved by the server; a client_encrypted field is unwrapped locally on this machine, which needs an enrolled device:

custodian records get rec_8VN2QJ4KpR --collection policies --reveal

If this machine holds no enrolled device, only the client_encrypted fields cannot be revealed — every other field still is — and Custodian names each one:

holder_tax_id: this machine holds no enrolled device, so this client_encrypted field cannot be revealed. Enrol one with `custodian device enrol`.

--reveal cannot be combined with --json: revealed values are never written to a machine-readable stream. Read them on a terminal, or use custodian exec to pass them to a program.

If the vault's keys have been destroyed, its master key no longer exists, so no client_encrypted value can be decrypted. Revealing one names the destroyed vault as the cause rather than reporting a missing record:

Vault "acme" has had its keys destroyed, so its master key no longer exists and no client_encrypted value in it can be decrypted. This is the destroyed vault, not a missing record; there is no recovery path (`custodian key destroy`).

custodian records update

Changes only the named fields of a record:

custodian records update rec_8VN2QJ4KpR --collection policies --set premium=@-

The --set grammar is the same as create.

custodian records delete

Deletes a record and every descendant. It shows the one level of children it can see, states plainly that the whole tree goes with it, and asks you to confirm:

custodian records delete rec_8VN2QJ4KpR --collection policies

About to delete record rec_8VN2QJ4KpR in collection policies.
  Direct children (one level — the tree may be deeper):
    rec_2Ab…
  Every descendant is tombstoned with it, however deep — this command cannot count them beforehand.
  This destroys the record's field values: the client_encrypted values, and the tokenised and
  masked ones, and the token and blind index that could otherwise confirm what it held. The
  record's own row remains so the audit trail still resolves.

Add the global --yes to skip the confirmation. Deleting a record that was already deleted reports the original time and destroys nothing further.

Every one of these commands accepts --json.