Config Management

The nanx config command provides utilities for managing nanx configuration files, including viewing current config, opening your editor, and validating configuration syntax.

Quick Start

# Show current configuration
nanx config show

# Edit config in your editor
nanx config edit

# Validate configuration
nanx config validate

Subcommands

show

Display the current effective configuration:

nanx config show

This shows the merged configuration from all sources (merge order: global → local → user-local):

• Global config: ~/.config/nanx/config.{yaml,yml,toml,json}
• Local config: .nanx/config.{yaml,yml,toml,json}
• User-local config: .nanx/config.user.{yaml,yml,toml,json} New in v0.3.0
• Environment variables

Output Format

# Default YAML output (merged config)
nanx config show

# JSON output
nanx config show --format json

# Show only global config
nanx config show --global

# Show only local config
nanx config show --local

# Show only user-local config (v0.3.0+)
nanx config show --user-local

# Show config with source annotations
nanx config show --sources

edit

Open the configuration file in your configured editor:

nanx config edit

This opens your local config file (.nanx/config.yaml) by default, in the editor determined by the following priority order:

1. $NANX_EDITOR - Tool-specific override
2. config.editor.command - Full path from config
3. config.editor.default - Editor name from config
4. $VISUAL - Standard visual editor variable
5. $EDITOR - Standard editor variable
6. Detected popular editor (cursor, code, neovim, vim, etc.)
7. Interactive prompt showing ALL installed editors + install options

Note: The interactive prompt shows all detected installed editors (cursor, code, zed, nvim, helix, micro, emacs, vim, nano, vi), allowing you to choose your preferred editor even if you have multiple installed.

Edit Specific Config

# Edit local config (default)
nanx config edit

# Edit global config
nanx config edit --global

# Edit user-local config (v0.3.0+)
nanx config edit --user-local

# Create config if it doesn't exist
nanx config edit --create

validate

Check configuration for syntax errors and invalid values:

nanx config validate

Validation checks:

• Syntax: Valid YAML/TOML/JSON
• Schema: All fields match expected types
• Values: Enum values are valid
• References: File paths exist (if applicable)
• API Keys: Provider configs are complete

Validation Options

# Validate local config (default)
nanx config validate

# Validate global config
nanx config validate --global

# Validate user-local config (v0.3.0+)
nanx config validate --user-local

# Validate all configs
nanx config validate --all

list

Show all configuration file locations and their existence:

nanx config list

Example output:

Configuration file locations:
(merge order: global → local → user-local)

1. Global (home directory):
   ✓ ~/.config/nanx/config.yaml

2. Local (repo root):
   ✓ .nanx/config.yaml

3. User Local (repo root, gitignored):
   ✗ .nanx/config.user.yaml (not found)

where

Print the path to configuration file(s):

# Show all config paths
nanx config where

# Show only global config path
nanx config where --global

# Show only local config path
nanx config where --local

# Show only user-local config path (v0.3.0+)
nanx config where --user-local

get

Get a specific configuration value using :: notation:

# Get editor default
nanx config get editor::default

# Get max tokens for commit messages
nanx config get repo::commit::generate_message::max_tokens

# Get from global config only
nanx config get editor::default --global

# Get from local config only
nanx config get editor::default --local

# Get from user-local config only (v0.3.0+)
nanx config get editor::default --user-local

set

Set a specific configuration value using :: notation:

# Set editor in local config (default)
nanx config set editor::default vim

# Set in global config
nanx config set editor::default code --global

# Set in user-local config (v0.3.0+)
nanx config set editor::default cursor --user-local

# Set numeric value
nanx config set repo::commit::generate_message::max_tokens 2000

# Set boolean value
nanx config set repo::commit::generate_message::auto_stage true

unset

Remove a specific configuration value (allows inheritance from parent config):

# Unset from local config (default)
nanx config unset editor::default

# Unset from global config
nanx config unset editor::default --global

# Unset from user-local config (v0.3.0+)
nanx config unset editor::default --user-local

repos New in v0.4.0

Manage repository configuration files. This command handles two types of configs:

• Global (~/.nanx/repos.yml): Personal settings like worktree preferences, editor, per-repo overrides
• Local (.repo.yml): Shared team settings like commands, release config, worktree setup files

# Edit global repos config (default)
nanx config repos

# Edit global repos config explicitly
nanx config repos --global

# Edit local .repo.yml
nanx config repos --local

# Show config file paths
nanx config repos --path

# Create config if not exists
nanx config repos --create

# Create and edit
nanx config repos --create --global

repos Options

Global Repos Config Example

# ~/.nanx/repos.yml
settings:
  on_switch_action: auto  # auto | editor | cd | none
  editor: cursor

repositories:
  - slug: my-project
    worktree:
      copy_files:
        - ".env"
        - ".env.local"

See Worktree Workflow for complete documentation on worktree settings.

Configuration Files

Global Config

Location: ~/.config/nanx/config.{yaml,yml,toml,json}

The global config applies to all projects. This is where you typically configure AI providers, editor preferences, and default behaviors.

Local Config

Location: .nanx/config.{yaml,yml,toml,json}

Local (project-specific) config overrides global settings. Use this for project-specific AI models, commit templates, or branch defaults.

User-Local Config New in v0.3.0

Location: .nanx/config.user.{yaml,yml,toml,json}

User-local config provides personal overrides within a repository that are automatically gitignored. Perfect for storing personal API keys or development preferences without affecting team configurations.

Inheritance

Configs merge in order: global → local → user-local. Values in later configs override earlier values.

You can explicitly unset a value to inherit from parent:

editor:
  default: ~  # Inherit from parent config

Or disable inheritance entirely:

no_inherit: true

Command Options

show Options

edit Options

validate Options

Examples

First Time Setup

# Create and edit global config
nanx config edit

# Add your AI provider
providers:
  - type: anthropic
    api_key: sk-ant-...
    models:
      - claude-3-5-sonnet-20241022

# Save and validate
nanx config validate

Local Config for Project

# Create local config with interactive prompt
nanx config edit --create

# Set project-specific max tokens
nanx config set repo::commit::generate_message::max_tokens 2000

# Validate
nanx config validate

Debug Configuration Issues

# Show effective config with sources
nanx config show --sources

# Check where each setting comes from:
# editor.default: "code"  # from: .nanx/config.yaml
# repo.commit.generate_message.max_tokens: 2000  # from: .nanx/config.yaml
# repo.commit.generate_message.temperature: 0.5  # from: ~/.config/nanx/config.yaml

# Get specific value
nanx config get editor::default

# List all config locations
nanx config list

Manage Config Values

# Set a value in local config
nanx config set editor::default vim

# Set a value in global config
nanx config set repo::commit::generate_message::temperature 0.9 --global

# Unset to inherit from global
nanx config unset editor::default

# Check current value
nanx config get editor::default

Troubleshooting

Config Not Loading

If your config changes aren't being picked up:

# Check syntax
nanx config validate

# Show effective merged config
nanx config show

# Show config with sources to debug inheritance
nanx config show --sources

# List config file locations
nanx config list

# Verify file paths
nanx config where

Editor Not Opening

If nanx config edit doesn't open your editor:

# nanx will auto-detect popular editors and prompt if none found
# Editor priority order:
# 1. $NANX_EDITOR
# 2. config.editor.command
# 3. config.editor.default
# 4. $VISUAL
# 5. $EDITOR
# 6. Detected installed editor
# 7. Interactive prompt with auto-install

# Set editor preference
nanx config set editor::default vim --global

# Or use environment variable
export NANX_EDITOR=code
nanx config edit

# Or use standard env vars
export VISUAL=cursor
export EDITOR=nano

Invalid Configuration

If you get validation errors:

# See detailed error
nanx config validate

# Common issues:
# - YAML indentation errors
# - Invalid enum values
# - Missing required fields
# - Malformed API keys

# Fix and re-validate
nanx config edit
nanx config validate

Configuration Reference

For complete configuration options and detailed explanations, see:

• Configuration File Reference
• AI Providers Setup
• Configuration Overview

Next Steps

• Full Configuration Reference
• Setup AI Providers
• Repository Commands
• All Commands