command.nvim

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 15 Open GitHub ↗

Run commands in a builtin Neovim terminal, follow compilation errors and much more

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# command.nvim

Run shell commands inside Neovim, keep a searchable history, and navigate terminal output without leaving the editor.

`command.nvim` runs commands through `$SHELL -ic` and falls back to `/bin/sh`, so your aliases, functions, and shell startup config are available.

## What It Does

- Open a centered prompt and run any shell command in a Neovim terminal split
- Re-run the last command in the current Neovim session
- Execute the current visual selection as a shell command
- Persist command history across sessions
- Search command history with `fzf-lua`
- Show ghost text suggestions from previous commands while typing
- Expand editor-aware variables like `${filePath}`, `${line}`, `${cwd}`, and `${selection}`
- Choose whether commands run from the current file directory or Neovim's current working directory
- Ask for confirmation before risky commands
- Hide and reopen the last terminal without losing its output
- Jump from terminal output to files and errors
- Send terminal output to quickfix

## Installation

### vim.pack

```lua
vim.pack.add({
  {
    src = 'https://github.com/vieitesss/command.nvim',
    version = vim.version.range('*'), -- latest tagged release
  },
})

require('command').setup()
```

### lazy.nvim

```lua
return {
  'vieitesss/command.nvim',
  lazy = false,
  version = '*',
  opts = {},
}
```

Install `ibhagwan/fzf-lua` if you want history search from the prompt with `<C-f>`.

Use `:checkhealth command.nvim` if you want to verify your shell, history storage, and `fzf-lua` setup.

## Commands

`command.nvim` does not define global keymaps by default. You can use the commands directly:

- `:CommandExecute` opens the prompt and runs a new command
- `:CommandExecuteLast` re-runs the last command after one has already been executed in the current Neovim session
- `:CommandExecuteSelection` runs the current visual selection as a shell command
- `:CommandReopenTerminal` reopens the last hidden terminal window if its buffer is still available
- `:CommandCycleTerminalSide` cycles the terminal split side (`up -> right -> down -> left`) and shows the new side

It also exposes `<Plug>` mappings if you want your own keys:

```lua
vim.keymap.set({ 'n', 'i' }, '<M-;>', '<Plug>(CommandExecute)')
vim.keymap.set({ 'n', 'i' }, '<M-l>', '<Plug>(CommandExecuteLast)')
vim.keymap.set('x', '<M-;>', '<Plug>(CommandExecuteSelection)')
vim.keymap.set('n', '<M-r>', '<Plug>(CommandReopenTerminal)')
vim.keymap.set('n', '<M-s>', '<Plug>(CommandCycleTerminalSide)')
```

## Prompt

The prompt stays a regular Neovim buffer. You can paste multiline commands, use normal-mode edits like `o` and `O`, and the floating window grows with the command up to `ui.prompt.max_height`.

Default prompt keys:

- `<CR>` runs the command. In insert mode, if the command is syntactically incomplete for the current shell, it inserts a newline instead. In normal mode, incomplete commands are not executed and a warning is shown.
- `<Up>` and `<Down>` browse history
- `<C-f>` searches history with `fzf-lua`
- `<C-e>` accepts the ghost text suggestion
- `<C-o>` toggles the execution directory
- `<Esc>` cancels in normal mode

When the command spans multiple lines, the prompt expands to show at least 5 lines when space allows.

The prompt title shows the directory that will be used for execution. `<C-o>` switches between:

- `buffer`: the current file's directory
- `root`: Neovim's current working directory from `:pwd` / `getcwd()`

## Terminal

Default terminal keys:

- `q` hides the terminal
- `Q` closes the terminal and stops its running command
- `<CR>` opens the file or error under the cursor
- `<C-q>` sends the full output to quickfix

`q` hides the window instead of deleting it, so `:CommandReopenTerminal` can bring it back. `Q` closes it permanently and stops any running command. The saved terminal is replaced the next time you run a new command.

When you send output to quickfix, the window keeps the original command output text. File paths and error lines are still parsed into jumpable quickfix entries, while non-matching lines stay as plain text rows.

## Context Variables

You can use these variables in commands typed into the prompt. They are expanded before execution.

| Variable | Expands to |
| --- | --- |
| `${file}` | Current filename with extension |
| `${filePath}` | Absolute path of the current buffer |
| `${fileDir}` | Directory of the current buffer |
| `${fileName}` | Current filename without extension |
| `${line}` | Current cursor line |
| `${col}` | Current cursor column |
| `${cwd}` | Resolved execution directory |
| `${selection}` | Raw visual selection |
| `${selection:sh}` | Shell-escaped visual selection |

Use `${selection}` when you want the shell to interpret the selected text as-is. Use `${selection:sh}` when the selection should be treated as one safe shell argument.

Examples:

- `python ${filePath}`
- `git blame -L ${line},+1 ${filePath}`
- `rm ${selection}`
- `git commit -m ${selection:sh}`

## Safety

By default, `command.nvim` asks for confirmation when a command contains risky patterns such as:

- command substitution: `$(...)` or `` `...` ``
- pipes to `rm`, `dd`, `mkfs`, or `shred`
- redirects to `/etc`, `/sys`, or `/dev`
- background execution with trailing `&`
- command chains with `&&` or `||`

Turn the warning off with:

```lua
require('command').setup({
  validation = {
    warn = false,
  },
})
```

## Configuration

Full setup example:

```lua
local prompt = require('command.actions.prompt')
local terminal = require('command.actions.terminal')

require('command').setup({
  history = {
    max = 200,
    picker = 'fzf-lua',
    -- file_path = vim.fn.stdpath('data') .. '/command_history.json',
  },
  ui = {
    prompt = {
      max_width = 40,
      max_height = 10,
      ghost_text = true,
    },
    terminal = {
      height = 0.4,
      split = 'below',
    },
  },
  execution = {
    cwd = 'buffer',
  },
  validation = {
    warn = true,
  },
  keymaps = {
    prompt = {
      ni = {
        { '<Up>', prompt.prev_history },
        { '<Down>', prompt.next_history },
        { '<C-f>', prompt.search_history },
        { '<CR>', prompt.enter_insert },
        { '<C-e>', prompt.accept_ghost },
        { '<C-o>', prompt.toggle_cwd },
      },
      n = {
        { '<CR>', prompt.enter },
        { '<Esc>', prompt.cancel },
      },
    },
    terminal = {
      n = {
        { '<CR>', terminal.follow_error },
        { '<C-q>', terminal.send_to_quickfix },
        { 'q', terminal.hide },
        { 'Q', terminal.close },
      },
    },
  },
})
```

Option reference:

| Key | Default | Description |
| --- | --- | --- |
| `history.max` | `200` | Maximum number of commands stored in history |
| `history.picker` | `'fzf-lua'` | History picker used by `<C-f>`. Only `fzf-lua` is supported |
| `history.file_path` | `stdpath('data') .. '/command_history.json'` | Optional custom path for persisted history |
| `ui.prompt.max_width` | `40` | Base width used for the centered prompt window |
| `ui.prompt.max_height` | `10` | Maximum height used for the centered prompt window. Multiline commands expand up to this limit |
| `ui.prompt.ghost_text` | `true` | Show inline history suggestions while typing |
| `ui.terminal.height` | `0.4` | Size of the terminal split as a fraction of screen lines (below/above) or columns (left/right) |
| `ui.terminal.split` | `'below'` | Where the terminal opens: `below`, `above`, `left`, or `right` |
| `execution.cwd` | `'buffer'` | `buffer` uses the current file directory, `root` uses Neovim's current working directory |
| `validation.warn` | `true` | Ask for confirmation before executing risky commands |

Keymap notes:

- `keymaps.prompt.ni` defines prompt mappings for both insert and normal mode
- `keymaps.prompt.n` defines prompt mappings for normal mode
- `keymaps.terminal.n` defines terminal mappings for normal mode
- If you want to fully replace the prompt defaults in normal mode, set both `keymaps.prompt.ni` and `keymaps.prompt.n`
- `<C-q>` in terminal mode always sends the output to quickfix

command.nvim

Today's picks

Was this content helpful?

Recent Feedback

command.nvim

Today's picks

Was this content helpful?

Recent Feedback

Download README