Skip to content
Cortex

Commands and Hotkeys

Declare command palette actions, default hotkeys, and Vim command names through the host registry.

1 min readEdit on GitHub

Commands are declared under contributes.commands and feed the command palette, configurable hotkeys, and Vim command-line names from one entry.

Declare a Command#

ts
contributes: {	commands: [		{			id: "insert-date",			label: "Insert Date",			category: "Daily",			aliases: ["date"],			icon: "calendar",			defaultHotkey: "mod+shift+d",			run: (ctx) => ctx.editor.insertAtCursor(new Date().toISOString().slice(0, 10)),		},	],}

run(ctx, payload) receives the typed plugin context and an optional payload (menu targets). Omit run to resolve commands[id] from load(). The first execution activates the plugin. Commands themselves need no permission; the APIs run calls do (editor:write above).

Command Ids#

Ids are plugin-local. Cortex registers them as <plugin-id>:<command-id>, so insert-date can safely exist in more than one plugin. Inside the plugin, ids are inferred: ctx.commands.execute("insert-date") type-checks, unknown ids do not.

Status bar items (command) and context menu items (command) reference these ids instead of holding callbacks. Use stable ids because users may assign custom hotkeys to them.

Hotkeys#

defaultHotkey is the default only; users rebind it in Settings > Hotkeys and the override wins. Plugin hotkeys are global-scoped. Do not implement a second hotkey system in your plugin.

Vim Names#

Vim command-line names derive from aliases, labels, and ids. Use short aliases for frequent commands and avoid names that collide with native Vim commands.

Execution Guidelines#

  • Keep run small; move heavy work behind load().
  • For longer work, show progress through a view, status bar item, notification, or generated Markdown tab.
  • Rejected promises are reported by the command registry; do not swallow errors silently.

Search docs

Search Cortex documentation pages and headings.