n8v CLI & MCP

Use the n8v CLI to create and list tasks from your terminal, and to pull a task's branch and session so you can pick up where the agent left off.

Requirements

• macOS, Linux, or WSL (Windows Subsystem for Linux)
• Node.js 18+ or newer
• npm package manager (bun is not currently supported)

Installation

npm install -g @n8v/cli

Authentication

n8v auth

This will:

You can override the default settings directory by setting the N8V_SETTINGS_DIR environment variable before running the CLI. For example:

export N8V_SETTINGS_DIR=~/.config/n8v
n8v auth

Commands

n8v create

Create a new task in n8v with a message.

# Create a task in the current repository and branch
n8v create "Fix the login bug"

# Specify a different repository
n8v create "Add new feature" --repo owner/repo

# Use a specific base branch
n8v create "Update documentation" --branch develop

# Use existing branch without creating a new one
n8v create "Quick fix" --no-new-branch

# Use a specific AI model
n8v create "Refactor code" --model opus

# Create a task in plan mode (for complex tasks requiring planning)
n8v create "Build new authentication system" --mode plan

Options

• -r, --repo <repo>: GitHub repository (default: current repository)
• -b, --branch <branch>: Base branch name (default: current branch, falls back to main)
• --no-new-branch: Don't create a new branch (default: creates new branch)
• -M, --mode <mode>: Whether to create tasks in plan mode (require approval before making changes) or execution mode. Only available with the Claude Code agent (default: execute)
• -m, --model <model>: AI model to use (default: your default model, as the app shows it)

--model takes any model the API takes; n8v models lists the ones your account can use. An unknown name is answered with the model it most likely means, and a model your account cannot use is refused before the task is created. See Model access.

n8v models

List the models you can use, by provider, with your default marked.

n8v models          # the models you can use
n8v models --all    # every model, with the ones not enabled for you

Claude Code
  sonnet-5        Sonnet 5        default
  opus-5.5        Opus 5.5

OpenAI Codex
  gpt-5.5         GPT-5.5         needs a ChatGPT sign-in

3 more models are not enabled for this account. `n8v models --all` lists them.

n8v pull

Pull tasks from n8v to your local machine:

# Interactive mode - select from recent tasks
n8v pull

# Pull a specific task by ID
n8v pull <taskId>

# Pull and automatically launch Claude Code
n8v pull <taskId> --resume

Options

• -r, --resume: Automatically launch Claude Code after pulling

Task Display

Once selected, each task shows:

• Task title
• Branch name
• Repository
• PR # (if available)

n8v list

List all tasks in a non-interactive format:

# List all tasks (automatically filters by current repo when inside a Git repository)
n8v list

Task Display

Each task shows:

• Task ID
• Name
• Branch
• Repository
• PR # (if available)

A count of your active tasks is returned after all of your tasks are listed.

Example Output

Task ID         abc123def456
Name            Fix login bug
Branch          n8v/fix-login
Repository      myorg/myrepo
PR Number       #123

Task ID         def789ghi012
Name            Add dark mode
Branch          n8v/dark-mode
Repository      myorg/myrepo
PR Number       N/A

Total: 2 tasks

n8v mcp

Run an MCP (Model Context Protocol) server for the git repository:

# Run MCP server for current directory
n8v mcp

Claude Code Integration

You can add the n8v MCP server to your local Claude Code instance to enable direct interaction with n8v tasks from within Claude:

claude mcp add n8v -- n8v mcp

This integration provides Claude Code with the following capabilities:

• n8v_list: List all your n8v tasks directly from Claude
• n8v_create: Create new tasks without leaving Claude Code
• n8v_pull: Pull task session data to continue work

The MCP server acts as a bridge between Claude Code and n8v, allowing you to manage tasks using natural language commands within your AI coding sessions.