napster-cli

nap

The nap (nap) is a customizable command line coding agent.

Installation

Install with npm (Node.js 20+):

npm i -g napster-cli

If napster is not found after install, restart your shell session.

Usage

napster

Headless Mode

Headless mode (-p flag) runs without an interactive terminal UI, making it perfect for:

• Scripts and automation
• CI/CD pipelines
• Docker containers
• VSCode/IntelliJ extension integration
• Environments without a TTY

# Basic usage
napster -p "Generate a conventional commit name for the current git changes."

# With piped input
echo "Review this code" | napster -p

# JSON output for scripting
napster -p "Analyze the code" --format json

# Silent mode (strips thinking tags)
napster -p "Write a README" --silent

TTY-less Environments: Headless mode is designed to work in environments without a terminal (TTY), such as when called from VSCode/IntelliJ extensions using terminal commands. The CLI will not attempt to read stdin or initialize the interactive UI when running in headless mode with a supplied prompt.

Session Management

The CLI automatically saves your chat history for each terminal session. You can resume where you left off:

# Resume the last session in this terminal
nap --resume

# List recent sessions and choose one to resume
nap ls

# List sessions in JSON format (for scripting)
nap ls --json

Command Line Options

• -p: Run in headless mode (no TUI)
• --config <path>: Specify agent configuration path
• --resume: Resume the last session for this terminal
• <prompt>: Optional prompt to start with

Environment Variables

• NAPSTER_API_BASE: Override backend API base URL (default https://api.nap-code.com/)
• NAPSTER_API_KEY: Explicit backend token override
• NAPSTER_BOOTSTRAP_PATH: Override bootstrap route path (default cli/bootstrap)
• nap_API_BASE: Legacy fallback for backend API base URL
• nap_API_KEY: Legacy fallback backend token override
• nap_GLOBAL_DIR: Override nap home directory (default ~/.nap)
• nap_CLI_DISABLE_COMMIT_SIGNATURE: Disable adding the nap commit signature to generated commit messages
• FORCE_NO_TTY: Force TTY-less mode, prevents stdin reading (useful for testing and automation)

Compatibility note: nap_API_BASE, nap_API_KEY, nap_GLOBAL_DIR, and nap_CLI_DISABLE_COMMIT_SIGNATURE remain supported as fallbacks.

Service Bootstrap Token

By default, napster attempts to auto-bootstrap a backend access token on startup.

• Token bootstrap endpoint: ${NAPSTER_API_BASE}/${NAPSTER_BOOTSTRAP_PATH}
• Token cache file: ~/.nap/service-auth.json
• If a valid cached token exists, it is reused.
• If no token is available, napster falls back to local service credentials (XAI_API_KEY / NAPSTER_XAI_API_KEY) when present.

Commands

• nap: Start an interactive chat session
• nap ls: List recent sessions with TUI selector to choose one to resume
• nap remote: Launch a remote instance
• nap serve: Start HTTP server mode

Session Listing (nap ls)

Shows recent sessions, limited by screen height to ensure it fits on your terminal.

• --json: Output in JSON format for scripting (always shows 10 sessions)

TTY-less Support

The CLI fully supports running in environments without a TTY (terminal):

# From Docker without TTY allocation
docker run --rm my-image nap -p "Generate docs"

# From CI/CD pipeline
nap -p "Review changes" --format json

# From VSCode/IntelliJ extension terminal tool
nap -p "Analyze code" --silent

The CLI automatically detects TTY-less environments and adjusts its behavior:

• Skips stdin reading when a prompt is supplied
• Disables interactive UI components
• Ensures clean stdout/stderr output

For more details, see spec/tty-less-support.md.