hf field

Read and write fields on a target. The subject is the dotted key path module.Object.field (crm.Account.name); list takes the object as module.Object, or no subject to list the fields of every object.

Verbs

Verb	Subject example	Request
list <module.Object>	crm.Account	GET /v1/metadata/{moduleKey}/objects/{objectKey}/fields
list	none	GET /v1/metadata/-/fields (every object)
show <module.Object.field>	crm.Account.name	GET /v1/metadata/{moduleKey}/objects/{objectKey}/fields/{fieldKey}
create --branch <b> <module.Object.field> -f <file>	crm.Account.name	POST /v1/metadata@{branchId}/{moduleKey}/objects/{objectKey}/fields/{fieldKey}
update --branch <b> <module.Object.field> -f <file>	crm.Account.name	PUT on the same path
delete --branch <b> <module.Object.field>	crm.Account.name	DELETE on the same path

Subject

On a write, the module part must be a bare module key: vendor modules are not writable, and the server answers 400 INVALID_KEY for a vendor-qualified one.

A dotted key path, split by casing: the object key is the first segment that starts with an uppercase letter, every segment before it is the module key (one segment, or two for a vendor-qualified module), and a field key follows the object key. Each key must pass its metadata key rule (camelCase module, vendor and field keys; PascalCase object keys; letters and digits only). A path of the wrong shape, or with a key outside its rule, fails before any request is sent.

Write flags

Flag	Required on	Meaning
--branch <name>	create, update, delete	The branch the write lands on. main writes in instant mode and also requires admin.metadata.apply; any other name is a cart branch, reviewed and published with hf branch. A name containing / is sent as one path segment.
-f, --file <path>	create, update	A JSON5 file holding the request body.

create fails with 409 METADATA_RESOURCE_EXISTS when the resource already exists on the branch. update and delete fail with 404 when it does not.

Request body

The body is a whole field definition (fieldKind, fieldKey, label, and the properties of its kind). Its fieldKey must equal the subject’s last segment; the server refuses a mismatch.

Output

Mode	Success	Failure
default	list: a KEY LABEL table whose keys are the module.Object.field paths the other verbs take; show: the record as indented JSON; writes: one status: file (branch name) line	on stderr, one hf error: [scope:target] CODE: message line per server error, or hf error: and hf’s own message for a refusal it makes before sending anything; exit 1
--json	the server’s response body, verbatim, on stdout, exit 0	on stderr, exit 1: the server’s {"errors": [...]} envelope, verbatim, or the same envelope from hf for a refusal it makes before sending anything (see below)

In the default mode every string the server sends is printed without control characters, bidirectional controls, line separators or zero-width characters. --json output is not altered.

Refusals hf makes itself

hf checks some input before it sends a request, and refuses it with a registry code, in the same envelope under --json:

Code	Domain	When
INVALID_KEY	data	The subject has the wrong shape (target: path) or a key outside its rule (target: moduleKey, objectKey or fieldKey). Nothing is sent.

Global flags

Every verb accepts --json, -t/--target <name> (run against a stored target other than the current one) and --no-color.

Examples

hf field list crm.Account
hf field show crm.Account.name
hf field delete --branch feat-sales crm.Account.fax

Related

• hf branch: review, plan and publish the branch the writes land on.
• Manage metadata with the hf CLI.
• HTTP API reference: the request and response shapes.