grove.card()

Show or replace a native command-output card.

Signature

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

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().