API Reference

Complete API reference for all cmdk-engine exports.

Core (cmdk-engine)

createRegistry()

Creates a command registry — the central store for all commands. Compatible with React's useSyncExternalStore.

const registry = createRegistry()
const unregister = registry.register({ id: 'cmd', label: 'My Command' })
const all = registry.getAll()
unregister() // cleanup

createFuzzySearch()

Built-in lightweight fuzzy search engine. Scores by exact match, prefix, substring, word boundary, and character matching. Under 1 KB.

createKeywordEngine(synonyms, userAliases?)

Creates a keyword engine with bidirectional synonym lookup.

const keywords = createKeywordEngine({
  billing: ['money', 'payment'],
})
const expanded = keywords.expandQuery('money')
// ['money', 'billing']

createAccessFilter(provider, mode?)

Creates a filter function that removes commands the user doesn't have permission to see. Supports "any" (user needs any listed permission) and "all" (user needs every listed permission) modes.

createSimpleAccessProvider(permissions)

Creates an access control provider from an array or Set of permission strings.

createFrecencyEngine(options?)

Creates a frecency ranking engine with exponential decay.

createGroupManager(groups?)

Manages command groups and their priority ordering.

defineConfig(config)

Helper function for type-checked CLI config files.

React (cmdk-engine/react)

<CommandEngineProvider>

Context provider that initializes the engine. Accepts a config prop with synonyms, access control, and engine options.

useCommandPalette()

Main hook returning the full palette state.

const {
  search,          // Current query string
  setSearch,       // Update query
  results,         // ScoredItem[] (filtered, ranked)
  flatResults,     // Same as results (flat list)
  groupedResults,  // GroupedResult[] — results grouped by group
  groups,          // Active CommandGroup[]
  isOpen,          // Palette visibility
  open, close, toggle,
  select,          // Select command (frecency + handler + close)
  recordUsage,     // Record command selection manually
} = useCommandPalette()

useCommandRegister(commands, deps?)

Register commands from a component. Auto-cleans up on unmount. Pass a dependency array to re-register when data changes.

useFrecency()

Direct access to frecency engine: recordUsage, getScore, getRecent, clear.

Adapters

CommandPalette (cmdk-engine/adapters/cmdk)

Pre-wired cmdk component. Sets shouldFilter={false} automatically so cmdk-engine owns all filtering and ranking.

scanRoutes(routes, options?) (cmdk-engine/adapters/react-router)

Scan a React Router route tree and extract CommandItem objects. Reads handle.command metadata from route definitions.

const commands = scanRoutes(routeConfig, {
  exclude: ['/admin/*', /^\/debug\//, '/internal'],
  noDefaultExclude: false,  // skip default auth/error exclusion
  includeDynamic: false,    // include :id routes
})

By default, the scanner excludes auth routes (/login, /signup, etc.), error pages (/404, /500), and dynamic routes (:id segments). Exclude patterns support exact strings, globs (/admin/*), and RegExp.

Provider Config

onSelect

Centralized handler called when any command is selected. Replaces per-component onSelect props.

<CommandEngineProvider config={{
  onSelect: (item) => {
    if (item.href) navigate(item.href)
    if (item.action) item.action(item)
  },
}}>

frecency.showRecent

Show a "Recent" group at the top when search is empty.

<CommandEngineProvider config={{
  frecency: {
    showRecent: true,
    recentCount: 5,
    recentLabel: 'Recent',
  },
}}>