job manager for neovim

• Installation
• Usage
  • Using a shell command string
  • Error handling
• APIs
  • job.start(cmd, opts)
  • job.stop(id, signal)
  • job.send(id, data)
  • job.chanclose(id, t)
  • job.is_running(id)
  • job.wait(id, timeout)
• Job options
  • encoding
  • cwd
  • detached
  • clear_env
  • env
• Error codes
• Callback signatures
  • on_stdout(id, data[, stream])
  • on_stderr(id, data[, stream])
  • on_exit(id, code, signal)
• Self-Promotion

Using nvim-plug

require("plug").add({
	{
		"wsdjeg/job.nvim",
	},
})

Using luarocks

luarocks install job.nvim

Alternatively, using lazy.nvim:

{
	"wsdjeg/job.nvim",
	config = function()
		-- No configuration needed
	end,
}

Basic example:

local job = require('job')
local function on_exit(id, code, signal)
    print('job ' .. id .. ' exit code:' .. code .. ' signal:' .. signal)
end

local cmd = { 'echo', 'hello world' }
local jobid1 = job.start(cmd, {
    on_stdout = function(id, data)
        vim.print(data)
    end,
    on_exit = on_exit,
})

vim.print(string.format('jobid is %s', jobid1))

local jobid = job.start({ 'cat' }, {
    on_stdout = function(id, data)
        vim.print(data)
    end,
    on_exit = function(id, code, signal)
        print('job ' .. id .. ' exit code:' .. code .. ' signal:' .. signal)
    end,
})

job.send(jobid, { 'hello' })

job.chanclose(jobid, 'stdin')

Output:

jobid is 43
{ "hello world" }
job 43 exit code:0 signal:0
{ "hello" }
job 44 exit code:0 signal:0

local jobid = job.start('echo "hello from shell"', {
    on_stdout = function(id, data) vim.print(data) end,
})

job.start returns a positive integer job ID on success, or one of the following error codes:

• 0: invalid command type or empty command
• -1: command not executable or spawn failure
• -2: cwd option is not a directory

Example:

local id = job.start({ '' }, {})
if id <= 0 then
    vim.print('Failed to start job, error code:', id)
end

• cmd (string|table): command to execute. If a string, it is passed to the shell. If a table, the first element is the executable and the rest are arguments.
• opts (table|nil): job options (see Job options).

• id (integer): job ID returned by job.start.
• signal (integer): POSIX signal number (e.g., 9 for SIGKILL, 15 for SIGTERM).

• id (integer): job ID.
• data (string|table|nil): data to send. If a table, each element is written as a line. If nil, an empty string is sent and stdin is shut down.

• id (integer): job ID.
• t (string): which channel to close: "stdin", "stdout", or "stderr".

• id (integer): job ID.

• id (integer): job ID.
• timeout (integer): maximum waiting time in milliseconds.

All options are optional.

If the output encoding of a job command is not UTF‑8, set this option to convert the output automatically.

Example:

job.start({ 'iconv', '-f', 'gbk', 'file.txt' }, {
    encoding = 'gbk',
    on_stdout = function(id, data) vim.print(data) end,
})

Working directory for the job.

job.start({ 'pwd' }, { cwd = '/tmp' })

If true, the job will run in a detached state (see uv.spawn documentation).

If true, only the environment variables provided in env will be passed to the job. By default the job inherits the current environment (with some Neovim‑specific variables removed).

Table of environment variables to set for the job. Values can be strings or numbers.

job.start({ 'printenv', 'MY_VAR' }, {
    env = { MY_VAR = 'hello' },
    on_stdout = function(id, data) vim.print(data) end,
})

Called when the job writes to stdout.

• id (integer): job ID.
• data (table): list of output lines (strings).
• stream (string, optional): if the callback accepts three parameters, this will be "stdout".

Called when the job writes to stderr. Same signature as on_stdout.

Called when the job exits.

• id (integer): job ID.
• code (integer): exit code.
• signal (integer): signal number (0 if the job exited normally).

Like this plugin? Star the repository on GitHub.

Love this plugin? Follow me on GitHub.