boxel-command

---
name: boxel-command
description: Use when running a Boxel host command via the realm server's prerenderer — invoking commands like `get-card-type-schema`, `evaluate-module`, `instantiate-card`, or any other module exposed at `@cardstack/boxel-host/commands/.../default`. Documents `boxel run-command` and the matching `client.runCommand()` method.
---

# 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"}}'
```

A command whose input has a `linksTo(CardDef)` field (here named `card`) takes that card's ID string:

```
boxel run-command @cardstack/boxel-host/commands/capture-card/default \
  --realm http://localhost:4201/my-realm/ \
  --input '{"card":"http://localhost:4201/my-realm/Author/1","format":"isolated"}'
```

The same command captures a paged PDF with `"type":"pdf"`; `"media":"print"` lays it out under the card's print CSS (`@page`, `@media print`). The result's `url` serves the document. Add the `download` and `filename=<name>` query params to that URL to fetch it as an attachment under a name you choose:

```
boxel run-command @cardstack/boxel-host/commands/capture-card/default \
  --realm http://localhost:4201/my-realm/ \
  --input '{"card":"http://localhost:4201/my-realm/Author/1","format":"isolated","type":"pdf","media":"print"}'
```

## Programmatic

```ts
import { BoxelCLIClient } from '@cardstack/boxel-cli/api';

let client = new BoxelCLIClient();

let result = await client.runCommand(
  realmServerUrl,
  realmUrl,
  '@cardstack/boxel-host/commands/get-card-type-schema/default',
  { codeRef: { module: '<absolute-module-identifier>', name: 'StickyNote' } },
);
```

Returns `{ status: 'ready' | 'error' | 'unusable', result?: string | null, error?: string | null }`. `result` is the command's serialized output (a JSON string — parse it yourself). `error` is set when `status !== 'ready'`.

## How it works under the hood

`/_run-command` hands the command to the prerenderer (which has the host app, the realm's Loader, the CardAPI, and all field serializers loaded) and answers with the result. The command module is imported in a headless tab, called with the input, and its result is serialized back to the HTTP response.

A command may persist cards. A write it makes is durable by the time the write returns, but it is indexed in the background, so a card the command just created is not immediately visible to search. Read it back with `boxel realm wait-for-ready` first rather than straight after the command returns.

The same applies inside a command: reading a card it just wrote waits for indexing to catch up, and a command invoked through the queue (a webhook delivery, or the bot) holds the worker that indexing needs, so such a read stalls until the job's timeout fails it. A command that has to see its own writes indexed belongs on `/_run-command`, which holds no worker.

Three failure modes you'll see:

- `status: 'unusable'` — the prerender pool is broken (e.g. "No standby page available for prerender"). Not retryable from the caller's side; usually a sign the prerender pool itself is unhealthy.
- `status: 'error'` with `error: "module URL not found"` — the realm's in-memory module map hasn't indexed the file yet. Common right after a `/_atomic` write; caller can retry briefly or use `client.sync(..., { waitForIndex: true })` upstream.
- `status: 'error'` with any other message — the command threw inside the prerender. The `error` is the thrown error's message; the original stack is in the prerender server's logs.

The realm server itself enforces auth (server JWT via `BoxelCLIClient`); the prerender executes with the permissions of the user the command runs as.

## What this skill is **not** for

- **Realm-side HTTP endpoints** (search, file read/write, atomic batches) — those are direct `BoxelCLIClient` methods. See the `boxel-api` skill.
- **Programmatic in-memory validators** (`runLintInMemory`, `runEvaluateInMemory`, `runParseInMemory`, `runInstantiateInMemory`) — those wrap `runCommand` internally but expose a flatter result shape; consumers usually want those, not raw `runCommand`. They live in the software-factory package.
- **Defining new host commands.** That's host-app development (`packages/host/app/commands/`).