hf module

Read and write modules on a target. The subject is a module key. list and show take it bare (crm) or vendor-qualified (acme.crm); the writes take a bare key only, because a vendor module is not writable: the server answers 400 INVALID_KEY for a vendor-qualified key on a write.

Verbs

Verb	Subject example	Request
list	none	GET /v1/metadata/-/modules
show <module>	crm	GET /v1/metadata/{moduleKey}
create --branch <b> <module> -f <file>	crm	POST /v1/metadata@{branchId}/{moduleKey}
update --branch <b> <module> -f <file>	crm	PUT /v1/metadata@{branchId}/{moduleKey}
delete --branch <b> <module>	crm	DELETE /v1/metadata@{branchId}/{moduleKey}

Subject

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

Output

Mode	Success	Failure
default	list: a KEY LABEL table, one module per row; 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 module list
hf module show crm
hf module create --branch feat-sales sales -f sales-module.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.