nca

Getting Started

Prerequisites

  • Rust toolchain — install via rustup (edition 2024, stable channel)
  • Git — required for session worktrees and version control integration
  • ripgrep (rg) — used by the search_code tool for fast code search
  • An LLM API key — MiniMax (default), Anthropic, OpenAI, OpenRouter, or any compatible endpoint

Installation

One-line install (macOS and Linux)

curl -fsSL https://nca-cli.com/install | bash

GitHub Releases

Pre-built binaries ship for Linux, macOS, and Windows (x86_64 and ARM64). Grab the matching archive from Releases.

Build from Source

git clone https://github.com/madebyaris/native-cli-ai.git
cd native-cli-ai

# Build optimized release binary
cargo build --release

# Install to your PATH (Unix)
cp target/release/nca /usr/local/bin/

The release profile is optimized for size and speed (opt-level = 3, lto = "thin", strip = true).

Verify Installation

nca doctor

This runs configuration checks and reports any issues with your setup.

Initial Setup

1. Set an API Key

The fastest way to get started is to export your API key:

# MiniMax (default provider)
export MINIMAX_API_KEY="your-key-here"

# Or use another provider
export ANTHROPIC_API_KEY="your-key-here"
export OPENAI_API_KEY="your-key-here"
export OPENROUTER_API_KEY="your-key-here"

To persist the key, add it to your shell profile (~/.zshrc, ~/.bashrc) or store it in the config file:

# ~/.local/share/ncacli/config.toml  (or $NCA_HOME/config.toml)
[provider.minimax]
api_key = "your-key-here"

Legacy ~/.nca/config.toml is still read if the product-home config is missing.

2. First Run

Navigate to any project directory and launch nca:

cd ~/my-project
nca

On first launch, nca runs an onboarding flow that helps you:

  • Select your default LLM provider
  • Enter your API key
  • Confirm basic settings

After onboarding, you enter the interactive TUI where you can start chatting with the agent.

3. One-Shot Mode

For quick tasks without entering the interactive session:

nca -p "explain the architecture of this project"
nca -p "add a health check endpoint to the API"

Directory Structure

nca creates project-local files under .nca/ for instructions, skills, and git worktrees. Session history, memory, and last-session pointers live under the product home ($NCA_HOME, $XDG_DATA_HOME/ncacli, or ~/.local/share/ncacli/):

~/.local/share/ncacli/
├── config.toml
└── workspaces/<slug>-<16hex>/
    ├── sessions/             # Session state and event logs
    ├── memory.json
    ├── last_session
    └── workspace.json

my-project/
├── .nca/
│   ├── config.local.toml    # Workspace-specific config overrides
│   ├── instructions.md      # Local instructions for the agent
│   ├── worktrees/            # Git worktrees for sub-agents
│   └── skills/               # Local skill definitions
├── .ncarc                    # Project-level instructions
├── AGENTS.md                 # Agent instructions (also used by other AI tools)
└── ...

Global config lives at ~/.local/share/ncacli/config.toml.

Custom Instructions

You can guide the agent’s behavior with instruction files, loaded in this order:

  1. Built-in system prompt — nca’s default behavior rules
  2. AGENTS.md — project-level instructions (compatible with other AI tools)
  3. .ncarc — project-level nca-specific instructions
  4. .nca/instructions.md — personal local instructions (gitignored)

Example .ncarc:

## Project Context

This is a REST API built with Axum. Use PostgreSQL for data storage.
Always run `cargo test` after making changes.
Prefer the `anyhow` crate for error handling.

Shell Completions

Generate shell completions for your shell:

# Bash
nca completion bash > /etc/bash_completion.d/nca

# Zsh
nca completion zsh > ~/.zsh/completions/_nca

# Fish
nca completion fish > ~/.config/fish/completions/nca.fish

Next Steps