🟢 Stable

nanx supports multiple configuration methods to customize its behavior. You can configure nanx through:

  • Config Files - YAML, TOML, or JSON configuration files with inheritance support
  • Environment Variables - Runtime configuration for installation and behavior
  • Project Settings - .repo.yml for project-specific commands and releases

Quick Start

Create a configuration file to get started:

# Create global config
mkdir -p ~/.config/nanx
nano ~/.config/nanx/config.yaml

Basic configuration example:

# ~/.config/nanx/config.yaml
editor:
  default: cursor

providers:
  - name: claude
    type: anthropic
    api_key: sk-ant-api03-...
    model: claude-3-5-sonnet-20241022

repo:
  commit:
    generate_message:
      default_provider: claude

Or use the config command:

# Edit global config
nanx config edit --global

# Edit local project config
nanx config edit

# Edit user-local config (not committed to git)
nanx config edit --user-local

Configuration Locations

nanx searches for configuration files in the following order (merge order: global → local → user-local):

  1. ~/.config/nanx/config.(yaml|yml|toml|json) - Global (user-level) config
  2. .nanx/config.(yaml|yml|toml|json) - Local (project-level) config
  3. .nanx/config.user.(yaml|yml|toml|json) - User-local config (gitignored) New in v0.3.0

File Priority: YAML > TOML > JSON

User-Local Configuration New in v0.3.0

User-local configuration allows you to have personal settings within a repository that won't be committed to version control. This is ideal for:

  • Personal API keys that shouldn't be shared
  • Local editor preferences
  • Development-specific overrides

User-local configs are automatically added to .gitignore when created. Use --user-local flag with config commands to manage this layer.

Configuration Inheritance

By default, configs inherit and merge from parent layers (global → local → user-local). You can disable inheritance by setting no_inherit: true at the top of your config.

Configuration Topics

Config File Reference

Complete reference for all configuration options in YAML/TOML/JSON files.

AI Providers

Set up Claude, GPT, Gemini, or local LLMs for AI-powered features.

.repo.yml Reference

Project-specific commands, release configuration, and workflows.

Environment Variables

These environment variables configure nanx behavior at runtime:

Installation Variables

Variable Default Description
NANX_INSTALL_DIR ~/.local/bin Installation directory for nanx binary
NANX_FORCE 0 Force reinstall when set to 1

Example usage:

# Install to custom directory
NANX_INSTALL_DIR=/usr/local/bin curl -fsSL https://install.nanx.dev | zsh

# Force reinstall
NANX_FORCE=1 curl -fsSL https://install.nanx.dev | zsh

Editor Configuration

Configure your preferred editor for commands like nanx config edit:

editor:
  default: cursor  # cursor, vscode, vim, emacs, nano, subl, atom
  command: /usr/local/bin/cursor  # Optional: full path

Shell Integration

Add nanx to your PATH in your shell profile:

# Add to ~/.zshrc or ~/.bashrc
export PATH="$PATH:$HOME/.local/bin"

After updating your shell profile, reload it:

# For zsh
source ~/.zshrc

# For bash
source ~/.bashrc

Custom Aliases

If you prefer different aliases for repo commands, add them to your shell profile: 

# Example: use 'g' instead of 'nanx r'
alias g='nanx repo'

# Now you can use:
# g s      (git status)
# g aa     (git add --all)
# g cm     (git commit -m)

Next Steps