hf object

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

Verbs

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

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 the object’s own properties (label, description, guidance, identity, rules). It does not carry objectKey: the key comes from the subject.

Output

Mode	Success	Failure
default	list: a KEY LABEL table whose keys are the module.Object 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 object list crm
hf object show crm.Account
hf object update --branch feat-sales crm.Account -f account.json5

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.