AI Notice: Most documentation right now was auto-generated by an LLM. Handwritten documentation will be implemented over time on the road to 1.0

Command

A command is a discrete action that can be invoked via:

Keyboard shortcut
Command bar
Context menu
Toolbar button
Programmatically

Signature

interface Command {
    id: string;
    label: string;
    description?: string;
    tooltip?: string;
    icon?: string;
    contextKeys?: CommandContextKey[];
    when?: (ctx: CommandContext) => boolean;
    disabled?: (ctx: CommandContext) => boolean;
    action: (ctx: CommandContext) => void | Promise<void>;
    toastData?: import("phoundry-ui").ToastEntry | ((ctx: CommandContext) => import("phoundry-ui").ToastEntry | null | undefined);
    shortcut?: CommandShortcut;
    defaultPlacements?: CommandPlacement[];
    category?: string;
    searchAliases?: string[];
    children?: Command[];
    renderSnippet?: (ctx: CommandContext) => import("svelte").Snippet;
}

Members

Name	Type	Required	Description
`id`	`string`	yes	Unique command identifier (e.g., ‘core.file.delete’, ‘plugin.terminal.toggle’)
`label`	`string`	yes	Human-readable label
`description`	`string`	no	Optional description for command bar/settings
`tooltip`	`string`	no	Tooltip text shown on hover (defaults to label if not set)
`icon`	`string`	no	Icon for UI display
`contextKeys`	`CommandContextKey[]`	no	Context keys required for this command to be visible. Used for fast pre-filtering before evaluating `when()`. If omitted or contains ‘always’, command is always considered.
`when`	`(ctx: CommandContext) => boolean`	no	Fine-grained visibility check. Only called if contextKeys pass (or are not specified). Return false to hide the command.
`disabled`	`(ctx: CommandContext) => boolean`	no	Whether the command is disabled (visible but not executable). Return true to disable.
`action`	`(ctx: CommandContext) => void \| Promise<void>`	yes	The action to execute
`toastData`	`import("phoundry-ui").ToastEntry \| (ctx: CommandContext) => import("phoundry-ui").ToastEntry \| null \| undefined`	no	Optional toast shown after the action completes successfully (no throw). Static entry or a function of the same context passed to `action`.
`shortcut`	`CommandShortcut`	no	Keyboard shortcut configuration
`defaultPlacements`	`CommandPlacement[]`	no	Where this command appears by default. Users can override these in settings.
`category`	`string`	no	Category for grouping in command bar. E.g., ‘File’, ‘Edit’, ‘View’, ‘Navigation’, ‘Tabs’
`searchAliases`	`string[]`	no	Alternative search terms for command bar fuzzy search
`children`	`Command[]`	no	Child commands for dropdown/submenu patterns. When a command has children, its action typically does nothing and the UI shows a dropdown menu of child commands instead.
`renderSnippet`	`(ctx: CommandContext) => import("svelte").Snippet`	no	Custom render snippet for context menu. When provided, the command renders as a custom menu item instead of a standard action item. Useful for inline controls like ratings.