Command

A command is a named operation a pack declares and the unit of Execute. Its CLI face and its JSON face are the same command under one Policy row, one Binding and one Adapter, so the name you give it holds on every surface a host shows. Give a pack 5 to 12 commands and write each CLI form to the agent-safe rules.

Anatomy#

The wire field verb_key and the manifest map verbs both mean command, since HCP has no separate verb ontology.

The twin face#

transit plan "A" "B" --json

{ "pack_id": "transit", "verb_key": "plan", "args": { "from": "A", "to": "B" } }

Only the Invoker differs, which makes the twin face the command's identity (L2). hcpx exec sends the JSON envelope from the command line for runtime operators and tests, while Skills teach the domain bin. Its k=v pairs after -- become args, and confirm=true or apply=true satisfies the confirm gate.

hcpx exec transit plan --json -- from=A to=B

Naming#

Names are lower-case, dot-separated when a family is useful, and stable.

Dots group names without creating a hierarchy, so mail.list is one command. A pack that needs more than 12 commands is usually two packs.

Each name is identical in every projection, and lint fails on drift:

The CLI face may carry aliases in other languages, declared as manifest metadata and never as separate commands, while the JSON verb_key stays English.

Titles#

A host shows a person each step of a run, and title gives the words: live while the command runs and done once it ran. The pack declares them because a command line shows only flags and ids, and model text uses words the pack never said.

"find": {
  "description": "Mail in the Inbox matching a query or a sender.",
  "cli": ["mail", "find", "--query", "{{q}}", "--from", "{{from}}"],
  "title": {
    "live": ["Searching the Inbox for “{{q}}”", "Searching the Inbox"],
    "done": ["Searched the Inbox for “{{q}}”", "Searched the Inbox for mail from {{from}}", "Searched the Inbox"]
  }
}

Each form is one template or a list tried in order. The first template whose placeholders all have a value wins, so a title never shows an empty slot, and the last one in each list should have no placeholders, so a title always shows. {{name}} is a call argument, and {{result.a.b}} is a field of the JSON result that works only in done, as in "Read {{result.mail.subject}}". Values are flattened to one line and cut to 60 characters, and a list of strings is joined with commas.

The SDK returns the words: commandTitle(pack, verb_key, args) while the command runs and commandTitle(pack, verb_key, args, result) once it has a result, or null when the pack declares no title and the host uses its own. hcpx check reports a title that names an unknown argument, uses a result in live, or has no plain fallback (M026).

RFC 0007 proposes titles and the reference SDK implements them. It asks hosts to show a declared title in place of the command line, keep the exact command one action away, and never replace the title with text the model wrote.

CLI projection#

Every command projects to a CLI form an agent can run safely (Projections):

<bin> <space…> [--flags] [--json]

mail list --folder=inbox --json
mail send --to user@example.com --subject Hello --confirm --json

{ "pack_id": "mail", "verb_key": "mail.list", "args": { "folder": "inbox" } }
{ "pack_id": "mail", "verb_key": "mail.send", "args": { "to": "user@example.com", "subject": "Hello", "confirm": true } }

How cli[] renders#

The runtime substitutes placeholders from args, drops empty ones, and appends the JSON flag.

The first token is the bin, and the arguments go to spawn as an array with no shell in between, so a value with spaces stays one argument. A missing optional value drops its token and the flag right before it, so an empty memo leaves no dangling --memo. Without cli[] the runtime falls back to wrap.argv_template, where {{verb}} expands to the command tail (mail.list becomes list).

The JSON flag#

The runtime appends --json unless the pack or the command selects JSON another way.

The JSON arguments always come last, and hcpx check probes render commands the same way. RFC 0004 proposes the JSON flag and the reference runtime implements it.

Exit codes#

A non-zero exit becomes { "ok": false, "error": <stderr or "exit N"> } on the JSON face.

Agent-safe rules#

What is not a command#

A mega-command such as run or exec -- <argv> forwards arbitrary arguments and behaves as a shell, which Execute does not cover. A PATH wrap over allowedSubcommands is a bootstrap to promote to named commands. "New message arrived" is a Sense trigger such as new_item, while mail.list is a command, and follow stays a read command however often an agent calls it.

Related#

• Execution: the pipeline a command passes
• Wrap a CLI
• Specification: Execute