boxel-command

Boxel Host Commands

Some Boxel operations only exist inside the host app's prerendered runtime — there's no realm-server HTTP endpoint for them, and they can't be reimplemented in plain Node. The realm server's /_run-command endpoint forwards a job to the prerenderer (a headless Chrome instance that has the full host runtime loaded), executes the named command there, and returns the serialized result. Schema introspection, module evaluation, card instantiation, transpiled-module fetches — all of these go through run-command.

This skill documents how to invoke that flow.

When to use it

• Card type schema lookup. Get the live { attributes, relationships } JSON Schema for a CardDef by introspecting its real class at runtime — not by reading the .gts source.
• Module evaluation. Load a .gts / .ts module in the prerender sandbox to surface broken imports, circular references, or top-level runtime errors before they hit a real consumer.
• Card instantiation. Construct a card instance from a JSON document inside the prerender — exercises the CardDef class against the document shape.
• Anything else exposed at @cardstack/boxel-host/commands/<name>/default. Each module is its own host command.

CLI

boxel run-command <command-specifier> --realm <realm-url> [--input '<json>'] [--json]

• <command-specifier> — the module path of the command (e.g. @cardstack/boxel-host/commands/get-card-type-schema/default).
• --realm — the realm URL the command runs against. Required.
• --input — JSON string passed as the command's input. Optional; some commands take no input. Keys map to the input card's field names. A linksTo field is given the target card's ID string, and a linksToMany field an array of ID strings — the host resolves each ID to the actual card before running the command.
• --json — emit the raw response instead of the formatted summary.

Example

boxel run-command @cardstack/boxel-host/commands/get-card-type-schema/default \
  --realm http://localhost:4201/my-realm/ \
  --input '{"codeRef":{"module":"http://localhost:4201/my-realm/sticky-note","name":"StickyNote"}}'