Commands

Blak’s surface area is small. Every command starts with :Blak. Every command with a keymap also shows up in :BlakKeys.

Most Blak management commands also have <leader>l* shortcuts; see Keymaps.

All commands are defined in lua/blak/core/commands.lua.

Core

:Blak

Opens a short overview buffer with the canonical command list. The fastest way to remember what’s wired up without leaving the editor.

:BlakDoctor

Shorthand for :checkhealth blak. Use this when:

• Something feels off after an update.
• An extra reports missing tools.
• You’re about to file an issue — paste the output.

The health checks live in lua/blak/core/health.lua — see the Health checks guide.

:BlakKeys

Opens a scratch buffer listing every keymap registered by Blak core, enabled extras, and user.lua, sorted by key and annotated with mode + description. The “did I bind this myself or did Blak?” question, answered.

:BlakNews

Opens Blak’s release notes (NEWS.md from the repo) in a scratch buffer. Use this after :BlakUpdate to see what changed.

:BlakDocs

Opens the docs site at https://getblak.dev/start/why/ through Neovim’s native vim.ui.open().

:BlakConfig

Opens lua/blak/user.lua directly. If the file does not exist yet, Blak creates it from lua/blak/user.example.lua first, then opens it for editing.

Pickers

:BlakPick {kind}

Entry point for every picker action. The {kind} is one of:

Kind	What
files	Find files in the workspace (default if no arg)
grep	Live grep
buffers	Buffer list
recent	Recently opened files
commands	Ex commands
keymaps	All keymaps
help	Help tags
diagnostics	Workspace diagnostics
lsp_symbols	Document symbols
workspace_symbols	Workspace symbols

These dispatch through lua/blak/providers/picker/, so changing picker.provider in your user.lua swaps the implementation without changing the keymaps. See the Pickers guide.

The old smart kind is still accepted as a compatibility alias for files.

Extras

:BlakExtras [list|enable|disable|sync] [id]

:BlakExtras                       " open the extras UI
:BlakExtras list                  " same UI, explicit
:BlackExtras list                 " alias for :BlakExtras
:BlakExtras enable lang.rust      " turn on the rust extra
:BlakExtras disable lang.rust     " turn it off
:BlakExtras sync                  " run :Lazy sync to install/uninstall plugins

The UI uses x or <CR> to toggle the extra under the cursor, s to sync lazy.nvim, r to refresh, and q to close. State lives in stdpath('state')/blak/extras.json. Enabling applies config to the current session; disabling persists immediately but already-loaded runtime pieces may remain until restart. See the Extras guide for the full list.

Update & rollback

:BlakUpdate

1. Refuses to continue if package.channel changed since the last accepted update or upgrade.
2. Refuses to continue if a pending breaking migration requires :BlakUpgrade.
3. Snapshots lazy-lock.json, lua/blak/user.lua, extras state, migration state, and update state to stdpath('state')/blak/rollbacks/rollback-YYYYMMDD-HHMMSS/.
4. Runs :Lazy update.

The snapshot also runs automatically on any LazyUpdatePre event, so even a bare :Lazy update is protected.

:BlakUpgrade

For intentional bigger moves — channel changes, major-version bumps, and workflow-affecting migrations. It snapshots first, applies pending migrations, accepts the current channel, then runs :Lazy update.

:BlakRollback

1. Finds the most recent rollback snapshot.
2. Restores lazy-lock.json, lua/blak/user.lua, extras state, migration state, and update state.
3. Reloads Blak config and runs :Lazy restore.

Result: every plugin and tracked config file returns to the state it was in before the last update or upgrade. Works offline.

See the Updates & rollback guide for the full machinery.

Tools & parsers

:BlakToolsInstall

Force-installs every Mason tool declared in mason.ensure_installed plus anything contributed by enabled extras. Useful after enabling a new extra, or on a fresh machine. Implementation: lua/blak/core/tools.lua.

:BlakTreesitterInstall

Installs every parser in treesitter.ensure_installed using the nvim-treesitter main branch API. Notifies on completion. Implementation: lua/blak/core/treesitter.lua.

Blak can install tree-sitter-cli through Mason on first launch (it’s in the default Mason set), then this command compiles parsers.

Terminal

:BlakTerminal [cmd]

Toggles the configured terminal provider. Blak uses a bottom split backed by Neovim’s native terminal by default; editor.snacks-terminal retargets the command to Snacks.terminal.toggle().

Without an argument it opens your shell; with an argument it runs that command. The keymap from terminal.toggle_key calls the no-argument form and defaults to <leader>tt.

Formatting

:BlakFormat

Formats the current buffer via Conform, falling back to the LSP based on format.lsp_format (default "fallback").

:BlakFormatToggle[!]

Toggles format-on-save.

• :BlakFormatToggle toggles for the current buffer (vim.b.blak_disable_autoformat).
• :BlakFormatToggle! toggles globally (vim.g.blak_disable_autoformat).

The keymap <leader>uf calls the buffer version. See the Formatting guide.

Splash

:BlakSplash

Plays the black-hole animation in a scratch buffer. Useful for tweaking your terminal’s color rendering — and a fun cold open. See the Splash guide.

Cheat sheet

:Blak                      overview
:BlakDoctor                health checks
:BlakKeys                  registered keymaps
:BlakNews                  release notes
:BlakDocs                  docs site
:BlakConfig                edit lua/blak/user.lua
:BlakPick {kind}           picker entrypoint
:BlakExtras                extras UI
:BlackExtras list          alias for :BlakExtras
:BlakExtras enable {id}    turn on an extra
:BlakExtras disable {id}   turn off an extra
:BlakExtras sync           :Lazy sync after changes
:BlakUpdate                channel-safe update + rollback snapshot
:BlakRollback              restore last rollback snapshot
:BlakUpgrade               migrations + explicit bigger moves
:BlakToolsInstall          install Mason tools
:BlakTreesitterInstall     install parsers
:BlakTerminal [cmd]        configured terminal
:BlakFormat                format current buffer
:BlakFormatToggle[!]       toggle format-on-save
:BlakSplash                preview splash animation