Skip to content

commands.md

Latest commit

 

History

History
371 lines (259 loc) · 8.24 KB

commands.md

File metadata and controls

371 lines (259 loc) · 8.24 KB

Commands

Complete reference for all nca CLI commands, subcommands, and flags.

Global Usage (No Subcommand)

nca [OPTIONS]

When invoked without a subcommand, nca starts an interactive session. Behavior depends on flags:

Flag Short Type Default Description
--prompt -p string — Run a one-shot prompt and exit
--safe -s flag false Start in read-only safe mode
--resume -r flag false Resume the most recent session
--no-resume — flag false Force a new session (skip auto-resume)
--run — flag false Start interactive run mode
--model — string — Override the default model
--enable-thinking -t flag false Enable extended thinking/reasoning
--thinking-budget — u32 5120 Token budget for extended thinking
--max-tokens — u32 8192 Max response tokens
--verbose -v flag false Verbose debug logging
--json — flag false Output structured JSON (for CI)
--stream — enum human Stream format: human, ndjson, or off
--no-tui — flag false Use line-oriented REPL instead of full-screen TUI
--permission-mode — enum — Permission mode (see Permissions)
--max-turns — u32 — Max agent turns per run

Examples

# Start interactive TUI session
nca

# One-shot prompt
nca -p "refactor the error handling in src/lib.rs"

# Safe mode (read-only analysis)
nca -s

# Resume last session
nca -r

# Force new session
nca --no-resume

# Use a specific model
nca --model "claude-3-7-sonnet-latest"

# Enable thinking with custom budget
nca -t --thinking-budget 10000

# CI-friendly JSON output
nca -p "list all TODO comments" --json

# NDJSON event stream
nca -p "fix the tests" --stream ndjson

# Line REPL (no full-screen TUI)
nca --no-tui

# Bypass all permission prompts
nca --permission-mode bypass-permissions

Subcommands

nca run

Run a one-shot task with explicit stream control.

nca run --prompt "..." [OPTIONS]
Flag Type Default Description
--prompt string required The task to execute
--stream enum human Stream format: human, ndjson, off
--model string — Override model
--json flag false Structured JSON output
--safe flag false Read-only mode
--permission-mode enum — Permission mode 
nca run --prompt "add input validation" --stream ndjson
nca run --prompt "analyze code quality" --safe --json

nca spawn

Launch a background session that runs without interactive input.

nca spawn --prompt "..." [OPTIONS]
Flag Type Default Description
--prompt string required The task to execute
--model string — Override model
--safe flag false Read-only mode
--json flag false Structured JSON output
--permission-mode enum accept-edits Permission mode 
nca spawn --prompt "write comprehensive tests for the auth module"
nca spawn --prompt "document all public APIs" --model "MiniMax-M2.7"

nca sessions

List and filter saved sessions.

nca sessions [OPTIONS]
Flag Type Default Description
--json flag false JSON output
--status enum — Filter by status: running, completed, cancelled, failed
--since-hours u32 — Show sessions from the last N hours
--search string — Search sessions by text
--limit usize 20 Max number of sessions to show 
nca sessions
nca sessions --status running
nca sessions --since-hours 24 --limit 5
nca sessions --search "auth" --json

nca resume

Resume a previously saved session.

nca resume <SESSION_ID> [OPTIONS]
Flag Type Default Description
--prompt string — Send a follow-up prompt after resuming
--model string — Override model for this session
--safe flag false Resume in read-only mode
--stream enum human Stream format
--no-tui flag false Use line REPL
--permission-mode enum — Permission mode 
nca resume abc123
nca resume abc123 --prompt "continue where you left off"
nca resume abc123 --model "claude-3-7-sonnet-latest"

nca logs

Stream or dump the event log for a session.

nca logs <SESSION_ID> [OPTIONS]
Flag Type Default Description
--follow flag false Follow the log in real-time (like tail -f)
--json flag false Raw JSON output 
nca logs abc123
nca logs abc123 --follow
nca logs abc123 --json

nca attach

Attach to a running session's output stream.

nca attach <SESSION_ID> [--json]

nca status

Show metadata for a session.

nca status <SESSION_ID> [--json]

nca cancel

Cancel a running session.

nca cancel <SESSION_ID> [--json]

nca skills

Manage agent skills.

nca skills [--json]              # List all discovered skills
nca skills list [--json]         # Same as above
nca skills add <SOURCE> [OPTIONS]
nca skills remove <NAME> [OPTIONS]
nca skills update [NAME]         # Update one or all skills

nca skills add:

Flag Short Type Default Description
--skill -s string[] all Specific skills to install (repeatable)
--global -g flag false Install globally to ~/.nca/skills/

nca skills remove:

Flag Short Type Default Description
--global -g flag false Remove from global skills 
nca skills
nca skills add https://github.com/user/skill-repo -s rust-patterns
nca skills remove rust-patterns --global
nca skills update

nca mcp

List configured MCP (Model Context Protocol) servers.

nca mcp [--json]

nca memory

Manage persistent memory notes.

nca memory [--json]              # List memory notes
nca memory list [--json]         # Same as above
nca memory add <TEXT> [--kind <KIND>]
Flag Type Default Description
--kind string note Type of memory entry 
nca memory
nca memory add "prefer async/await over thread spawning"
nca memory add "API uses bearer token auth" --kind note

nca models

List available models for the current provider.

nca models [--json]

nca doctor

Run diagnostic checks on your configuration.

nca doctor [--json]

Checks API key availability, provider connectivity, config file validity, and tool dependencies.

nca config

Display the current runtime configuration.

nca config [--json]

nca completion

Generate shell completion scripts.

nca completion <SHELL>

Supported shells: bash, zsh, fish, power-shell, elvish. Default: bash.

nca index

Manage the CLI index cache (used for agent self-awareness of available commands).

nca index build [--json]
nca index show [--json]

nca autoresearch

Run automated research on a program/topic.

nca autoresearch once <PROGRAM> [--workspace <PATH>]
Flag Type Default Description
--workspace path current directory Workspace for research output

Stream Modes

The --stream flag controls output format:

Mode Description
human Terminal-friendly output with colors, markdown rendering, and TUI support (default)
ndjson Newline-delimited JSON events — one event per line, for machine consumption
off Minimal output — final result only

Exit Codes

Code Meaning
0 Success
1 General error (provider failure, config issue, etc.)
non-zero Task failure or cancellation