Lua Academy · Lesson

Commands and Keymaps

Add user-facing actions.

User Commands Overview

User commands are colon-commands your plugin exposes, like :Format or :Telescope. They must start with an uppercase letter.

nvim_create_user_command defines them in Lua, taking a name, a callback or string, and an options table. This replaces Vimscript's :command.

vim.api.nvim_create_user_command('Hello', function()
  print('Hello from my plugin')
end, {})

Set nargs to accept arguments: '0', '1', '*', '?', or '+'. The callback receives an opts table with args, fargs, and bang.

fargs is the argument list already split on whitespace, which is usually what you want.

vim.api.nvim_create_user_command('Greet', function(opts)
  print('Hi ' .. opts.args)
end, { nargs = 1 })