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.

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.

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.