Commands and Hotkeys
Declare command palette actions, default hotkeys, and Vim command names through the host registry.
Commands are declared under contributes.commands and feed the command palette, configurable
hotkeys, and Vim command-line names from one entry.
Declare a Command#
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
runsmall; move heavy work behindload(). - 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.