# grove.card()

Show or replace a native command-output card.

## Signature

```ts
grove.card(card: {
  id: string; body: string; title?: string; markdown?: string; to?: string
  actions?: CardAction[]
  menus?: { label: string; items: CardAction[] }[]
}): void
interface CardAction {
  label: string; command: string; args?: string
  style?: 'normal' | 'prominent' | 'destructive'
  closes?: boolean
}
```

## Availability

IRC-bound runtimes with commands.register. An explicit private destination additionally needs server scope and query.open.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `card.id` | Yes | Stable local identifier; trimmed and must be nonempty. Reuse it to replace a card. |
| `card.body` | Yes | Nonempty trimmed plain-text fallback and Copy content, capped at 2,000 characters. |
| `card.title` | No | Single-line heading, capped at 80 characters. |
| `card.markdown` | No | Optional native Markdown presentation, capped at 2,000 characters; body is still required. |
| `card.to` | No | Strict nickname of an existing query, server scope only. Does not select the query. |
| `card.actions` | No | Up to six buttons; default []. |
| `card.menus` | No | Up to three menus, each with label and up to 20 items; default []. |
| `action.label` / `menu.label` | Yes | Visible label, single-line and capped at 80 characters. |
| `action.command` | Yes | Command registered by this same instance, normalized as a slash-command name. |
| `action.args` | No | Argument string, trimmed; default empty. |
| `action.style` | No | normal by default; unknown values fall back to normal. |
| `action.closes` | No | Boolean, default false. Dismiss the card after dispatching the command. |

## Return value

Returns `undefined`; it does not return a card handle.

## Behavior and errors

Without to, routing uses the instance's last command target and the host's available buffer context. Overlapping asynchronous commands can change that last target; this is not a per-invocation routing token. Invalid/empty id or body refuses the card. Actions referring to commands the instance does not own are removed. Empty menus are omitted. Native cards support inline Markdown and simple two-column tables, never raw HTML. Mango adds attribution, Copy, and Close. Up to three cards fit per buffer; older output is evicted. Cards disappear when dismissed or the instance stops.

## Example

```js
grove.commands.register([{ name: 'status', summary: 'Show service status' }])
grove.on('command', event => {
  if (event.command !== 'status') return
  grove.card({
    id: 'service-status', title: 'Service', body: 'Ready',
    actions: [{ label: 'Refresh', command: 'status' }]
  })
})
```

See [grove.dismissCard()](grove-dismiss-card.md).