Nia CLI User Guide

Nia is an agentic software development life cycle (SDLC) command-line tool from Progress. It orchestrates AI coding agents through structured workflows that help teams plan work, implement changes, review results, and maintain an auditable record of AI-assisted development.

Nia provides one command surface above the AI agents and development systems your team already uses. Project context, team conventions, workflow stages, checks, and outputs stay connected to the task instead of being scattered across chat sessions and tools.

Why Use Nia

AI coding agents can produce useful results quickly, but teams still need a consistent way to define work, preserve context, review changes, and apply engineering controls. Nia adds that operating model around the agents.

Nia helps your team:

• Standardize development practices: Apply the same planning, implementation, review, and documentation expectations across repositories and developers.
• Reduce routine supervision: Run multi-step workflows with defined pre-checks, agent execution, output validation, and post-work cleanup.
• Preserve project context: Provide agents with issue, pull request, ticket, and project metadata so they can work from the same information as the team.
• Improve review quality: Produce structured plans, traces, and workflow results that help reviewers focus on technical decisions instead of reconstructing what happened.
• Strengthen governance: Configure human review points, checks, and team conventions before AI-generated changes move through the development process.
• Measure AI-assisted work: Record workflow activity and AI usage so teams can understand how agents, models, and workflows affect development effort and cost.

Key Features

AI Agent Orchestration

Nia coordinates supported AI coding agents through a consistent CLI. You can add or change an agent without redesigning the workflow that surrounds it.

This separation gives teams a stable engineering process while agent tools and model choices change. Developers can use a common command surface and review standard across projects.

End-to-End SDLC Workflows

Built-in workflows cover common activities across the software development life cycle:

• Backlog management: Review backlog health, prioritize work, and plan releases.
• Issue management: Draft, review, triage, split, prioritize, and plan issues.
• Code operations: Implement plans, review code, apply fixes, refactor, and build documentation.
• Pull request management: Create pull requests, review code quality, evaluate merge readiness, and publish changes.
• Documentation and security: Create documentation and connect security checks to development workflows.

These workflows give teams repeatable starting points for common tasks while leaving room for project-specific configuration.

Context-Aware Execution

Nia carries relevant context into a workflow, including project metadata, issue IDs, pull request IDs, ticket IDs, technology choices, testing frameworks, and package managers. This context helps agents make decisions that match the repository and the task.

Keeping context with the work reduces tool switching and makes handoffs easier. Team members can inspect the same task context when they review or continue an operation.

Configurable Workflows

Nia defines commands, subcommands, options, help text, and workflow operations through TOML configuration. Teams can create custom commands that match their development process instead of forcing every project into one fixed sequence.

Custom workflows can include:

• Pre-work checks and steps: Validate prerequisites or prepare the environment before agent execution.
• Agent operations: Run the main AI-assisted task with the configured project context.
• Output validation: Confirm that the workflow produced the expected files or results.
• Post-work steps: Clean up temporary resources, report status, or collect additional results.

Nia validates configuration at startup and reports errors before a workflow runs. This makes team-defined workflows easier to test and maintain.

Traceability and Governance

Nia records workflow execution so teams can understand how an AI-assisted change was produced. Traces can capture prompts, outputs, decisions, workflow stages, code changes, and model or token usage.

This record supports consistent review and audit processes. Teams can define checks and human review points that keep engineering judgment in the loop before changes are merged.

Integrations and Model Profiles

Nia connects workflows to development systems such as GitHub, Jira, Azure DevOps, Shortcut, ServiceNow, Freshdesk, and PagerDuty, depending on the configured integration. It also supports code platforms and security tools used in the development process.

Teams can select predefined model profiles for different priorities, including predictable behavior, balanced capability, or lower-cost experimentation. Centralizing these choices in configuration makes model usage easier to manage across projects.

Built-In Roles and Shell Support

Nia includes workflow roles for activities such as product management, software architecture, software engineering, technical writing, security analysis, and site reliability engineering. Shell completions for Bash, Zsh, Fish, and PowerShell help developers discover commands and options from their terminal.

Getting Started

Start with these sections:

1. Installation - Install Nia on your system
2. Quick Start - Get up and running in 5 minutes

Exploring the Guide

This guide is organized into the following sections:

• Getting Started: Installation and initial setup
• Configuration: How to configure and customize Nia
• User Guide: Detailed usage instructions
• Reference: Complete command and configuration reference
• Troubleshooting: Solutions to common problems
• Appendix: FAQ and additional resources

Getting Help

Use the following resources when you need help:

• Built-in help: Run nia --help or nia <command> --help.
• Documentation: Run nia docs to open the documentation locally.
• Issues: Report bugs in the project repository.
• Discussions: Ask questions in the project discussions.

Version

This documentation is for Nia CLI version 2.6.0.

Next Steps

Continue with Installing Nia, then follow the Quick Start guide to configure an agent and project metadata.

Quick Start with the Sample App

The fastest way to learn NIA is to run its built-in, guided tutorials against a real codebase. The nia learn command walks you through a hands-on curriculum on the healthcare-app-angular sample app: it validates your environment, explains what each command does, runs the real NIA workflow, and tracks your progress as you go.

This guide is the quickest path from zero to productive. Each tutorial executes an actual NIA command against real code and real GitHub issues, so by the end you will have seen nia ask, the issue-to-PR workflow, ticket triage, security review, and backlog planning in action — without writing any configuration by hand.

Prefer to use your own repository? Follow the Quick Start instead. This sample-app guide is optimized for learning; the standard Quick Start is optimized for adopting NIA in your own project.

Prerequisites

• A GitHub account — required for repository access and authentication.
• The tutorials run against a clone of the sample app (see Step 1).

Using the Dev Container (recommended)

The sample app includes a Dev Container that installs Node.js, the GitHub CLI (gh), supported AI coding agents, and NIA automatically. This is the recommended approach because:

• Zero manual installation — all dependencies are pre-configured.
• Isolated environment — protects your local system from unintended changes.
• Consistent experience — eliminates “works on my machine” issues.

⚠️ Agent Isolation: AI coding agents execute commands and modify files autonomously. Running them inside a Dev Container, VM or sandbox provides essential isolation that prevents accidental changes to your local system or other projects. We strongly recommend using the Dev Container for the NIA tutorials to ensure safe and reliable execution.

To launch the Dev Container with VS Code, choose one of the following:

• Local Dev Container: Install Docker Engine and Visual Studio Code with the Dev Containers extension. After cloning the repository (Step 1), open the folder in VS Code and choose Reopen in Container when prompted.

• Custom Container Build: the Dev Container format is well suported by other build systems and cloud platforms, feel free to use the one you’re most familiar with.

On first launch, the container downloads the supported coding agents and the latest NIA release, so an internet connection is required. After setup completes, authenticate the GitHub CLI (gh auth login) and your chosen coding agent — see Configure your coding agent for more details if you have trouble authenticating your chosen agent.

Manual Setup (without Dev Container)

If you prefer not to use the Dev Container, you can configure the environment on your own VM or test system:

• Node.js 18+ — the coding agents install via npm. Get it from nodejs.org.
• GitHub CLI — install with brew install gh, winget install --id GitHub.cli, or sudo apt install gh, then authenticate with gh auth login.
• AI Coding Agent — GitHub Copilot CLI, Claude Code, or OpenCode (see Agent Setup).
• NIA — follow the installation steps in the standard Quick Start.

Note: When running outside a Dev Container, take care to understand what commands the AI agent will execute, as they run directly on your system.

1. Clone and open the sample app

Clone the repository to your system:

git clone https://github.com/telerik/healthcare-app-angular.git
# Or use the SSH URI - git clone git@github.com:telerik/healthcare-app-angular.git
cd healthcare-app-angular

Open the folder in VS Code and choose Reopen in Container when prompted. The Dev Container provisions every dependency the tutorials need.

Confirm NIA is available:

nia --version

The terminal prints a NIA version number, for example nia 4.3.5.

2. Configure your coding agent

Run the one-time setup for the learning environment:

nia learn init

This command:

• Explains the NIA configuration system.
• Prompts you to select a coding agent — GitHub Copilot CLI, Claude Code, or OpenCode.
• Runs nia config init --agent <agent> --models stable for you.
• Extracts the offline documentation to .nia/cache/docs/.

The --models stable flag configures NIA to use specific, optimised models rather than automatic model selection. This ensures consistent, predictable behavior across your tutorials and workflows.

Why not use automatic model selection? While agents support an auto option that dynamically selects models, this can lead to inconsistent output quality and unpredictable costs. The stable profile provides reliable behavior that’s been validated with NIA’s prompts. For advanced model configuration, see AI Model Selection.

Additional OpenCode note: Replace auto with provider/claude-sonnet-4.5, and set "issue.plan" to provider/claude-opus-4.5.

Make sure the agent you pick is authenticated. GitHub Copilot CLI reuses your gh authentication; Claude Code and OpenCode authenticate on first launch (claude or opencode auth login). Verify everything with:

nia status

3. See the tutorials

List every tutorial along with its status and estimated time:

nia learn list

The seven tutorials build on one another, from a two-minute question to a full security review:

4. Run the tutorials in sequence

Start the next incomplete tutorial. Run this command again after each one to progress through the curriculum in order:

nia learn next

Every run follows the same guided pattern:

1. Validates your environment — GitHub CLI authentication, agent authentication, and that you are inside a clone of the Demo App repo.
2. Explains what you’ll learn — the concept, the value NIA adds, and links to the relevant documentation.
3. Runs the real command — the exact nia command is printed, then executed against the sample app.
4. Tracks your progress — completion status is saved to .nia/config/learn.toml, so nia learn next always resumes where you left off.

To jump straight to a specific tutorial instead of following the sequence, run it by name:

nia learn run ask-architecture
nia learn run issue-validation

Re-running a completed tutorial prompts for confirmation, because the agent may exit early when the expected changes already exist. Use --force to skip that prompt:

nia learn run ask-architecture --force

Verify your success

You have completed this guide when all of the following are true:

• nia --version prints a version number.
• nia learn init configured an agent and nia status reports no blocking problems.
• nia learn list shows tutorials marked as completed.
• Running nia learn next reports that all tutorials are complete.

You’re ready for your own project

Congratulations — you are now proficient with NIA. You have used nia ask, the issue-to-review-lite and issue-to-review workflows, ticket triage, a long-horizon security review, and backlog planning against a real codebase. The next step is to set up NIA in your own project: initialize configuration with nia config init, describe your project in .nia/config/project.toml, and run your first workflow on code you own.

Continue with the Quick Start to configure NIA in your own project and automate an issue from planning to pull request with nia workflow run issue-to-pr.

Next steps

• Set up NIA in your own project with your issue tracker and code platform.
• Configure an AI coding agent to change agents, models, or prompt formats.
• Explore the built-in workflows that power the tutorials you just ran.
• Review the command reference for every target, operation, flag, and modifier.

Quick Start

NIA is a command-line agent harness for software development life cycle (SDLC) workflows. It connects your project context and development tools to an AI coding agent so you can draft issues, create plans, review code, and run other configured workflows.

This guide takes you from installing NIA to configuring a supported AI coding agent, initializing NIA in a project, and running an Issue-to-PR workflow that begins by setting an issue context and generating a plan with nia issue plan. The examples cover GitHub Copilot CLI, Claude Code, and OpenCode — use the tabs to pick your agent. GitHub Copilot CLI is the shortest path in this tutorial. The AI coding agent setup guide contains the agent-specific requirements and authentication commands.

Want a guided, hands-on tour first? The Quick Start with the Sample App runs NIA’s built-in nia learn tutorials against a ready-made codebase — no configuration required. Come back here when you are ready to adopt NIA in your own project.

Prerequisites

Before you begin, ensure that you have:

• Node.js 18+ (node --version) — the coding agents install via npm. Get it from nodejs.org.
• GitHub CLI (gh --version & gh auth status) — installs and authenticates NIA. Install with brew install gh, winget install --id GitHub.cli, or sudo apt install gh and then authenticate.
• NIA runs inside a project, so you need a local Git repository to work in. This guide uses your own project. If you would rather practice on a ready-made codebase with guided tutorials, follow the Quick Start with the Sample App instead.

Installation & Verification

Make the nia command available in a new terminal.

1. Download and run the installer:

gh release download --repo telerik/project-nia --pattern 'install.ps1'
.\install.ps1

gh release download --repo telerik/project-nia --pattern 'install.sh'
sh install.sh

2. Close the current terminal and open a new one so the updated PATH is available.

3. Verify the installation.

   nia --version
   

The terminal prints a NIA version number, for example nia 4.2.1. If the command is not found, open a new terminal and confirm that the directory containing the NIA executable is on your PATH.

4. Install and authenticate an AI coding agent.

Give NIA an authenticated coding agent that can execute a workflow. You can change agents later by re-running config init.

5. Initialize NIA Configuration.

Run nia config init from the root of your project, such as a locally cloned Git repository (for example, https://github.com/telerik/healthcare-app-angular). The command creates the NIA configuration files that store your AI agent, project metadata, and optional toolchain connections.

Choose the initialization command that matches your setup:

• Connect GitHub Issues and GitHub

Use this command when your workflows will read issues from GitHub or work with a GitHub repository. Pick the tab for the agent you set up in the previous step:

nia config init --issues github_issues --code github --agent github_copilot --models stable

nia config init --issues github_issues --code github --agent claude_code --models stable

nia config init --issues github_issues --code github --agent opencode --models stable

This command creates configuration for the selected AI coding agent, GitHub Issues, and GitHub as the code platform for demo purposes. Other providers like JIRA and Bitbucket are supported.

• Use a Local-Only Setup

Use this command when you do not want to connect NIA to an external issue tracker or code platform. Pick the tab for the agent you set up in the previous step:

nia config init --issues local --code local --agent github_copilot --models stable

nia config init --issues local --code local --agent claude_code --models stable

nia config init --issues local --code local --agent opencode --models stable

You can customize model selection with the --models flag:

# Use balanced profile (recommended for most users)
nia config init --agent github_copilot --models balanced

# Use the lite profile for lower-cost experimentation
nia config init --agent opencode --models lite

Note: When you omit --models, NIA uses the stable profile by default.

After initialization, confirm that these files exist:

• .nia/config/agents.toml, which selects the AI coding agent.
• .nia/config/project.toml, which contains project metadata that you must complete.
• .nia/config/toolchain.toml when you selected an issue tracker or code platform.

6. Configure Project Metadata.

Open .nia/config/project.toml and replace the sample values with details about your project. NIA uses this metadata to give the agent reliable information about your language, framework, tests, and package manager.

Use this template as a starting point:

schema_version = "1.0.0"

[project]
name = "my-project"
description = "Brief description of your project"
language = "Rust"
framework = "clap, tokio"
testing_framework = "cargo test"
package_manager = "cargo"

All fields are required. Update them to match your project:

• name - Your project name
• description - Brief project description
• language - Primary programming language (e.g., “Rust”, “TypeScript”, “Python”)
• framework - Framework(s) used (e.g., “axum, tokio”, “React, Next.js”)
• testing_framework - Testing framework (e.g., “cargo test”, “Jest”, “pytest”)
• package_manager - Package manager (e.g., “cargo”, “npm”, “pip”)

For detailed configuration options including custom fields and monorepo setup, see Project Setup.

After you complete the project metadata, validate the configuration:

nia config validate

If validation succeeds, NIA reports:

Configuration is valid

7. View Available Commands.

Nia includes a command-line interface (CLI) that provides access to its available features and operations. You can use the built-in help system to discover available commands, view command descriptions, and learn how to use specific functionality.

To display a list of all available commands, run:

nia --help

The help output includes:

• Available commands and their purpose
• Global options that apply to all commands
• Command syntax and usage information
• Examples for common operations

Use this command whenever you want to discover available capabilities or verify the correct syntax for a command.

Most commands provide their own detailed help. To view the available options, arguments, and examples for a specific command, append the –help option to the command name:

nia issue --help
nia config --help

Nia includes comprehensive documentation that you can access offline:

nia guide

This will open the full user guide in your default web browser.

Run Your First Workflow Command

Use the issue, code, and pull request workflows to address an existing issue from planning through pull request review. Run these commands from the root of the configured project.

1. Set the issue context.

Replace 14 with the identifier of the existing issue or work item:

nia config set-issue 14
nia config show-context

The issue workflow requires an Issue ID. You can set the same context with the NIA_ISSUE_ID environment variable instead:

export NIA_ISSUE_ID=14

The context command reports the current Issue ID. If NIA reports that an Issue ID is required, set it with one of these methods before continuing.

2. Generate and review the implementation plan.

Create the implementation plan for the selected issue:

nia issue plan

The standard plan uses the software_architect role and writes its output under .nia/work/job_14/code/. A full plan can include README.md, research.md, tasks.md, and one or more phase files. For a simple change, you can request the lightweight plan format instead:

nia issue plan --lite

Review the generated plan files, especially the implementation approach in README.md, the decisions and alternatives in research.md when present, the checklist in tasks.md, and the phase files. Refine the plan when requirements, risks, dependencies, or verification steps are missing:

nia issue plan --edit

Use focused instructions with the edit operation when needed:

nia issue plan --edit "Include the required test and validation steps"

Do not start implementation until the plan reflects the approved approach. The code workflow validates the required plan files before it invokes the coding agent.

3. Implement the approved plan.

Use the plan to create the implementation and tests:

nia code create

The create operation uses the issue-linked plan, applies changes to the project files, and writes task progress to tasks.md. If the implementation needs a targeted correction, provide fix instructions with the documented fix modifier:

nia code create --fix "Address the failing validation identified during implementation"

4. Build, test, and review the implementation.

Run the build and test workflows after implementation:

nia code build
nia code test

The build workflow writes diagnostic results to .nia/work/job_14/code/build_report.md. The test workflow writes its test-results analysis to the Code job directory. Review the terminal results and generated reports, and fix any failures before continuing.

Review the implementation against the issue plan:

nia code review

The standard review writes review.md to .nia/work/job_14/code/. If the review identifies issues, run the review auto-fix workflow with the required severity scope:

nia code review --auto-fix issues

Run nia code review before --auto-fix so that the current review.md exists. You can use critical, major, minor, suggestions, or all when a narrower or broader scope is appropriate. After applying fixes, run nia code build, nia code test, and nia code review again and resolve remaining failures or findings. Use specific --edit or --fix instructions when a workflow needs clarification.

5. Create and publish the pull request.

NIA does not provide a standalone built-in operation for creating a pull request. Use your configured code management system to create the pull request for the implementation changes, then note its identifier. The pull request must be associated with the issue.

Set the pull request context after the pull request exists. Replace 456 with its identifier:

nia config set-pr 456
nia config show-context

For a PR-specific workflow, both the Issue ID and PR ID are required. You can set them with environment variables instead:

export NIA_ISSUE_ID=14
export NIA_PR_ID=456

Draft the pull request description from the changes and associated issue:

nia pr draft

The standard operation writes pull_request.md under .nia/work/job_14/pr/pr_456/. Review and refine the local description as needed:

nia pr draft --edit

Publish the reviewed description to the existing pull request:

nia pr publish

This updates only the pull request description and preserves metadata such as its state, labels, and reviewers. It does not create the pull request.

6. Review the pull request and address feedback.

Run the pull request review with both the issue and pull request contexts set:

nia pr review

The standard review analyzes status checks, code quality, reviewer comments, and merge conflicts. It writes reports such as pr_review.md, status_check_fixes.md, code_quality_improvements.md, and conflict reports under .nia/work/job_14/pr/pr_456/. Use the lightweight review when you need only blocking issues, failing checks, and merge conflicts:

nia pr review --lite

Review the findings and address the requested changes in the project. Validate all resulting changes locally with nia code build, nia code test, and the relevant code review workflow, then update the pull request through your configured code management system. Rerun nia pr review until the actionable issues and reviewer feedback are resolved. Treat high-risk merge conflicts as escalation items; NIA does not resolve them automatically.

Stop here. Do not run a merge operation: merging the pull request is not part of this workflow. The documented nia pr merge operation prepares a pull request for merging but does not perform the final merge; complete any eventual merge separately through the configured code management system after the required approvals and checks.

7. Expected result.

The selected issue has a reviewed implementation plan, the planned changes and tests are applied, the build and test workflows report their results, and code review findings are resolved. A pull request exists in the configured code management system with a reviewed description, and nia pr review reports the remaining status checks, code-quality findings, reviewer feedback, and merge conflicts. The pull request remains unmerged.

Tip: To see the generated prompt and complete agent response when troubleshooting, inspect the workflow trace under .nia/work/ or run nia trace list.

8. Verify your success.

You have completed the quick start when all of the following are true:

• nia --version prints a version number.
• The selected AI coding agent’s version and authentication checks succeed.
• .nia/config/project.toml exists and describes your project.
• nia config validate completes successfully.
• nia status does not report a blocking installation or authentication problem.
• nia config set-issue 14 sets the issue context without an error.
• nia issue plan creates an implementation plan for the selected issue.
• nia issue draft creates a local issue draft that you can open and review.

If a check fails, fix that check before continuing. Common causes include an old PowerShell version on Windows, an agent executable missing from PATH, incomplete agent authentication, or sample values left in .nia/config/project.toml.

Automate the Whole Journey with One Command

You just ran the Issue-to-PR lifecycle step by step — planning, implementation, build, test, review, and pull request. NIA can orchestrate that entire sequence for you as a single, stateful workflow.

This is the payoff: nia workflow run issue-to-pr. With the issue context set, this one command chains every step you performed by hand — nia issue plan, nia code create, nia code build, nia code test, nia code review, and the pull request operations — into a resumable state machine with approval gates, automatic retries, and a full audit trail. It is the recommended way to run the workflow once you are comfortable with the individual steps.

Set the issue context, then run the workflow:

nia config set-issue 14
nia workflow run issue-to-pr

Useful options:

# Skip approval gates for CI/automation
nia workflow run issue-to-pr --bypass-approvals

# Validate the workflow without executing it
nia workflow run issue-to-pr --dry-run

# Resume an interrupted run from a specific step
nia workflow run issue-to-pr --start-from create_code

The workflow pauses at approval gates so you stay in control, and it resumes automatically if a run is interrupted. See Introduction to Workflows for the built-in workflows, states, and transitions.

Summary

You installed NIA, connected an AI coding agent, initialized NIA in a project, completed the required project metadata, validated the configuration, and ran your first workflow.

Next steps

• Automate the Issue-to-PR lifecycle with nia workflow run issue-to-pr instead of running each step by hand.
• Configure an AI coding agent to change agents, commands, models, or prompt formats.
• Configure project metadata for monorepos, shared context, configuration locks, and custom fields.
• Explore issue workflows to review, plan, publish, or split issues.
• Review the command reference for targets, operations, flags, and modifiers.
• Troubleshoot common issues when installation, configuration, or workflow execution fails.

Installation

Nia CLI is a Rust-based command-line utility for agentic software development life cycle (SDLC) workflows. This article explains how to select a supported platform, download and install Nia, verify the installation, and remove it when necessary.

Before You Begin

Use the following sequence to complete the installation:

1. Check the prerequisites and confirm your platform support tier.
2. Download Nia from the public release repository.
3. Choose the recommended quick install, a manual release asset, or a Linux package.
4. Install any required companion software described in this article.
5. Verify that the nia command runs in a new terminal.

The quick-install scripts are the recommended option for most users. Use the manual, package, or container procedures when your environment requires them.

Prerequisites

Environment Requirements

WARNING: BETA SOFTWARE WARNING

Nia is beta software with autonomous agent capabilities. Before installing, understand the following:

Autonomous Actions

Nia can perform the following actions without individual confirmation:

• Command Execution: Run shell commands on your system
• File Modifications: Create, edit, and delete files in your workspace
• Git Operations: Create commits, branches, and push changes
• Network Calls: Make HTTP requests to external services and APIs

Recommended Environment

Install and run Nia ONLY in isolated development environments:

User Responsibility

You are responsible for:

1. Reviewing agent output before accepting changes
2. Configuring constraints via workflow configuration
3. Limiting scope using project.toml settings
4. Validating actions in code review before merging

For information on configuring agent behavior, see:

• Workflow Configuration
• Agent Setup

System Requirements

Before installing Nia CLI, ensure you have:

• A 64-bit operating system (Linux, macOS, or Windows)
• Terminal/command prompt access
• Internet connection (for initial download)
• PowerShell 6 or later (Windows only) — Windows ships with PowerShell 5.1 by default, which is not compatible with nia. Install PowerShell 7 via:
  • WinGet: winget install Microsoft.PowerShell.
  • PowerShell GitHub Releases: Download PowerShell from PowerShell GitHub Releases.

Related Documentation

• Workflow Configuration: Configure workflow behavior and constraints
• Agent Setup: Configure AI agent behavior
• Troubleshooting: Common issues and solutions

Platform Support

Nia CLI is available for the following platforms:

Support Tiers

Platform Matrix

Note: Windows Server editions use the same binary as Windows 11 but may require additional configuration. See Installing on Windows Server.

PowerShell Requirement: All Windows platforms (Windows 10, 11, Server 2016-2025) require PowerShell 6 or later. Windows ships with PowerShell 5.1 by default, which is not compatible. See Prerequisites for installation instructions.

Version Compatibility

Legend:

• ✅ = Fully supported and tested
• ⚠️ = May work but not guaranteed, requires community validation or workarounds

Important: All Windows editions require PowerShell 6 or later. Older PowerShell versions (5.1 and earlier) are not supported regardless of Windows version.

Installation Methods

Use the Quick Installer

The quick installer detects the release asset for your platform and provides the shortest installation path. Nia releases are published in the public telerik/project-nia repository.

Install with GitHub CLI

Linux/macOS:

gh release download --repo telerik/project-nia --pattern 'install.sh' && sh install.sh

Windows (PowerShell 6+):

gh release download --repo telerik/project-nia --pattern 'install.ps1'
.\install.ps1

Choose Installer Options

After downloading the installer, pass options to select a release channel, version, destination, or output mode:

Linux/macOS:

gh release download --repo telerik/project-nia --pattern 'install.sh'
sh install.sh --version 4.0.1              # Install specific version
sh install.sh --pre-release                 # Install pre-release
sh install.sh --install-dir ~/.local/bin   # Custom directory
sh install.sh --skip-verify                # Skip verification (not recommended)
sh install.sh --quiet                      # Quiet mode for CI/CD

Windows PowerShell:

gh release download --repo telerik/project-nia --pattern 'install.ps1'
.\install.ps1 -Version '4.0.1'             # Install specific version
.\install.ps1 -PreRelease                  # Install pre-release
.\install.ps1 -InstallDir "$env:LOCALAPPDATA\Programs\nia"  # Custom directory
.\install.ps1 -SkipVerify                  # Skip verification (not recommended)
.\install.ps1 -Quiet                       # Quiet mode for CI/CD

Install from a Binary Release

Use a binary release when you need to manage the executable yourself or distribute it through an internal software process. Download the asset for your operating system and architecture, then follow the matching procedure.

Install on Linux (x86_64)

# Download latest release
gh release download --repo telerik/project-nia --pattern 'nia-*-x86_64-linux'
chmod +x nia-*-x86_64-linux
sudo mv nia-*-x86_64-linux /usr/local/bin/nia
nia --version

Install on Linux (aarch64/ARM64)

For ARM64 Linux systems (e.g., AWS Graviton, Raspberry Pi 4+, Linux containers on Apple Silicon):

# Download latest release
gh release download --repo telerik/project-nia --pattern 'nia-*-aarch64-linux'
chmod +x nia-*-aarch64-linux
sudo mv nia-*-aarch64-linux /usr/local/bin/nia
nia --version

Note: Use this binary for Linux ARM64 systems and containers. For native macOS execution on Apple Silicon, use the aarch64-darwin binary instead.

Detect Your macOS Architecture

# Check your Mac's architecture
uname -m
# Output: x86_64 = Intel Mac
# Output: arm64 = Apple Silicon Mac (M1/M2/M3/M4)

Install on macOS (Intel x86_64)

For Intel Macs:

# Download latest release
gh release download --repo telerik/project-nia --pattern 'nia-*-x86_64-darwin'

# Make executable
chmod +x nia-*-x86_64-darwin

# Remove macOS quarantine attribute (required for unsigned binaries)
xattr -d com.apple.quarantine nia-*-x86_64-darwin

# Alternative: Control-click the file in Finder → Open → confirm

# Move to PATH
sudo mv nia-*-x86_64-darwin /usr/local/bin/nia

# Verify installation
nia --version

Note: macOS Gatekeeper will initially block the binary because it’s not signed with an Apple Developer certificate. Use the xattr command or Control-click method to bypass this security warning. This is safe for nia as all binaries are GPG signed for verification.

Install on macOS (Apple Silicon aarch64)

For Apple Silicon Macs (M1/M2/M3/M4):

# Download latest release
gh release download --repo telerik/project-nia --pattern 'nia-*-aarch64-darwin'

# Make executable
chmod +x nia-*-aarch64-darwin

# Remove macOS quarantine attribute (required for unsigned binaries)
xattr -d com.apple.quarantine nia-*-aarch64-darwin

# Alternative: Control-click the file in Finder → Open → confirm

# Move to PATH
sudo mv nia-*-aarch64-darwin /usr/local/bin/nia

# Verify installation
nia --version

Note: Apple Silicon Macs can run Intel binaries via Rosetta 2, but native aarch64 binaries provide better performance. Always use the aarch64 version for Apple Silicon.

Install on Windows 11 Client

Note: These instructions are for Windows 11 desktop/laptop systems. For Windows Server, see Windows Server Installation below.

Prerequisite: Verify you have PowerShell 6 or later before proceeding:

$PSVersionTable.PSVersion.Major  # Must be 6 or higher

If you see 5, install PowerShell 7: winget install Microsoft.PowerShell, then run commands in the new pwsh terminal.

# Download latest release
gh release download --repo telerik/project-nia --pattern 'nia-*-x86_64-windows.exe'

# Create programs directory if it doesn't exist
New-Item -ItemType Directory -Force -Path "$env:LOCALAPPDATA\Programs"

# Move to local programs directory
Move-Item nia-*-x86_64-windows.exe "$env:LOCALAPPDATA\Programs\nia.exe"

# Add to user PATH (if not already present)
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
if ($userPath -notlike "*$env:LOCALAPPDATA\Programs*") {
    [Environment]::SetEnvironmentVariable("Path", "$userPath;$env:LOCALAPPDATA\Programs", "User")
}

# Restart PowerShell, then verify:
nia --version

Install on Windows Server

Windows Server editions (2019, 2022, 2025) use the same binary as Windows 11 but require additional steps due to stricter default security policies.

Support Level: Windows Server 2025 is Tier 1 (Fully Supported), Server 2022 is Tier 2 (Supported), and Server 2019/2016 are Tier 3 (Community Supported). See Platform Support for details.

PowerShell Requirement: Windows Server ships with PowerShell 5.1, which is not compatible with nia. You must install PowerShell 7 before proceeding:

# Check current version
$PSVersionTable.PSVersion.Major  # Must be 6 or higher

# Install PowerShell 7 (requires admin)
winget install Microsoft.PowerShell

# After installation, use pwsh.exe instead of powershell.exe
pwsh

All subsequent commands must be run in pwsh (PowerShell 7), not powershell (PowerShell 5.1).

Download the Binary

# Download latest release
gh release download --repo telerik/project-nia --pattern 'nia-*-x86_64-windows.exe'

If gh (GitHub CLI) is not available, download manually from GitHub Releases.

Create the Installation Directory

# Create program directory (run as Administrator)
New-Item -ItemType Directory -Force -Path "C:\Program Files\Nia"

# Move binary to installation directory
Move-Item nia-*-x86_64-windows.exe "C:\Program Files\Nia\nia.exe"

Add Nia to the System PATH

# Add to system PATH (run as Administrator)
$niaPath = "C:\Program Files\Nia"
$currentPath = [Environment]::GetEnvironmentVariable("Path", "Machine")

if ([string]::IsNullOrEmpty($currentPath)) {
    # No existing PATH: set it to the Nia directory
    $newPath = $niaPath
} elseif ($currentPath.Split(';') -notcontains $niaPath) {
    # Append Nia directory if it is not already present
    $newPath = "$currentPath;$niaPath"
} else {
    # Nia directory already present: leave PATH unchanged
    $newPath = $currentPath
}
[Environment]::SetEnvironmentVariable("Path", $newPath, "Machine")

# Restart PowerShell to apply changes

Important: On Windows Server, add to System PATH rather than User PATH for consistent behavior across all sessions and services.

Verify the Installation

# Open a new PowerShell window, then verify:
nia.exe --version

# If the above fails, try with explicit path:
& "C:\Program Files\Nia\nia.exe" --version

Note: Always use nia.exe (with extension) in scripts and automation on Windows Server. The extension-less nia command may not resolve correctly in all contexts.

Handle Security Warnings

If you encounter security warnings, see Windows Server Troubleshooting.

Common scenarios:

• SmartScreen blocking execution
• Execution Policy restrictions
• Group Policy blocking unsigned binaries

Install on Server Core

For Windows Server Core (no GUI):

# All steps above work in Server Core
# Verification:
nia.exe --version

# If needed, bypass SmartScreen via PowerShell:
Unblock-File -Path "C:\Program Files\Nia\nia.exe"

Resolve the Nia Command on Windows

Understanding how Windows resolves the nia command helps avoid common issues:

Choose a Command Format

Follow Command Recommendations

For Interactive Use:

• Windows 11: nia usually works
• Windows Server: Use nia.exe for reliability

For Scripts and Automation:

# Recommended - explicit extension
nia.exe config validate

# Most reliable - full path
& "C:\Program Files\Nia\nia.exe" config validate

For CI/CD Pipelines:

# GitHub Actions example
- name: Run Nia
  run: nia.exe config validate
  shell: pwsh

Troubleshoot Command Resolution

If nia is not recognized:

1. Check PATH:

   $env:PATH -split ';' | Where-Object { $_ -like '*nia*' }
   

2. Check PATHEXT (should include .EXE):

   $env:PATHEXT
   # Expected: .COM;.EXE;.BAT;.CMD;...
   

3. Locate the binary:

   Get-Command nia.exe -ErrorAction SilentlyContinue | Select-Object Source
   

4. Use explicit path as workaround:

   & (Get-Command nia.exe).Source --version
   

Note: The gh release download examples require an authenticated GitHub CLI. The repository and its release assets are public; use the direct-download quick installer if you do not use GitHub CLI.

Install a Linux Package

For supported Linux distributions, use the package that matches your architecture. Package installation integrates Nia with the distribution’s package manager and avoids manually moving the binary.

Debian or Ubuntu (x86_64)

# Download latest release
gh release download --repo telerik/project-nia --pattern 'nia_*_amd64.deb'

# Install package
sudo dpkg -i nia_*_amd64.deb

# Verify installation
nia --version

Debian or Ubuntu (ARM64)

# Download latest release
gh release download --repo telerik/project-nia --pattern 'nia_*_arm64.deb'

# Install package
sudo dpkg -i nia_*_arm64.deb

# Verify installation
nia --version

RHEL, Fedora, or CentOS (x86_64)

# Download latest release
gh release download --repo telerik/project-nia --pattern 'nia-*x86_64.rpm'

# Install package (Fedora/RHEL 8+)
sudo dnf install ./nia-*x86_64.rpm

# Or for older systems
sudo rpm -i nia-*x86_64.rpm

# Verify installation
nia --version

RHEL, Fedora, or CentOS (ARM64)

# Download latest release
gh release download --repo telerik/project-nia --pattern 'nia-*aarch64.rpm'

# Install package (Fedora/RHEL 8+)
sudo dnf install ./nia-*aarch64.rpm

# Or for older systems
sudo rpm -i nia-*aarch64.rpm

# Verify installation
nia --version

Install GitHub Copilot CLI on Windows

If you use GitHub Copilot CLI for AI-powered workflows, choose an installation method that lets Nia invoke the executable without the command-line length limitations of Windows Command Shell. Nia also supports OpenCode and Claude Code; see AI Coding Agent Setup for the supported agents and their provider-specific prerequisites.

Supported Installation Methods

On Windows, we recommend installing GitHub Copilot CLI using one of these methods:

Install with WinGet (Recommended)

winget install GitHub.CopilotCLI

This installs a native Windows executable that works reliably with Nia.

Do Not Use the GitHub CLI Extension on Windows

Warning: The GitHub CLI extension method (gh extension install github/gh-copilot) is not supported by nia on Windows.

The gh copilot command uses Windows Command Shell (cmd.exe) internally, which has an ~8191 character command-line limit. This limit is frequently exceeded with nia’s prompts that include multi-file context, detailed instructions, and XML formatting.

Symptoms of this issue:

• “The command line is too long” errors
• “batch file arguments are invalid” errors
• Truncated or failed responses from Copilot

If you have gh extension installed:

1. Install via WinGet instead: winget install GitHub.CopilotCLI
2. Or use npm with automatic wrapper discovery (see below)
3. Remove any command = "gh" from your .nia/config/agents.toml

The gh CLI itself works fine for other purposes—only the Copilot extension integration with nia is affected.

Install with npm

You can install GitHub Copilot CLI via npm:

npm install -g @githubnext/github-copilot-cli

Automatic Wrapper Discovery: Nia automatically detects npm installations and parses the .cmd wrapper scripts to find the underlying Node.js entry point. This allows nia to invoke Node.js directly, bypassing Windows Command Shell limitations.

How it works:

1. Nia finds copilot.cmd in your PATH
2. Parses the wrapper to extract the Node.js script path
3. Invokes node <script> directly instead of using the wrapper
4. Logs the discovery process (visible with nia status --verbose)

No configuration needed - wrapper discovery is automatic. Nia will log:

Successfully parsed wrapper script, will invoke Node.js directly

If wrapper parsing fails, nia falls back to using the wrapper directly and logs a warning. In that case, consider switching to the WinGet installation.

Verify GitHub Copilot CLI

After installation, verify everything is working:

# Check Nia can find and use the agent
nia status

# Test a simple command
nia issue draft --lite

Configure an Alternative Copilot Command

In most cases, no configuration is needed - nia automatically discovers and uses the best invocation method.

If you need to specify a direct path, you can configure it in .nia/config/agents.toml:

schema_version = "2.1.0"

[agent]
default = "github_copilot"

[agent.github_copilot]
# Specify a direct path to executable
command = "C:\\Program Files\\GitHub Copilot CLI\\copilot.exe"

model = "gpt-4"

Note: Do not use command = "gh" - this is not supported and will result in a configuration error.

See Custom Agent Configurations for more details.

Verify the Installation

Run the version command from a new terminal to confirm that Nia is on your PATH:

nia --version

You should see output similar to:

nia 4.1.1

Container Deployment

ARM64 Containers on Apple Silicon (Docker/Podman)

When running Linux containers on Apple Silicon Macs (M1/M2/M3/M4), use the Linux aarch64 packages. The macOS aarch64 binary is for native macOS execution and cannot run inside a Linux container.

RHEL-Based Dockerfile

FROM fedora:latest

# Install curl for downloading nia
RUN dnf install -y curl ca-certificates

# Download and install nia (ARM64)
RUN curl -fsSL -o /tmp/nia.rpm \
   $(curl -s https://api.github.com/repos/telerik/project-nia/releases/latest \
    | grep "browser_download_url.*aarch64.rpm" | cut -d'"' -f4) \
    && dnf install -y /tmp/nia.rpm \
    && dnf clean all \
    && rm /tmp/nia.rpm

# Verify installation
RUN nia --version

Debian-Based Dockerfile

FROM ubuntu:latest

# Install curl for downloading nia
RUN apt-get update && apt-get install -y curl ca-certificates

# Download and install nia (ARM64)
RUN curl -fsSL -o /tmp/nia.deb \
   $(curl -s https://api.github.com/repos/telerik/project-nia/releases/latest \
    | grep "browser_download_url.*arm64.deb" | cut -d'"' -f4) \
    && apt-get install -y /tmp/nia.deb \
    && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/nia.deb

# Verify installation
RUN nia --version

Optimize the Image with a Multi-Stage Build

For production deployments, use multi-stage builds to reduce final image size:

RHEL-Based Image

# Build stage - download package
FROM fedora:latest as builder
RUN dnf install -y curl jq
RUN curl -fsSL -o /tmp/nia.rpm \
   $(curl -s https://api.github.com/repos/telerik/project-nia/releases/latest \
    | jq -r '.assets[] | select(.name | contains("aarch64.rpm")) | .browser_download_url')

# Runtime stage - minimal image
FROM fedora:latest
COPY --from=builder /tmp/nia.rpm /tmp/nia.rpm
RUN dnf install -y /tmp/nia.rpm && dnf clean all && rm /tmp/nia.rpm
RUN nia --version

Debian-Based Image

# Build stage - download package
FROM ubuntu:latest as builder
RUN apt-get update && apt-get install -y curl jq
RUN curl -fsSL -o /tmp/nia.deb \
   $(curl -s https://api.github.com/repos/telerik/project-nia/releases/latest \
    | jq -r '.assets[] | select(.name | contains("arm64.deb")) | .browser_download_url')

# Runtime stage - minimal image
FROM ubuntu:latest
COPY --from=builder /tmp/nia.deb /tmp/nia.deb
RUN apt-get update && apt-get install -y /tmp/nia.deb && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/nia.deb
RUN nia --version

Tip: Multi-stage builds eliminate curl and jq from the final image, reducing size and attack surface.

Choose the Container Binary

Important: The macOS aarch64 binary (aarch64-darwin) is for native macOS execution only. It will not work inside Linux containers, even on Apple Silicon Macs. Use the Linux aarch64 binary or packages for container deployments.

Next Steps

• Quick Start Guide - Get started with Nia in 5 minutes

Troubleshoot Installation Problems

Start with these checks when installation does not complete successfully:

• Command not found: Ensure the binary is in your PATH or use the full path to execute
• Permission denied: Run with appropriate permissions (e.g., sudo on Linux/macOS)
• Binary won’t execute: Verify file permissions (chmod +x nia on Unix systems)

Troubleshoot macOS

Gatekeeper Blocks the Binary

Problem: “cannot be opened because it is from an unidentified developer”

Solution:

Method 1 - Remove quarantine attribute (recommended):

xattr -d com.apple.quarantine /usr/local/bin/nia
# Or for the downloaded file:
xattr -d com.apple.quarantine nia-*-darwin

Method 2 - Control-click bypass:

1. Locate the file in Finder
2. Control-click (or right-click) the file
3. Select “Open” from the menu
4. Click “Open” in the warning dialog
5. The file will now run without warnings

Method 3 - System Settings (macOS 13+):

1. Try to run the binary (it will be blocked)
2. Go to System Settings → Privacy & Security
3. Scroll to “Security” section
4. Click “Open Anyway” next to the blocked app message
5. Re-run the binary

Why this happens: macOS applies Gatekeeper checks to downloaded applications. Nia release assets include signatures and checksums for authenticity verification.

Binary Not in PATH

Problem: nia: command not found

Solution:

Check if /usr/local/bin is in your PATH:

echo $PATH | grep /usr/local/bin

If not present, add to your shell configuration:

For Zsh (default on macOS 10.15+):

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

For Bash:

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile

For Fish:

fish_add_path /usr/local/bin

Permission Denied

Problem: Permission denied when running nia

Solution:

Ensure the binary is executable:

chmod +x /usr/local/bin/nia

If you moved the file without sudo, you might not have write permissions:

ls -la /usr/local/bin/nia
# Should show: -rwxr-xr-x

# Fix if needed:
sudo chmod 755 /usr/local/bin/nia

Wrong Architecture Downloaded

Problem: Binary doesn’t run or shows architecture errors

Solution:

1. Check your Mac’s architecture:

   uname -m
   # x86_64 = Intel → Download x86_64-darwin binary
   # arm64 = Apple Silicon → Download aarch64-darwin binary
   

2. Check downloaded binary architecture:

   file /usr/local/bin/nia
   # Should show: Mach-O 64-bit executable x86_64 (for Intel)
   # Or: Mach-O 64-bit executable arm64 (for Apple Silicon)
   

3. Download the correct version for your architecture.

Terminal Colors Not Working

Problem: Colors appear broken or don’t display

Solution:

1. Verify terminal supports colors:

   echo $TERM
   # Should be: xterm-256color or similar
   

2. Enable colors in Terminal.app:

   • Terminal → Settings → Profiles → Advanced
   • Ensure “Declare terminal as” is set to xterm-256color

3. For iTerm2, colors should work by default.

4. Force color output:

   export CLICOLOR_FORCE=1
   nia --help
   

Unicode Characters Not Displaying

Problem: Progress bars or special characters show as ? or boxes

Solution:

1. Verify terminal encoding:

   locale
   # LANG should end with UTF-8 (e.g., en_US.UTF-8)
   

2. Set UTF-8 encoding:

   export LANG=en_US.UTF-8
   export LC_ALL=en_US.UTF-8
   

3. Add to shell profile to make permanent:

   echo 'export LANG=en_US.UTF-8' >> ~/.zshrc
   source ~/.zshrc
   

Slow Performance on Apple Silicon

Problem: Nia runs slower than expected on M1/M2/M3/M4

Possible Cause: Running Intel binary via Rosetta 2 instead of native aarch64 binary.

Solution:

1. Check what you’re running:

   file $(which nia)
   # Should show: Mach-O 64-bit executable arm64
   # If shows x86_64, you're running the Intel version via Rosetta
   

2. Download and install the aarch64-darwin binary:

   gh release download --repo telerik/project-nia --pattern 'nia-*-aarch64-darwin'
   # Follow installation instructions above
   

GPG Verification Fails

Problem: GPG signature verification fails

Solution:

1. Import the public GPG key:

   # Download public key from release
   gh release download --repo telerik/project-nia --pattern 'public-key.asc'
   gpg --import public-key.asc
   

2. Verify signature:

   gpg --verify nia-*-darwin.asc nia-*-darwin
   

3. If verification still fails, re-download both the binary and signature.

Quick Install Script Issues

Problem: Installation script fails with authentication error

Solution:

1. Authenticate using GitHub CLI:

   gh auth login
   

2. Verify authentication works:

   gh auth status
   

Problem: Installation script fails with “Unsupported platform” error

Solution:

1. Check your platform and architecture:

   # Linux/macOS
   uname -s -m
   

   # Windows
   $env:PROCESSOR_ARCHITECTURE
   

2. Supported platforms are:

   • Linux: x86_64, aarch64
   • macOS: x86_64, aarch64 (Apple Silicon)
   • Windows: x86_64 (AMD64) only

3. If your platform is not supported, use the manual binary installation method above.

Problem: Checksum verification fails

Solution:

1. Try re-running the installation (transient network issues):

   curl -fsSL https://.../ install.sh | sh
   

2. If it continues to fail, skip verification (not recommended):

   curl -fsSL https://.../ install.sh | sh -s -- --skip-verify
   

3. Report persistent checksum issues to the Nia CLI team.

Problem: Windows PowerShell version error

Solution:

The installation script requires PowerShell 6 or later. Windows includes PowerShell 5.1 by default.

1. Install PowerShell 7:

   # Using winget
   winget install Microsoft.PowerShell
   
   # Or download from: https://github.com/PowerShell/PowerShell/releases
   

2. Open a new PowerShell 7 terminal and retry installation.

Problem: macOS Gatekeeper blocks the binary

Solution:

The installation script automatically removes the quarantine attribute. If you still see a warning:

1. Open System Preferences → Security & Privacy
2. Click “Open Anyway” next to the nia warning
3. Or manually remove the quarantine attribute:

   sudo xattr -d com.apple.quarantine /usr/local/bin/nia
   

GitHub CLI Authentication Fails

Problem: gh command fails with authentication error

Solution:

1. Authenticate with GitHub:

   gh auth login
   

2. Select “GitHub.com” and follow the prompts to authenticate.

3. Verify authentication:

   gh auth status
   

For more help, see the Troubleshooting Guide.

Uninstall Nia CLI

Remove the Nia executable from the location where you installed it. The commands below cover the default and custom installation locations.

Remove Nia on Linux or macOS

# If installed to default location
sudo rm -f /usr/local/bin/nia

# If installed to custom location
rm -f /path/to/custom/dir/nia

Remove Nia on Windows

# If installed to default location
Remove-Item "C:\Program Files\Nia\nia.exe" -Force

# If installed to custom location
Remove-Item "C:\Path\To\Custom\Dir\nia.exe" -Force

Note: You may need administrator/sudo privileges depending on the installation location.

To also remove Nia’s configuration and data directories, run the matching command:

# Linux/macOS
rm -rf ~/.nia

# Windows
Remove-Item "$env:USERPROFILE\.nia" -Recurse -Force

Shell Completions

Shell completions let you press Tab to discover NIA commands, subcommands, and options instead of typing each name from memory. NIA generates completion scripts from the command-line interface, including workflow commands available in your configuration.

Before You Begin

Make sure that:

• NIA is installed and available on your PATH.
• You know which shell starts when you open your terminal.
• You have permission to create or edit that shell’s profile file.
• You run the installation command from the same environment where you use NIA, such as a local terminal, a remote shell, or a development container.

The installer edits a shell profile. It does not install a separate package or modify NIA project configuration.

Supported Shells

NIA supports these shells:

Use the shell value, not the display name, in nia shell install, nia shell generate, and nia shell uninstall.

Understand How Completions Work

NIA generates completions each time you run nia shell generate <shell>. The generated script is based on the CLI that NIA can load in that environment:

• Utility commands, such as config, guide, and shell.
• Workflow commands loaded from the built-in and user command configuration.
• Custom commands when the workflow registry loads successfully.

The installer adds a command to your profile that generates and loads completions when the shell starts. This means completions can reflect command changes after you restart or reload the shell. If NIA cannot load the workflow registry, the generated completion set may contain only utility commands until you fix the configuration.

Install Completions Automatically

Run the command for your shell:

# Bash
nia shell install bash

# Zsh
nia shell install zsh

# Fish
nia shell install fish

# PowerShell
nia shell install powershell

The installer performs these actions:

1. Detects the profile path for the selected shell.
2. Shows the line it plans to add and asks for confirmation.
3. Creates a timestamped backup when the profile already exists.
4. Adds the completion command to the profile.

Restart the shell after installation. You can also reload the profile manually when your shell supports it.

Install Completions Manually

Use manual mode when you want to inspect the profile path and generated command before editing your profile:

nia shell install bash --manual

Replace bash with zsh, fish, or powershell for another shell. Manual mode prints the line to add and the reload instruction; it does not modify the profile or create a backup.

Generate a Completion Script

Use generate when you want to view, redirect, or load a script yourself:

nia shell generate bash

The command writes the Bash completion script to standard output. Replace bash with the target shell. For example, to load Bash completions only in the current shell session:

source <(nia shell generate bash)

This command does not edit a profile. Use nia shell install <shell> for persistent profile-based setup.

Reload Completions

After automatic or manual installation, restart the shell. To reload a profile in a POSIX shell, use the profile path that NIA reported, for example:

source ~/.bashrc

For Fish, start a new Fish session or load the profile with Fish’s source command. For PowerShell, start a new session or dot-source the profile path shown by $PROFILE.

Remove Completions

Remove NIA’s completion lines from a shell profile with:

nia shell uninstall bash

Replace bash with the shell whose profile you want to change. Uninstall creates a timestamped backup when the profile exists, then removes lines added by NIA. It does not delete the backup file.

Common Scenarios

Use a Different Shell Profile

When you use more than one shell, install completions separately for each shell:

nia shell install bash
nia shell install zsh

Use the shell that matches the terminal session where you want completions.

Review the Generated Configuration

Generate a script without changing your profile:

nia shell generate zsh > nia-zsh-completions

Review the file, then remove it when you no longer need it. Redirecting the output is useful for testing or for managing profile changes through your own deployment process.

Use Completions with Custom Commands

NIA builds completions from the commands available when it generates the script. After changing user command configuration, validate the configuration and reload the shell:

nia config validate
source ~/.bashrc

If the new command is still unavailable, inspect the validation output and regenerate the script in the current shell:

source <(nia shell generate bash)

Troubleshoot Completions

Tab Completion Shows No NIA Commands

Run these checks in order:

1. Confirm that NIA is available:

   nia --version
   

2. Confirm that the profile contains the NIA completion command. Open the profile path for your shell, or use the command appropriate to your environment:

   grep "nia shell" ~/.bashrc
   

3. Reload the profile or start a new shell session.

4. Test completion by typing nia and pressing Tab.

On PowerShell, inspect $PROFILE instead of using grep. On Fish, inspect ~/.config/fish/config.fish.

The Profile Cannot Be Modified

If installation reports a permission error, check that you can write to the detected profile. Use manual mode to obtain the exact profile path:

nia shell install bash --manual

You can then add the printed line through your normal profile-management process. Avoid changing permissions or using elevated privileges unless your environment requires it.

Completions Are Missing Custom Commands

Run nia config validate and correct any configuration errors. NIA can generate workflow completions only when it can load the workflow registry. After validation succeeds, regenerate the script or restart the shell.

NIA Reports an Unsupported Shell

Use one of the supported values: bash, zsh, fish, or powershell. The installer also accepts pwsh as an alias for PowerShell.

Limitations

• NIA supports only Bash, Zsh, Fish, and PowerShell completion generation.
• Completion scripts are generated from the CLI available in the current environment. A configuration error can prevent workflow commands from appearing.
• Installing completions changes the selected shell profile for the current user. It does not configure other users, shells, machines, or containers.
• The automatic installer requires an interactive confirmation. Use --manual for a non-modifying inspection step and manage the profile change yourself.
• NIA creates backups before modifying an existing profile, but you are responsible for retaining or removing those backups according to your environment’s policies.

Related Content

• Learn how to install NIA for platform-specific prerequisites and installation methods.
• Review the command reference for available utility and workflow commands.
• Configure project metadata so workflow-generated completions include the commands available to your project.
• Troubleshoot common NIA issues when the problem is not specific to shell integration.

Configuration Overview

Nia’s configuration system provides a flexible, hierarchical approach to customizing behavior across projects and teams. Configuration files control AI agent selection, development tool integration, project metadata, and workflow customization.

Configuration Files

Nia uses TOML-based configuration files stored in .nia/config/:

Quick Links

• Configuration Files Reference - Quick reference for all config files
• Project Configuration - Configure project metadata
• Context Sources - Add context files to AI prompts
• Commit Behavior - Control commit generation
• Toolchain Configuration - Configure development tools
• Hierarchical Loading - Multi-source configuration
• Agent Skills - Customizable procedural knowledge

Getting Started

1. Initialize configuration: nia config init
2. Edit .nia/config/project.toml with project metadata
3. Configure your toolchain in .nia/config/toolchain.toml
4. Validate configuration: nia config validate

Configuration Hierarchy

Nia loads configuration from multiple locations (highest priority first):

1. Repository (.nia/config/)
2. Application (multi-repo scenarios)
3. User (~/.config/nia/)
4. System (/etc/nia/)

Settings from higher-priority sources override those from lower-priority sources. By default, only repository configuration is loaded; external sources must be explicitly enabled in project.toml for security reasons.

See Hierarchical Loading for details on multi-source configuration.

Configuration Files Reference

Quick reference for all nia configuration files, their purposes, and key fields.

File Overview

project.toml

Defines project metadata used to provide context to AI agents.

Location: .nia/config/project.toml (repository only)

Key Fields:

Related: Project Configuration

agents.toml

Configures AI agent selection and model preferences.

Location: .nia/config/agents.toml (supports hierarchical loading)

Key Fields:

Related: Agent Setup, Model Selection

toolchain.toml

Defines development tools and platforms available in your environment.

Location: .nia/config/toolchain.toml (supports hierarchical loading)

Key Fields:

Related: Toolchain Configuration

commands.toml

Customizes workflow commands with context and prompt overrides.

Location: .nia/config/commands.toml (supports hierarchical loading)

Key Fields:

Related: Workflow Schema

Initialization

Create configuration files with:

# Full initialization with all options
nia config init --issues github_issues --code github --agent github_copilot

# Minimal initialization (uses external configs)
nia config init --minimal

Validation

Check configuration validity:

nia config validate

See Also

• Hierarchical Loading - Multi-source configuration
• Configuration Overview - Getting started guide

Project Configuration

title: Project Setup meta_title: NIA Project Setup - Configure Project Metadata description: Initialize NIA, configure project metadata, validate settings, and prepare a repository for reliable AI-assisted workflows. slug: project-setup

Project Setup

NIA uses project metadata to describe your repository to its AI coding agent. This article explains how to initialize NIA, complete .nia/config/project.toml, validate the configuration, and prepare optional monorepo or context settings.

After completing the setup, your repository has valid project metadata and can load the configuration required by NIA workflows.

Prerequisites

Before you begin, prepare the following:

• NIA installed and available on your PATH.
• A project directory where you can create .nia/config/.
• Permission to create and edit files in the project directory.
• A terminal opened at the project root, such as the root of a cloned repository.
• An authenticated AI coding agent when you plan to run workflow commands. See Configure an AI coding agent for agent-specific requirements.

NIA can initialize a project outside a Git repository, but a Git repository is recommended for development workflows that inspect changes or create commits.

Before You Begin

Keep these points in mind:

• nia config init creates a default project.toml only when the file does not already exist. It does not overwrite an existing project configuration.
• The [project] table has six required fields. documentation_framework is not a required core field; add it as an optional custom field when your prompts or team process need it.
• NIA validates configuration values when it loads project.toml. Use None for a required tooling field that does not apply to your project.
• Treat project metadata as shared project configuration. Commit it to version control after reviewing the values and any sensitive custom fields.
• NIA workflows run agents autonomously and bypass approval prompts. Run NIA in a sandbox or development container, not against production systems.

Set Up Project Configuration

Complete the following steps from the project root.

Step 1: Initialize NIA

Run config init to create the .nia/ configuration structure and a default .nia/config/project.toml file.

For a local-only project configuration, run:

nia config init

To configure an AI coding agent during initialization, add --agent with a supported agent ID documented in AI coding agent setup:

nia config init --agent github_copilot

The default model profile is stable. Select another profile with --models when you configure an agent:

nia config init --agent github_copilot --models balanced

NIA creates the project file and reports project.toml in the command output. When you provide issue, ticket, or code-platform options, it also creates the corresponding toolchain configuration. The --code option requires at least one tracker option, such as --issues or --tickets.

Verify that the project file exists:

.nia/config/project.toml

If the file already exists, NIA reports that it already exists and preserves it. Edit the existing file in the next step.

Step 2: Complete Required Metadata

Open .nia/config/project.toml and replace the sample values in the [project] table.

Use this minimum valid configuration:

schema_version = "1.0.0"

[project]
name = "my-project"
description = "Brief description of the project"
language = "Rust"
framework = "None"
testing_framework = "cargo test"
package_manager = "cargo"

The required fields are:

Use non-empty values. The project name cannot exceed 100 characters, and the description cannot exceed 250 characters. The schema version must be 1.0.0.

Verify this step by checking that every required field has a value that describes the actual project. The validation step reports the exact file and field when a value is missing or invalid.

Step 3: Add Optional Metadata

Add custom fields when the agent needs project information beyond the six required fields. NIA makes custom fields available as template variables.

For example:

[project]
name = "user-service"
description = "User authentication and management service"
language = "Rust"
framework = "axum, tokio"
testing_framework = "cargo test"
package_manager = "cargo"
documentation_framework = "rustdoc"
repository = "https://github.com/example/user-service"

Custom field names can contain letters, numbers, underscores, and hyphens, but cannot start with a number or reuse a reserved core field name. Custom values must be non-empty, no longer than 250 characters, and free of control characters.

Verify custom fields by checking that each value is safe to include in an AI prompt and does not contain credentials, tokens, or other secrets.

Step 4: Configure a Monorepo

Add a [monorepo] table only when one repository contains multiple services that NIA must distinguish.

Each service requires a unique name and a unique relative path. Service metadata is optional:

[monorepo]
enabled = true

[[monorepo.services]]
name = "api"
path = "services/api"
description = "REST API service"
language = "Rust"
framework = "axum"
testing_framework = "cargo test"
package_manager = "cargo"

[[monorepo.services]]
name = "web"
path = "services/web"
description = "Frontend application"
language = "TypeScript"
framework = "React"
testing_framework = "Jest"
package_manager = "npm"

When enabled = true, define at least one service. Service paths must exist, resolve to directories, and remain inside the repository. Set enabled = false or remove the table for a single-project repository.

Verify the monorepo configuration with nia config validate. Correct duplicate service names, duplicate paths, missing directories, or paths outside the repository before continuing.

Step 5: Add Shared Context

Use [[project.context]] entries to include architecture documents, standards, or other files and directories in AI prompt context.

For example:

[[project.context]]
type = "file"
path = "docs/architecture.md"
description = "System architecture overview"

[[project.context]]
type = "directory"
path = "docs/standards"
description = "Coding standards and guidelines"

Keep paths meaningful and descriptions concise. Do not include secrets or large generated directories. Validate the configuration after adding context entries.

Step 6: Validate the Configuration

Run the validator from the project root:

nia config validate

Validation checks the available configuration files, including project.toml, toolchain.toml, agents.toml, and commands.toml. It also checks agent dependencies and workflows when those components are configured.

Successful validation ends with a message that all configuration files are valid, or that they are valid with warnings. Warnings do not block validation, but review them before running workflows.

Verify that the command exits successfully and that no configuration file reports an invalid status. When validation fails, fix the reported file and run the command again.

Step 7: Lock Configuration for Workflows

Create a configuration lock after validation succeeds:

nia config lock

This command validates the configuration again, hashes each present configuration file, and writes .nia/.config_lock. The lock enables configuration drift detection. If a locked configuration file changes, NIA blocks workflow commands until you run nia config lock again.

Verify that the command reports Configuration locked successfully and that .nia/.config_lock exists. Re-run the command after intentional changes to project, agent, toolchain, command, or workflow configuration.

Configuration Details

Project Configuration File

The project configuration file is:

.nia/config/project.toml

The top-level schema_version must be "1.0.0". The [project] table contains the required metadata, while [monorepo], [commit], [config], and custom fields are optional.

Commit Behavior

Use [commit] to set the project-wide commit instruction behavior:

[commit]
behavior = "enabled"

Supported values are:

• enabled: Include basic commit instructions. This is the default.
• tagged: Include commit instructions with NIA co-author attribution.
• disabled: Omit commit instructions globally so you manage commits yourself.

This setting is a project-wide override. Command-specific settings can also exist in agents.toml; review that file when command-level behavior matters.

External Configuration Sources

The optional [config.external_sources] section controls external configuration loading:

[config.external_sources]
enabled = true

Individual source toggles have no effect when enabled = false. Leave this section out unless your project uses externally managed configuration sources.

Verify Project Setup

Run these checks after completing the setup:

nia config validate
nia config lock
nia --help

The expected results are:

• nia config validate completes without invalid configuration results.
• nia config lock reports a successful lock and writes .nia/.config_lock.
• nia --help displays the NIA command-line interface.

If an agent is configured, also run:

nia status

Confirm that NIA detects the configured agent and its authentication state. Agent authentication is managed by the agent’s own CLI, not by the project metadata file.

Troubleshooting

project.toml Is Missing

Symptom: Validation reports that NIA cannot read .nia/config/project.toml.

Cause: NIA was not initialized in the project root, or the configuration file was removed.

Resolution: Change to the project root and run nia config init. If another .nia directory exists higher in the path, confirm that NIA resolves the intended project root before editing files.

Required Field Is Missing or Empty

Symptom: Validation reports a missing or empty project field.

Cause: One of the six required [project] fields is absent or contains only whitespace.

Resolution: Add a value for name, description, language, framework, testing_framework, and package_manager. Use None when a framework, test framework, or package manager does not apply.

Schema Version Is Unsupported

Symptom: Validation reports an unsupported schema version.

Cause: schema_version is not "1.0.0".

Resolution: Set the top-level value to schema_version = "1.0.0", then run nia config validate again.

Monorepo Validation Fails

Symptom: Validation reports duplicate services, no services, or an invalid service path.

Cause: A monorepo configuration with enabled = true requires unique service names, unique paths, and existing directories inside the repository.

Resolution: Correct the service names and relative paths, create missing service directories, or disable monorepo mode when the repository contains one project.

Configuration Lock Blocks a Workflow

Symptom: A workflow command is blocked because configuration changed after locking.

Cause: One or more files recorded in .nia/.config_lock changed after the last lock operation.

Resolution: Review the changes, validate them, and regenerate the lock:

nia config validate
nia config lock

Do not regenerate the lock until you have reviewed unexpected configuration changes.

Agent Dependency or Authentication Check Fails

Symptom: Validation or nia status reports that an agent is missing or unauthenticated.

Cause: The selected AI coding agent is not installed, is not on PATH, or has not been authenticated.

Resolution: Follow the agent installation and authentication procedures, then run nia status again. Project metadata alone cannot install or authenticate an agent.

Permission Error During Initialization

Symptom: nia config init cannot create .nia/config/ or write project.toml.

Cause: The current user cannot write to the project directory, or another process has locked the file.

Resolution: Choose a writable project directory, close applications that have the file open, or ask an administrator to grant the required directory permission. Avoid running NIA with elevated privileges unless your environment requires it.

Next Steps

After project setup is valid, continue with the task that matches your workflow:

• Configure AI coding agents to install, authenticate, and select an agent.
• Configure commit behavior to control commit instructions.
• Manage workflow context to set issue, pull request, ticket, or service context.
• Start with the Quick Start workflow to run an initial NIA command.
• Review the command reference to learn available targets and operations.

Context Sources

title: Context Configuration meta_title: NIA Context Configuration - Add Project and Workflow Context description: Configure project, workflow, operation, and command-line context sources so NIA agents can use relevant repository files during execution. slug: context-configuration

Context Configuration

Context configuration tells NIA which repository files and directories are relevant to an AI-assisted workflow. NIA resolves those paths, validates that they stay inside the repository, and passes the resulting file references to the workflow prompt.

Use context configuration to provide architecture documents, coding standards, review checklists, examples, and other project-specific references without repeating the same command-line options.

Key Concepts

NIA supports two context source types:

Each source can also include an optional description. The description explains why the source matters and is associated with the resolved files. A description can contain up to 500 characters.

NIA keeps context as resolved file paths during loading. The context loader does not read file contents into the prompt at this stage. The configured paths are available to the AI coding agent as workflow context.

Context Scope

Choose a scope based on how broadly the information applies:

Project context is rendered in the project context section. Target, operation, job, and command-line context are merged into the target-operation context section.

Prerequisites

Before you configure context, make sure that:

• NIA is installed and available on your PATH.
• You can edit the relevant .nia/config/ file.
• The files and directories you reference exist inside the repository.
• The workflow command supports the context flags when you use command-line context.
• You do not include credentials, tokens, private keys, or other sensitive files.

NIA validates context paths against the repository root. Absolute paths and relative paths are accepted only when their resolved locations remain inside that boundary.

Configure Project Context

Project context applies to every workflow command in the repository.

1. Open .nia/config/project.toml.
2. Add one [[project.context]] entry for each file or directory.
3. Set type to file or directory.
4. Set path to a path relative to the repository root.
5. Add a short description when the source purpose is not obvious.
6. Run nia config validate to check the configuration.

For example:

schema_version = "1.0.0"

[project]
name = "payment-service"
description = "Payment processing service"
language = "Go"
framework = "gin"
testing_framework = "go test"
package_manager = "go mod"

[[project.context]]
type = "file"
path = "docs/architecture.md"
description = "System architecture and design decisions"

[[project.context]]
type = "directory"
path = "docs/adr"
description = "Architecture decision records"

The file entry resolves one file. The directory entry recursively discovers eligible files below docs/adr.

Configure Target Context

Target context applies to every operation under a command target. Add it to .nia/config/commands.toml.

schema_version = "2.1.0"

[metadata]
name = "Project Commands"
version = "1.0.0"
author = "Development Team"

[[commands]]
target = "code"
description = "Code generation and review"

[[commands.context]]
type = "directory"
path = "docs/code-patterns"
description = "Reusable code patterns"

[[commands.operations]]
name = "review"
description = "Review code changes"

[commands.operations.prompts]
role = "software_architect"
task = "code_review"

NIA also accepts [[workflows]] as an alias for the command target collection for backward compatibility. Use the current [[commands]] form for new configuration.

Configure Operation Context

Operation context applies only to one operation. Add it under the operation that consumes the reference:

[[commands.operations.context]]
type = "file"
path = "docs/review-checklist.md"
description = "Required code review checks"

[[commands.operations.context]]
type = "file"
path = "docs/security-checklist.md"
description = "Security requirements for review"

Use operation context for review checklists, test requirements, merge criteria, or other references that do not apply to every operation under the target.

Add Command-Line Context

Add context for one workflow invocation with --context-file or --context-dir:

nia code review --context-file docs/hotfix-notes.md
nia code create --context-dir examples

Repeat either flag when a command needs multiple files or directories:

nia issue draft --context-file requirements.md --context-dir docs/specs

These flags are available on workflow commands, not utility commands such as nia config validate or nia status. Use --context-file with a file and --context-dir with a directory.

Validate and Use Context

Validate configuration changes before running a workflow:

nia config validate

Then run a workflow from the repository root. For example:

nia code review --context-file docs/review-notes.md

To inspect the generated prompt during troubleshooting, use the workflow’s --print-prompt debug option when that option is available in the command’s help output:

nia code review --print-prompt

The command-line reference identifies --print-prompt as a debug feature. Treat the output as potentially sensitive because it can expose paths and workflow context.

Configuration Reference

Context Source Properties

Every configured context source supports these properties:

NIA canonicalizes the path before it checks the repository boundary. A path that resolves outside the repository fails validation, including a path that escapes through .. or a symlink.

Directory Traversal Defaults

NIA applies these defaults when it traverses a directory context source:

The 100-file limit applies per directory source. The loader reports skipped files through its collected context state and logs traversal warnings when appropriate.

Runtime Behavior

NIA resolves context in this order for a workflow command:

1. Loads target context.
2. Loads operation context.
3. Loads the optional job context directory.
4. Loads files from --context-file.
5. Loads directories from --context-dir.

The loader merges these sources into the target-operation collection. It deduplicates files by canonical path, so the same resolved file appears once within that collection. Project context is loaded separately and is not merged into the target-operation collection by this deduplication step.

If a configured file or directory does not exist, NIA returns a configuration error. If a file path resolves to a directory, or a directory path resolves to a file, NIA returns a type-specific configuration error. Missing job context is optional and is skipped.

Security Considerations

Context configuration has security implications. Before configuring context sources, review the Security Guide to understand:

• Which paths should NOT be included in context (credentials, .env files, keys)
• How path validation works and its limitations
• The difference between what nia validates and what the agent can access

⚠️ Important: The AI agent can read files directly from your filesystem. Context paths tell the agent where to look, but the agent’s access is not limited to those paths. See Agent File System Access.

Best Practices

Use these patterns to keep context focused and predictable:

• Put architecture and organization-wide standards in project context.
• Put target-specific patterns in target context.
• Put checklists and acceptance criteria in operation context.
• Use command-line flags for temporary notes and one-time references.
• Prefer specific directories over broad repository roots.
• Add descriptions that explain why a source matters, not only what its filename is.
• Exclude secrets, generated output, dependencies, and large binary assets.
• Run nia config validate after changing a configured source.
• Use --print-prompt only for diagnostics and review its output before sharing it.

Troubleshooting

Context File Not Found

Symptom: NIA reports Context file not found.

Cause: The configured file does not exist at the resolved path.

Resolution: Check the spelling and case of path, then verify the file from the repository root. For project and command configuration, use a repository-relative path.

Context Directory Not Found

Symptom: NIA reports Context directory not found.

Cause: The directory path does not exist or cannot be resolved.

Resolution: Create the directory or correct the path. Confirm that the command runs from the intended repository.

Path Resolves Outside the Repository

Symptom: NIA reports that a context path resolves outside the repository boundary.

Cause: The path uses .., an absolute location, or a symlink that resolves outside the repository.

Resolution: Move the reference inside the repository and use a path that resolves below the repository root.

Context Is Not Available to a Command

Symptom: The agent does not receive a configured context source.

Cause: The source is configured at a scope that does not apply to the command, or the command-line flag was used with a utility command.

Resolution: Put shared references under [[project.context]], target references under the target’s context entries, and operation references under [[commands.operations.context]]. Use context flags only with workflow commands.

Directory Context Contains Fewer Files Than Expected

Symptom: Some files in a directory do not appear in the collected context.

Cause: NIA skips hidden entries, configured build and dependency directories, binary files, unreadable files, files over 1 MB, and files after the 100-file per-source limit.

Resolution: Use a narrower directory, move relevant text files into a dedicated documentation directory, or add important files individually with type = "file" or --context-file.

Duplicate Context Appears in a Workflow

Symptom: A file appears in both project context and target-operation context.

Cause: Deduplication applies within the target-operation collection. Project context remains a separate category.

Resolution: Remove the duplicate source from one scope when the file does not need both semantic roles.

Configuration Validation Fails

Symptom: nia config validate reports an invalid configuration.

Cause: A context entry has an unsupported type, an invalid path, or a description longer than 500 characters.

Resolution: Correct the entry, ensure the source exists inside the repository, and run nia config validate again.

Related Information

• Set up project metadata to initialize .nia/config/project.toml and validate project configuration.
• Review workflow commands for context flags and command-specific options.
• Configure AI coding agents before running agent-driven workflows.
• Start with the Quick Start workflow for an end-to-end setup path.

Commit Behavior

title: Commit Behavior Configuration meta_title: NIA Commit Behavior - Control Agent Commit Instructions description: Configure project and command-level commit instructions for NIA workflows, including attribution, overrides, defaults, and troubleshooting. slug: commit-behavior

Commit Behavior Configuration

NIA adds commit instructions to workflow prompts so an AI coding agent receives explicit guidance about whether it may create Git commits. Configure commit behavior at the project level, override it for a target or operation, and verify the result before running autonomous workflows.

This setting controls the instructions sent to the agent. It does not itself create, amend, or push a commit.

When to Configure Commit Behavior

Use project-level commit behavior when one policy should apply across the repository. Use agent-level target or operation settings when different workflows need different policies.

Typical choices include:

• Use enabled when NIA should provide basic commit instructions for workflows that modify project files.
• Use tagged when commits should use NIA attribution in the commit instructions.
• Use disabled when a person or another automation system manages all commits.
• Use commits = "on" or commits = "off" for a specific target or operation.

Prerequisites

Before configuring commit behavior, make sure that:

• NIA is initialized in the project.
• You can edit .nia/config/project.toml and, when needed, .nia/config/agents.toml.
• Git is available when the selected workflow needs to inspect or modify a Git repository.
• You run NIA in a sandbox or development environment when an agent can modify files or create commits.

Run configuration validation after editing either file:

nia config validate

How Commit Behavior Works

NIA resolves one of three prompt configurations for each workflow operation:

NIA always supplies one of these commit configurations. Commands that do not commit by default receive explicit no-commit instructions so the agent does not decide commit behavior on its own.

Configure Project Defaults

Set the project-wide behavior in .nia/config/project.toml:

[commit]
behavior = "enabled"

The behavior setting accepts these values:

The project setting affects the commit instruction variant only when the operation resolves to commits enabled. It does not turn commits on for an operation that has no commit default.

Disable Commits Globally

Set the project behavior to disabled when all commits require manual review or external automation:

[commit]
behavior = "disabled"

Expected result: every workflow receives explicit no-commit instructions, including code create, which normally has commit instructions enabled.

Use NIA Attribution

Set the project behavior to tagged when the project policy requires NIA attribution in commit instructions:

[commit]
behavior = "tagged"

Expected result: an operation that normally commits receives the NIA-attributed commit configuration. An operation that normally does not commit still receives no-commit instructions unless an agent-level override enables commits.

Configure Target and Operation Overrides

Agent-level overrides belong to the settings for the selected agent in .nia/config/agents.toml. The file uses an agent table with a default agent name and one table for each configured agent.

For example:

schema_version = "1.0.0"

[agent]
default = "github_copilot"

[agent.github_copilot.targets]
code = { commits = "on" }

[agent.github_copilot.operations]
"code.review" = { commits = "off" }

The extended target and operation forms support commits values of on and off:

The selected agent matters. Configure the target and operation settings under the agent that NIA uses for the workflow.

Enable Commits for One Operation

The following configuration enables commit instructions for code review, which does not commit by default:

[agent.github_copilot.operations]
"code.review" = { commits = "on" }

Expected result: NIA selects the project behavior, such as basic or NIA-attributed instructions, for code review.

Disable Commits for One Target

The following configuration disables commit instructions for every code operation unless a more specific operation setting enables them:

[agent.github_copilot.targets]
code = { commits = "off" }

Expected result: code operations receive explicit no-commit instructions, including operations that normally commit.

Override a Target for One Operation

Operation-specific settings take precedence over target settings:

[agent.github_copilot.targets]
code = { commits = "off" }

[agent.github_copilot.operations]
"code.create" = { commits = "on" }

Expected result: code create receives commit instructions, while other code operations inherit the target-level off setting.

Understand Resolution Precedence

NIA resolves commit behavior in this order:

1. Project behavior = "disabled" acts as a global override and forces no-commit instructions.
2. An operation-specific commits setting takes precedence. For modifier operations, NIA first checks the modifier operation and then its base operation.
3. A target-specific commits setting applies when no operation-specific setting exists.
4. The built-in default determines whether the operation normally receives commit instructions.
5. Project behavior = "enabled" or behavior = "tagged" selects the commit instruction variant when commits are enabled.

For example, a project with behavior = "disabled" still sends no-commit instructions when operations."code.create".commits = "on". The global project setting has higher priority.

Review Built-In Defaults

NIA enables commit instructions by default for operations that create or modify code, documentation, or security changes:

All other operations use explicit no-commit instructions by default. Examples include ordinary code review, issue planning, issue review, pull request drafting and review, security audits, and other operations that are not listed above.

The internal operation names for modifier variants use names such as create_fix, refactor_fix, review_edit, and review_auto_fix. Use the command syntax shown in the command help and command reference when invoking them.

Verify the Effective Configuration

Use this workflow after changing commit settings:

1. Edit .nia/config/project.toml or .nia/config/agents.toml.

2. Run configuration validation:

   nia config validate
   

3. Review any validation errors or warnings.

4. Use the workflow command’s prompt-printing diagnostic when available to inspect the generated prompt:

   nia code create --print-prompt
   

5. Confirm that the prompt contains basic commit instructions, NIA-attributed instructions, or explicit no-commit instructions according to the resolved settings.

The --print-prompt option is a diagnostic feature. Review its output before sharing it because prompts can contain project paths and other workflow context.

Common Scenarios

Require Manual Commits

Use a project-wide disabled setting:

[commit]
behavior = "disabled"

This is appropriate when a developer or a separate release process reviews and creates every commit.

Allow Code Changes but Keep Reviews Uncommitted

Keep the default behavior for code creation and explicitly disable commits for review:

[agent.github_copilot.operations]
"code.review" = { commits = "off" }

Code creation retains its built-in commit behavior, while code review receives explicit no-commit instructions.

Enable Commit Instructions for a Normally Read-Only Operation

Use an operation override when an operation has an edit mode that your team wants the agent to commit:

[agent.github_copilot.operations]
"code.review" = { commits = "on" }

The project behavior value determines whether those instructions are basic or NIA-attributed.

Apply One Policy to a Target

Use a target override when every operation under a target follows the same policy:

[agent.github_copilot.targets]
docs = { commits = "off" }

Add an operation override when one documentation operation needs a different policy.

Best Practices

Follow these practices when you configure commit behavior:

• Set the project default first, then add the smallest number of agent-level exceptions needed by the team.
• Use disabled when autonomous commits are not permitted anywhere in the project.
• Use target settings for a consistent target-wide policy and operation settings for exceptions.
• Keep behavior values (enabled, tagged, and disabled) separate from agent toggles (on and off). They control different parts of resolution.
• Validate both configuration files after every change.
• Inspect the effective prompt when a workflow’s commit behavior is unexpected.
• Review autonomous agent changes before accepting or pushing commits.

Troubleshooting

A Workflow Receives No-Commit Instructions

Symptom: The agent is told not to commit during an operation that normally creates changes.

Cause: The project behavior is disabled, the selected agent has a target or operation setting of off, or the operation does not commit by default.

Resolution: Check the project setting first, then the selected agent’s operation and target settings. Set the relevant operation to commits = "on" when the workflow should receive commit instructions.

Commits Are Disabled Despite commits = "on"

Symptom: An operation-specific commits = "on" setting does not enable commit instructions.

Cause: The project-level setting is behavior = "disabled", which has global priority.

Resolution: Change the project behavior to enabled or tagged when the project permits commit instructions. Then run nia config validate and inspect the effective prompt.

A Target Setting Does Not Apply

Symptom: A target-level commits setting has no effect.

Cause: An operation-specific setting overrides it, or the setting is under an agent that is not selected for the workflow.

Resolution: Check the selected agent in [agent].default, inspect operations."target.operation", and remove or update the more specific setting when necessary.

A Modifier Uses Unexpected Commit Behavior

Symptom: A command with a modifier, such as a fix or edit variant, does not follow the base operation’s setting.

Cause: NIA checks the modifier operation first. If it has no setting, NIA inherits the base operation setting before checking the target setting.

Resolution: Configure the modifier operation explicitly when it needs a different policy. Use the operation key that matches the target and modifier operation shown by the command configuration.

NIA Rejects the Configuration

Symptom: nia config validate reports an error in the commit settings.

Cause: The setting uses an unsupported value, an incorrect table path, or invalid TOML syntax.

Resolution: Use enabled, tagged, or disabled for project behavior. Use on or off for agent target and operation toggles. Confirm that the settings are under .nia/config/project.toml or the selected agent in .nia/config/agents.toml, then validate again.

Related Information

• Set up project metadata to initialize and validate .nia/config/project.toml.
• Configure AI coding agents to select the agent whose target and operation settings NIA uses.
• Review the command reference for workflow operations and modifiers.
• Start with the Quick Start workflow for an end-to-end project setup.

Toolchain Configuration

Configure NIA with the issue tracker, ticket tracker, code platform, and security scanner used by your project. NIA resolves these definitions into context for AI agents so they can understand where project work is tracked and how each tool is accessed.

When to Configure the Toolchain

Configure the toolchain when your project uses an external development platform, a custom or on-premises service, a local workflow, or different repositories for issues and code. The configuration describes access and context; it does not install command-line tools, start MCP servers, or create credentials.

Prerequisites

Before you configure the toolchain, complete the following tasks:

• Initialize an NIA project so the .nia directory exists.
• Install and authenticate any CLI, MCP server, or API client referenced by a tool definition.
• Identify the repository URL when a tool uses a repository different from the current repository.
• Obtain the environment variables or other credentials required by the selected tool.

Configuration Fundamentals

NIA reads the project toolchain from .nia/config/toolchain.toml. The file uses TOML tables for tool categories and fields for each tool definition.

The configuration has these category rules:

• code_platform is required.
• At least one of issue_tracker or ticket_tracker is required.
• issue_tracker, ticket_tracker, and security_scanner each allow at most one definition.
• security_scanner is optional.

NIA supports two tool types:

• built-in uses a tool name from NIA’s built-in catalog. NIA supplies a description unless you provide one.
• custom describes a tool that is not represented by a built-in definition. Custom tools require a description and cannot reuse a built-in tool name.

Configuration File Structure

Use this structure as a starting point. The ticket_tracker and security_scanner tables are optional, but the file must contain code_platform and at least one tracker table:

[issue_tracker]
name = "github_issues"          # Tool name (required)
type = "built-in"               # "built-in" or "custom" (required)
method = "skill"                # "skill", "cli", "mcp", "api", or "local"
description = "..."             # Optional for built-in, required for custom
skill_name = "..."              # Optional custom skill name when method = "skill"

[code_platform]
name = "github"                 # Tool name (required)
type = "built-in"               # "built-in" or "custom" (required)
method = "skill"                # "skill", "cli", "mcp", "api", or "local"
description = "..."             # Optional for built-in, required for custom

[security_scanner]              # Optional
name = "polaris"                # Tool name
type = "built-in"               # "built-in" or "custom"
method = "skill"                # "skill", "cli", "mcp", "api", or "local"
description = "..."             # Optional for built-in, required for custom

Define Tool Fields

Each tool definition supports these fields:

Validation Rules

• code_platform is required (exactly one must be defined)
• issue_tracker is optional (at most one can be defined)
• ticket_tracker is optional (at most one can be defined)
• security_scanner is optional (at most one can be defined)
• description is required for custom tools
• description is optional for built-in tools (defaults provided)
• Custom tools cannot use the same name as built-in tools
• description field allows CLI command syntax and special characters
• description must be under 2000 characters

NIA validates descriptions before using them in prompt context. A description cannot exceed 2,000 characters and cannot contain a shell substitution pattern such as ${VALUE}.

Use Built-In Tools

NIA includes definitions for common platforms:

Issue Trackers

• github_issues—GitHub Issues.
• jira—Atlassian JIRA.
• azure_devops—Azure DevOps Boards.
• shortcut—Shortcut Project Management.
• local—Local issue tracker that reads local Markdown files.

Code Platforms

• github—GitHub.
• github_enterprise—GitHub Enterprise.
• bitbucket—Bitbucket.
• azure_devops—Azure DevOps Repos.
• local—Local code platform that uses local Git branches.

Ticket Trackers

Ticket trackers represent customer-facing support or RFA work, while issue trackers represent development tasks. NIA includes these ticket tracker definitions:

• github_issues—GitHub Issues for RFA ticket tracking.
• jira—JIRA for RFA ticket tracking.
• azure_devops—Azure DevOps Boards for RFA ticket tracking.
• shortcut—Shortcut for RFA ticket tracking.
• local—Local ticket tracker that reads local Markdown files.

Built-in Method Support

Nia validates the selected access method against the built-in tool definition. The exact support matrix is:

An explicit description override can define instructions for another valid access method.

Access Methods

The method field specifies how nia instructs agents to interact with your tools.

Skill Method (Recommended)

The skill method is the default and recommended choice for new projects. It provides:

• 60-90% token savings compared to inline descriptions
• Cross-agent compatibility with GitHub Copilot, Claude Code, and OpenCode
• Customizable instructions that you can version control with your project
• Progressive disclosure - agents load only what they need

How Skills Work:

1. When you configure method = "skill", nia injects a short reference telling the agent which skill to use
2. The agent discovers and loads the skill from .agents/skills/<skill-name>/
3. Skills are loaded progressively: metadata first, then full instructions when needed

Built-in Skill Mapping:

Local issue, ticket, and code tools use method = "local" and do not have embedded skills.

Example Configuration:

[issue_tracker]
name = "github_issues"
type = "built-in"
method = "skill"  # Uses "issue-read-github" skill

[code_platform]
name = "github"
type = "built-in"
method = "skill"  # Uses "pr-read-github" skill

Installing Skills:

The recommended setup command creates toolchain.toml and automatically installs only the skills required by the selected tools:

nia config init --issues github_issues --code github

This installs issue-read-github and pr-read-github under .agents/skills/ without overwriting existing customizations. To export every embedded built-in skill, use:

nia config export --skills

Explicit --skills export is not filtered by toolchain.toml; it exports all embedded skills and skips existing files unless --force is supplied. See the Skills Configuration Guide for customization details.

CLI (Command Line Interface)

Tools accessed via installed command-line utilities:

method = "cli"

MCP (Model Context Protocol)

Tools accessed via MCP servers:

method = "mcp"

API (Direct API Access)

Tools accessed via REST APIs:

method = "api"

Local (Local File Access)

Tools that read from local files:

method = "local"

Security scanners do not support the local method.

Use Local Mode

Set both the issue tracker and code platform to the built-in local tool with the local method for a local workflow. The local issue tracker reads issue content from the project’s local work area, and the local code platform uses local Git branches.

The NIA_ISSUE_ID environment variable identifies the current issue for local issue processing. Set it before running a workflow that requires an issue identifier.

Configure Repository Targets

Set repository when a tool must target a repository other than the current repository. NIA validates the repository URL and uses the current repository when the field is omitted where repository detection applies.

The following examples show separate issue and code repositories, including upstream and fork-based workflows. Verify that the configured credentials can access every repository named in the file.

Configuration Examples

Example 1: Default Configuration (Skill Method)

# Recommended: Use skill method for token efficiency
schema_version = "1.0.0"

[issue_tracker]
name = "github_issues"
type = "built-in"
method = "skill"  # 60-90% token savings

[code_platform]
name = "github"
type = "built-in"
method = "skill"

When this configuration is created with nia config init, the matching skills are installed automatically. If you wrote the file manually, export the embedded skills:

nia config export --skills

Example 2: Mixed Methods

# Use skill method for some tools, CLI for others
schema_version = "1.0.0"

[issue_tracker]
name = "jira"
type = "built-in"
method = "skill"  # Uses agent skill for token efficiency

[code_platform]
name = "github"
type = "built-in"
method = "cli"    # Uses direct CLI instructions

[security_scanner]
name = "polaris"
type = "built-in"
method = "skill"

Example 3: Custom Tool with Skill

# Custom tool with custom skill
schema_version = "1.0.0"

[issue_tracker]
name = "acme_tracker"
type = "custom"
method = "skill"
skill_name = "acme-issue-read"  # Custom skill name
description = "Use the {{skill_name}} skill to read ACME issues."

Then create .agents/skills/acme-issue-read/SKILL.md with your custom instructions. Nia replaces {{skill_name}} with acme-issue-read when composing the prompt. Custom skills are user-authored and are not created by nia config export --skills.

Example 4: GitHub with CLI

# Use GitHub Issues and GitHub repos with GitHub CLI
[issue_tracker]
name = "github_issues"
type = "built-in"
method = "cli"

[code_platform]
name = "github"
type = "built-in"
method = "cli"

Example 2: GitHub with MCP Server

# Use GitHub with MCP server integration
[issue_tracker]
name = "github_issues"
type = "built-in"
method = "mcp"

[code_platform]
name = "github"
type = "built-in"
method = "mcp"

Example 3: JIRA and Github

# Use JIRA for issues and Github for code
[issue_tracker]
name = "jira"
type = "built-in"
method = "cli"

[code_platform]
name = "github"
type = "built-in"
method = "cli"

Example 4: Override Built-in Description

# Override default GitHub Issues description with custom details
[issue_tracker]
name = "github_issues"
type = "built-in"
method = "cli"
description = """
GitHub Issues via gh CLI. Enterprise instance at github.mycompany.com.
Use 'gh issue view <number>' to read issues.
Use 'gh issue create' to create new issues.
Authentication: SSO required, run 'gh auth login --hostname github.mycompany.com'
"""

[code_platform]
name = "github"
type = "built-in"
method = "cli"

Example 5: Custom On-Premise Tool

# Custom JIRA on-premise installation
[issue_tracker]
name = "jira-onprem"
type = "custom"
method = "api"
description = """
JIRA on-premise instance at jira.mycompany.com.
Access via REST API: https://jira.mycompany.com/rest/api/2
Authentication: Basic auth with username/password from environment variables.
View issue: GET /rest/api/2/issue/{issueKey}
Create issue: POST /rest/api/2/issue
Search issues: POST /rest/api/2/search with JQL query
"""

[code_platform]
name = "github"
type = "built-in"
method = "cli"

Example 6: Local-Only Mode (Offline Development)

schema_version = "2.1.0"

# Local issue tracking - reads from local markdown files
[issue_tracker]
name = "local"
type = "built-in"
method = "local"

# Local code platform - uses local Git only
[code_platform]
name = "local"
type = "built-in"
method = "local"

With this configuration:

• Issue descriptions are read from .nia/work/job_<issue_id>/issue/issue.md.
• No external API calls are made by the local tool definitions.
• Pull request operations use local Git branches only.
• Set the issue ID with the NIA_ISSUE_ID environment variable.

Example 7: Mixed Mode (Local Issues + GitHub Code)

schema_version = "2.1.0"

# Local issue tracking
[issue_tracker]
name = "local"
type = "built-in"
method = "local"

# GitHub for code (with external access)
[code_platform]
name = "github"
type = "built-in"
method = "cli"

Use this configuration when you want to:

• Define issues locally without using GitHub Issues.
• Create and manage pull requests through GitHub.

Example 8: Full Configuration with Security Scanner

schema_version = "2.1.0"

# Issue tracking
[issue_tracker]
name = "github_issues"
type = "built-in"
method = "cli"

# RFA ticket tracking
[ticket_tracker]
name = "github_issues"
type = "built-in"
method = "api"

# Code platform
[code_platform]
name = "github"
type = "built-in"
method = "cli"

# Security scanning
[security_scanner]
name = "polaris"
type = "built-in"
method = "cli"

With this configuration:

• GitHub Issues handles development tasks through the CLI.
• GitHub Issues handles RFA tickets through the API.
• GitHub hosts the code and pull requests.
• Polaris performs security scanning.

Example 9: Fork-Based Workflow

When working on a fork but tracking issues in upstream:

schema_version = "2.1.0"

[issue_tracker]
name = "github_issues"
type = "built-in"
method = "cli"
repository = "https://github.com/upstream-org/project.git"

[code_platform]
name = "github"
type = "built-in"
method = "cli"
# No repository field - uses your fork (auto-detected)

This configuration:

• Reads issues from the upstream repository.
• Creates pull requests against the fork repository selected by repository detection.
• Supports GitHub CLI commands that target the upstream repository when the tool description or command supplies that repository.

Example 10: Public Issues with Private Code

For projects with separate public issue tracking and private source code:

schema_version = "2.1.0"

[issue_tracker]
name = "github_issues"
type = "built-in"
method = "cli"
repository = "https://github.com/company/product-public.git"

[code_platform]
name = "github"
type = "built-in"
method = "cli"
repository = "https://github.com/company/product-internal.git"

This configuration supports:

• Public issue discussions and feature requests.
• Private source code.
• Separate access control for each repository.

Initialize the Configuration

Use nia config init to generate a toolchain configuration from built-in tool names. Supply at least one tracker flag and the --code flag:

nia config init --issues github_issues --code github --agent github_copilot
nia config init --issues github_issues --code github --agent opencode --models stable

The command requires --agent only when you also want NIA to generate agent configuration. The --models option requires --agent. Supported initialization flags include:

• --issues for an issue tracker.
• --tickets for a ticket tracker.
• --code for the required code platform.
• --scanner for a security scanner.
• --agent for an agent profile.
• --models for the selected agent model profile.

When the command generates toolchain configuration, it writes .nia/config/toolchain.toml with built-in definitions and the cli method. When --agent is supplied, it also writes .nia/config/agents.toml.

The available agent profiles include github_copilot, opencode, and claude_code. The available model profiles are:

• lite—Minimize cost with faster models.
• balanced—Balance cost and performance.
• stable—Use the stable profile.
• heavy—Use the highest-quality profile.

Understand Toolchain Context

NIA resolves each tool definition and makes the result available as Markdown context headed # Development Toolchain. A built-in tool uses this description order:

1. A description set in toolchain.toml.
2. A method-specific built-in description.
3. A generic built-in description.

Custom descriptions provide context such as authentication requirements, commands, API endpoints, and service-specific behavior. NIA treats descriptions as prompt context; they do not execute commands or authenticate with a service.

Use Prompt Placeholders

Custom prompts can reference resolved tool values with {{key}} syntax:

# Custom Prompt Example

The issue tracker is: {{issue_tracker_name}}
The code platform is: {{code_platform_name}}

The placeholder map includes these values:

• {{issue_tracker_name}}, {{issue_tracker_method}}, and {{issue_tracker_description}}.
• {{ticket_tracker_name}}, {{ticket_tracker_method}}, and {{ticket_tracker_description}}.
• {{code_platform_name}}, {{code_platform_method}}, and {{code_platform_description}}.
• {{security_scanner_name}}, {{security_scanner_method}}, and {{security_scanner_description}}.
• Repository owner, name, and slug values for configured tools when available.

The placeholder map does not include the tool type field.

Apply Configuration Precedence

NIA can discover configuration from multiple sources. The precedence order from lowest to highest is:

1. System configuration.
2. User configuration.
3. Application configuration when an application is connected.
4. Repository configuration.

External sources are disabled by default. Enable the external-source master switch and the individual configuration source in the project configuration before NIA reads those files. Higher-precedence values overlay lower-precedence values; toolchain fields merge at the category level.

Validate and Lock the Configuration

Run the direct configuration validation command after editing the file:

nia config validate

The command validates the project configuration without writing a lock file. It reports errors for missing required categories, invalid tool types or methods, unknown built-in tools, duplicate definitions, invalid repository URLs, missing custom descriptions, name conflicts, and unsafe or oversized descriptions.

After validation succeeds, create or update the configuration lock:

nia config lock

NIA stores the lock at .nia/.config_lock and uses SHA-256 hashes to track configuration state. Run nia config lock again after changing configuration so the lock reflects the current files.

Troubleshoot Configuration Errors

Use the error message to identify the invalid field or table, then apply the corresponding correction:

• Missing required configuration: Add [code_platform] and at least one of [issue_tracker] or [ticket_tracker].

  At least one of issue_tracker or ticket_tracker must be configured
  

  If the code platform is missing, the configuration parser reports a missing code_platform field.

• Custom tool without a description: Add a description to every type = "custom" definition.

  Custom issue_tracker 'my_custom_tracker' must have a description
  

  The category and tool name in the message change to match the invalid definition.

• Unknown built-in tool: Check the spelling and use a name from the built-in catalog, or change the type to custom and provide a description. A custom tool name cannot match a built-in name.

  Unknown built-in issue_tracker: 'unknown_tracker'. Available: [...]
  

  NIA replaces [...] with the available names for that category.

• Invalid method: Use cli, mcp, api, or local, subject to the category restrictions for security scanners.

• Invalid repository: Set repository to a valid repository URL and verify that the configured tool can access it.

• Invalid description: Shorten descriptions to 2,000 characters or fewer and remove ${...} shell substitution syntax.

  Tool 'my_custom_tracker' description exceeds maximum length of 2000 characters
  Tool 'my_custom_tracker' description contains unsafe shell variable substitution: ${...}
  

  The tool name in each message identifies the definition that needs correction.

• Stale lock state: Run nia config validate, then run nia config lock to write a lock for the current configuration.

Follow Configuration Practices

Apply these practices to keep toolchain context accurate and useful:

• Use built-in tools when their definitions match your platform.
• Use a custom description for service-specific hosts, authentication steps, commands, and API endpoints.
• Keep descriptions factual and focused on information an agent needs to choose or use the tool.
• Store credentials in the supported credential mechanism, not in toolchain.toml descriptions.
• Set repository explicitly when issue, ticket, code, or scanner data belongs to a different repository.
• Validate the file before committing it and update .nia/.config_lock after configuration changes.

Related Documentation

• Agent Setup Guide - Installing and authenticating AI agents
• Skills Configuration Guide - Installing and customizing agent skills
• Agent Troubleshooting - Diagnosing agent and toolchain issues

Hierarchical Configuration

Nia supports loading configuration from multiple locations, allowing you to share configurations across repositories while maintaining repository-level control.

Overview

Configuration files can be loaded from up to five locations (in priority order):

1. Repository (highest priority): .nia/config/<file>.toml
2. Application: <app-root>/.nia/config/application.toml (when using multi-repository applications)
3. User: ~/.config/nia/<file>.toml (Linux/macOS) or %APPDATA%\nia\<file>.toml (Windows)
4. System (lowest priority): /etc/nia/<file>.toml (Linux/macOS) or %PROGRAMDATA%\nia\<file>.toml (Windows)
5. Default: Built-in default values

Settings from higher-priority sources override those from lower-priority sources.

New in 4.2: Application-level configuration for multi-repository applications. See Multi-Repository Applications below.

Supported Configuration Files

The following files support hierarchical loading:

Note: project.toml is always repository-specific and does not support hierarchical loading.

Enabling External Sources

⚠️ Important: External configurations are disabled by default for security reasons.

By default, nia only loads configuration from the repository. To enable user and system configurations, add the following to your project.toml:

[config.external_sources]
enabled = true

Fine-Grained Control

You can enable external sources for specific configuration files:

[config.external_sources]
enabled = true
agents = true      # Load agents.toml from user/system
toolchain = false  # Keep toolchain.toml repository-only
commands = true    # Load commands.toml from user/system
workflows = true   # Load workflows/*.toml from user/system

If a specific file toggle is omitted, it defaults to true when the master enabled switch is on.

Merge Behavior

When multiple sources provide the same configuration:

• Simple values: Higher priority wins (repository overrides user, user overrides system)
• Objects/tables: Deep merge (nested values merge recursively)
• Arrays: Higher priority replaces entirely (no merging)

Example: Merging Agent Configuration

System (/etc/nia/agents.toml):

schema_version = "1.0.0"

[agent]
default = "github_copilot"

[models]
code = "claude-sonnet-4.5"
docs = "claude-haiku-4.5"

Repository (.nia/config/agents.toml):

schema_version = "1.0.0"

[models]
code = "claude-opus-4.5"

Result (merged):

[agent]
default = "github_copilot"              # From system

[models]
code = "claude-opus-4.5"                # From repository (overrides)
docs = "claude-haiku-4.5"               # From system (preserved)

Minimal Initialization

For repositories that rely primarily on user/system configurations:

nia config init --minimal

This creates only project.toml with commented examples showing how to enable external sources. You can then manage agents, toolchain, commands, and workflows at the user or system level.

Diagnostics

View Configuration Sources

nia config show --sources

Output example:

Configuration Sources

External sources: enabled

project.toml:
  • repository configuration (.nia/config/project.toml)

agents.toml:
  • system configuration (/etc/nia/agents.toml)
  • repository configuration (.nia/config/agents.toml)

toolchain.toml:
  • user configuration (~/.config/nia/toolchain.toml)
  • repository configuration (.nia/config/toolchain.toml)

Validate Merged Configuration

nia config validate

This validates the merged configuration and reports which sources contributed to each file.

Lock Configuration

nia config lock

Creates a lockfile (.nia/.config_lock) with hashes of all configuration sources. This ensures reproducible builds and helps detect configuration changes.

Security Considerations

⚠️ Important: External configurations are disabled by default for security reasons.

Before enabling external sources:

1. Trust the source: Ensure you trust configurations at user/system locations
2. Review contents: Inspect external configuration files before enabling
3. CI/CD environments: Consider using NIA_DISABLE_EXTERNAL_CONFIGS=true to force repository-only mode

Environment Override

Force-disable external sources regardless of project.toml:

export NIA_DISABLE_EXTERNAL_CONFIGS=true
nia workflow run  # Will only use repository config

This is particularly useful in CI/CD pipelines where you want to ensure reproducible builds without external dependencies.

Use Cases

Enterprise Standard Configuration

System administrators can deploy standard configurations to /etc/nia/:

# Install organization-wide defaults
sudo mkdir -p /etc/nia
sudo cp agents.toml toolchain.toml /etc/nia/

Repositories only need minimal configuration:

# .nia/config/project.toml
schema_version = "1.0.0"

[project]
name = "my-service"
description = "My service"
language = "Rust"
framework = "actix-web"
testing_framework = "cargo test"
package_manager = "cargo"

[config.external_sources]
enabled = true

Personal Preferences

Store personal AI agent preferences in user configuration:

mkdir -p ~/.config/nia
cat > ~/.config/nia/agents.toml << EOF
schema_version = "1.0.0"

[agent]
default = "github_copilot"

[models]
code = "claude-sonnet-4.5"
docs = "claude-haiku-4.5"
EOF

All your repositories can then use these settings without duplicating configuration.

Project-Specific Overrides

Override specific settings while inheriting defaults:

# .nia/config/agents.toml
# Only override what's different for this project
schema_version = "1.0.0"

[models]
code = "claude-opus-4.5"  # Use premium model for this critical project

The other settings (agent selection, docs model, etc.) will be inherited from user/system configuration.

Team Workflows

Share common workflows across repositories via system configuration:

# System admin installs team workflows
sudo mkdir -p /etc/nia/config/workflows
sudo cp review-checklist.toml code-quality.toml /etc/nia/config/workflows/

Individual repositories can:

• Use team workflows as-is by enabling external sources
• Override specific workflow steps in their repository configuration
• Add repository-specific workflows alongside team workflows

Workflow Configuration

Workflows support the same hierarchical loading as other configuration files:

# .nia/config/project.toml
[config.external_sources]
enabled = true
workflows = true  # Enable workflow loading from user/system

Workflow merge strategy:

• Workflows with the same filename from higher priority sources completely override lower priority
• No partial merging of workflow steps
• This ensures workflow consistency and prevents unexpected behavior

Example:

System: /etc/nia/config/workflows/review.toml
User:   ~/.config/nia/config/workflows/review.toml
Repo:   .nia/config/workflows/review.toml

Result: Only repo review.toml is used (completely overrides user and system)

Troubleshooting

External sources not loading

Check that:

1. project.toml has [config.external_sources] with enabled = true
2. File-specific toggle is not explicitly set to false
3. NIA_DISABLE_EXTERNAL_CONFIGS environment variable is not set
4. Configuration files exist at expected user/system paths

Run nia config show --sources to see which sources are being loaded.

Configuration validation errors

If validation fails:

1. Check syntax in all configuration files
2. Ensure schema versions match (use 1.0.0 for all files)
3. Verify merged configuration with nia config validate --verbose
4. Check individual files in isolation first

Lockfile conflicts

If you see lockfile validation errors:

1. Delete .nia/.config_lock
2. Run nia config lock to regenerate
3. Commit the new lockfile

The lockfile includes hashes from all sources, so changes to user/system configs will invalidate it.

Best Practices

1. Start minimal: Use nia config init --minimal for new repositories that will use external configs
2. Layer appropriately: System for organization-wide, user for personal, repository for project-specific
3. Document overrides: Add comments explaining why repository config overrides external settings
4. Lock in CI: Always use NIA_DISABLE_EXTERNAL_CONFIGS=true in CI/CD for reproducibility
5. Version control: Only commit repository configs to git, never user/system configs
6. Review external: Periodically review user/system configs for stale or conflicting settings

Multi-Repository Applications

New in version 4.2

Nia supports managing multiple related repositories as a single application. This is useful for:

• Microservices architectures with separate repositories per service
• Large projects spanning multiple related repositories
• Monorepo alternatives where repositories are siblings in a directory

Creating an Application

Initialize an application configuration in your application root directory:

cd /path/to/my-application
nia config init --app

This creates .nia/config/application.toml with a unique application ID:

schema_version = "1.0.0"

[application]
id = "550e8400-e29b-41d4-a716-446655440000"
name = "my-application"
description = "Multi-repository application"

[discovery]
enabled = true
max_depth = 5
exclude = ["node_modules", "target", ".git"]

# Discovered repositories will be added here
[[repositories]]
name = "api-service"
path = "./services/api"

Initializing with Additional Configuration

The --app flag can be combined with other configuration flags to create a complete setup in one command:

Application with Issue Tracker and Code Platform

nia config init --app --issues github_issues --code github

This creates:

• .nia/config/application.toml - Application metadata and repository discovery
• .nia/config/toolchain.toml - Issue tracker and code platform configuration

Application with AI Agent Configuration

nia config init --app --agent github_copilot --models balanced

This creates:

• .nia/config/application.toml - Application metadata
• .nia/config/agents.toml - AI agent and model selection

Complete Application Setup

nia config init --app \
    --issues github_issues \
    --code github \
    --agent github_copilot \
    --models balanced

This creates all configuration files at once:

• .nia/config/application.toml - Application metadata
• .nia/config/toolchain.toml - Development toolchain
• .nia/config/agents.toml - AI agent configuration

This is particularly useful for bootstrapping new multi-repository applications where child repositories will inherit these shared configurations.

Repository Opt-In

Each repository that should be part of the application must explicitly opt-in by adding the application ID to its project.toml:

# services/api/.nia/config/project.toml
schema_version = "1.0.0"

[project]
name = "api-service"
description = "API Service"
language = "Rust"
framework = "actix-web"
testing_framework = "cargo test"
package_manager = "cargo"
allow_app = "550e8400-e29b-41d4-a716-446655440000"  # Application UUID

This opt-in mechanism ensures:

• Repositories consciously join applications
• Accidental inclusion is prevented
• Security boundaries are maintained

Discovering Repositories

Find all repositories that have opted into the application and save them to configuration:

nia app discover

This command:

1. Recursively scans directories up to max_depth from application root
2. Finds repositories with matching allow_app UUID
3. Writes discovered repositories to application.toml

To overwrite existing repository configuration with fresh discovery:

nia app discover --force

Note: Discovery results are persisted to application.toml since nia operates as single-execution CLI commands. This ensures repository configuration is explicit, version-controllable, and reproducible across runs.

Discovery Configuration

Control the discovery process in application.toml:

[discovery]
enabled = true           # Enable automatic discovery
max_depth = 5            # Maximum directory depth to scan (1-10)
exclude = [              # Patterns to exclude from scanning
    "node_modules",
    "target",
    ".git",
    "vendor",
    "*_cache"
]

Exclusion patterns support:

• Exact matches: "node_modules"
• Prefix wildcards: ".cache*" matches .cache, .cache-v3, etc.
• Suffix wildcards: "*_build" matches cmake_build, debug_build, etc.

Explicit Repository Paths

You can also explicitly list repositories in application.toml:

[[repositories]]
name = "external-lib"
path = "../external-repo"

[[repositories]]
name = "shared-utils"
path = "/absolute/path/to/repo"

Explicit repositories:

• Are included even without allow_app matching
• Can use relative or absolute paths
• Override discovered repositories with the same name

Application Configuration Hierarchy

With an application, the configuration hierarchy becomes:

Higher priority settings override lower priority ones.

Viewing Application Context

See which repositories are part of the application:

nia config show --sources

Output example:

Configuration Sources

Application: my-application (550e8400-e29b-41d4-a716-446655440000)
  Repositories:
    • api-service (./services/api)
    • web-frontend (./services/web)
    • shared-lib (./libraries/shared)

project.toml:
  • application configuration (../.nia/config/application.toml)
  • repository configuration (.nia/config/project.toml)

agents.toml:
  • user configuration (~/.config/nia/agents.toml)
  • application configuration (../.nia/config/application.toml)
  • repository configuration (.nia/config/agents.toml)

Working Across Repositories

When you run nia commands from within any repository that has opted into an application:

1. Nia searches upward for application.toml
2. Application-level configuration is loaded and merged
3. Repository-specific config overrides application config
4. You can access application-wide settings while maintaining repository autonomy

Best Practices

1. Use meaningful application names - Helps identify the application purpose
2. Set reasonable exclude patterns - Improves discovery performance and accuracy
3. Keep max_depth minimal - Only as deep as your repository structure requires
4. Use explicit paths for external repos - Repositories outside the app directory tree
5. Validate configurations - Run nia config validate regularly
6. Version control application.toml - Commit to ensure team has same repository list
7. Document UUID in project.toml - Add comment explaining which application it joins

Example: Microservices Application

my-microservices-app/
├── .nia/
│   └── config/
│       └── application.toml          # Application config
├── services/
│   ├── api/
│   │   └── .nia/
│   │       └── config/
│   │           └── project.toml      # allow_app = "app-uuid"
│   ├── auth/
│   │   └── .nia/
│   │       └── config/
│   │           └── project.toml      # allow_app = "app-uuid"
│   └── notifications/
│       └── .nia/
│           └── config/
│               └── project.toml      # allow_app = "app-uuid"
└── libraries/
    └── shared/
        └── .nia/
            └── config/
                └── project.toml      # allow_app = "app-uuid"

Setup:

# 1. Create application
cd my-microservices-app
nia config init --app

# 2. Copy UUID from application.toml
APP_UUID=$(grep 'id =' .nia/config/application.toml | cut -d'"' -f2)

# 3. Add UUID to each repository's project.toml
echo "allow_app = \"$APP_UUID\"" >> services/api/.nia/config/project.toml
echo "allow_app = \"$APP_UUID\"" >> services/auth/.nia/config/project.toml
echo "allow_app = \"$APP_UUID\"" >> services/notifications/.nia/config/project.toml
echo "allow_app = \"$APP_UUID\"" >> libraries/shared/.nia/config/project.toml

# 4. Discover all repositories
nia app discover

# 5. Verify
nia config show --sources

Security Considerations

Application-level configuration introduces an additional trust boundary:

1. Verify application.toml - Review before opting repositories in
2. UUID validation - Nia validates UUIDs are properly formatted
3. Explicit opt-in required - Repositories must explicitly allow the application
4. Path validation - Explicit repository paths are validated during discovery
5. Backward compatibility - Repositories without allow_app work as before

Troubleshooting

Repository not discovered

Check that:

1. Repository has allow_app field with correct UUID (case-insensitive)
2. Repository is within max_depth from application root
3. Repository path is not matched by exclude patterns
4. Repository has .nia/config/project.toml file

UUID mismatch errors

• UUIDs are case-insensitive but must be valid UUIDv4 format
• Copy UUID exactly from application.toml
• Check for extra whitespace or quotes

Discovery finds wrong repositories

1. Check exclude patterns in application.toml
2. Reduce max_depth if scanning too deep
3. Use explicit [[repositories]] entries for specific repos

Further Reading

• Configuration Reference - Complete configuration field documentation
• Workflow Configuration - Workflow configuration schema
• Project Configuration - Project-level configuration guide

Agent Skills

Skills are packages of procedural knowledge that agents load on demand. They follow the Agent Skills open standard and work across multiple AI agents.

Installing Built-in Skills

When you initialize a toolchain, Nia installs only the embedded skills required by tools configured with method = "skill":

nia config init --issues github_issues --code github
# Installs .agents/skills/issue-read-github/
#          .agents/skills/pr-read-github/

To export the complete embedded library, run:

nia config export --skills

Explicit export writes all 18 embedded skills. Existing files are preserved unless you add --force. Custom skills are not generated by this command; create their directories and SKILL.md files yourself.

Embedded Skill Library

Local issue, ticket, and code tools use method = "local"; they do not require or export skill packages during initialization.

Skill Structure

Each skill is a directory containing:

skill-name/
├── SKILL.md          # Required: metadata and instructions
└── references/       # Optional: additional documentation

SKILL.md Format

The SKILL.md file has two parts:

Frontmatter (YAML)

---
name: issue-read-github
description: >
  Retrieves and reads issues from GitHub issue trackers using gh CLI.
  Use when working with GitHub issues, or when the user mentions reading,
  viewing, or retrieving issues from GitHub.
version: "1.0.0"
---

Body (Markdown)

The body contains instructions the agent follows. Write in imperative language:

# GitHub Issue Retrieval

## Prerequisites
- gh CLI installed and authenticated

## Basic Commands

### List Issues
\`\`\`bash
gh issue list
gh issue list --state closed
\`\`\`

### View Issue Details
\`\`\`bash
gh issue view <number>
\`\`\`

## Best Practices
1. Check comments for updates
2. Review linked PRs
3. Consider issue labels and assignees

Customizing Skills

Edit Existing Skills

1. Locate the skill: .agents/skills/<skill-name>/SKILL.md
2. Edit the body to match your team’s practices
3. Commit to version control to share with your team

Example customization:

# GitHub Issue Retrieval

## Prerequisites
- gh CLI installed and authenticated
- VPN connected to company network

## Our Team Practices
- Always check #engineering Slack for context
- Label issues with `team:backend` or `team:frontend`
- Mention relevant RFC documents in issue comments

## Basic Commands
...

Add Progressive Disclosure

For detailed documentation that shouldn’t always be loaded:

1. Create references/ subdirectory
2. Add Markdown files with detailed content
3. Reference from main SKILL.md: “See references/advanced-queries.md for complex JQL patterns”

Example:

.agents/skills/issue-read-jira/
├── SKILL.md
└── references/
    ├── jql-syntax.md
    ├── custom-fields.md
    └── workflow-states.md

Then in SKILL.md:

## Advanced Queries

For complex JQL patterns and custom field queries, see `references/jql-syntax.md`.

Custom Skill Names

For custom tools, optionally specify a skill name and reference it from the description:

[issue_tracker]
name = "acme_tracker"
type = "custom"
method = "skill"
skill_name = "acme-issue-read"
description = "Use the {{skill_name}} skill to read ACME issues."

Then create .agents/skills/acme-issue-read/SKILL.md with your custom instructions. During prompt composition, Nia replaces {{skill_name}} with acme-issue-read. If skill_name is omitted, it defaults to the custom tool’s exact name (acme_tracker in this example). The field is used only when method = "skill".

Naming Conventions

Skill names should follow the pattern: {category}-{action}-{variant}

Valid examples:

• issue-read-github
• pr-read-bitbucket
• acme-deploy-prod
• custom-build-docker

Invalid examples:

• GithubIssues (use kebab-case, not PascalCase)
• read_issues (use hyphens, not underscores)
• issue (missing action and variant)

Reserved prefixes (for built-in skills):

• issue- - Issue tracker operations
• pr- - Pull request operations
• ticket- - Ticket tracker operations
• scanner- - Security scanner operations

Custom skills using reserved prefixes will trigger a warning but are allowed.

Skill Scope

Skills can be stored at two levels:

Project Scope

• Location: <repo>/.agents/skills/
• Committed to version control
• Shared with team members
• Project-specific customizations

Best for:

• Team-wide practices and conventions
• Project-specific tool configurations
• Shared knowledge and procedures

User Scope

• Location: ~/.agents/skills/
• Not committed (personal)
• Available across all projects
• Personal preferences and customizations

Best for:

• Personal shortcuts and preferences
• Company-wide standards across projects
• Tools you use in all projects

Automatic Detection

When you run nia config export --skills, the scope is auto-detected:

Override with –scope

# Force project scope (version-controlled)
nia config export --skills --scope=project

# Force user scope (global, personal)
nia config export --skills --scope=user

Scope Precedence

When an agent loads skills, it checks locations in order:

1. Project: .agents/skills/ (highest priority)
2. User: ~/.agents/skills/

Project skills take precedence over user skills with the same name.

Cross-Agent Compatibility

Skills work across:

• GitHub Copilot - Full support for Agent Skills standard
• Claude Code - Compatible skill loading
• OpenCode - Follows same discovery pattern

The .agents/skills/ path is the interoperable standard recognized by all three agents.

Version Management

Checking for Updates

When you run nia config export --skills, Nia compares each existing skill’s frontmatter version string with the embedded version. A different string is reported as an update:

⚠ Skill updates available:
  - issue-read-github: v1.0.0 → v1.1.0
  - pr-read-github: v1.2.0 → v1.3.0

Run 'nia config export --skills --force' to update
Warning: This will overwrite existing files. Back up custom modifications first.

Updating Skills

Skills are not updated automatically to preserve your customizations. To update:

1. Back up your changes:

   cp -r .agents/skills/ .agents/skills-backup/
   

2. Re-export with force:

   nia config export --skills --force
   

3. Manually merge customizations: Review .agents/skills-backup/ and merge your changes back

Version Field

The version field in SKILL.md frontmatter should follow semantic versioning:

version: "1.2.3"

• Major (1.x.x): Breaking changes to skill structure or commands
• Minor (x.2.x): New features or commands added
• Patch (x.x.3): Bug fixes, clarifications, typo corrections

Nia currently detects only whether version strings differ; it does not determine whether the embedded version is semantically newer.

Troubleshooting

Skill Not Loading

If an agent doesn’t load your skill:

1. Check skill location: Ensure it’s in .agents/skills/<skill-name>/
2. Verify frontmatter: Ensure YAML is valid with --- delimiters
3. Check name field: Must match directory name exactly
4. Validate markdown: Ensure no syntax errors in body

Skill Update Not Detected

If nia config export --skills doesn’t detect updates:

1. Check version field: Ensure both files contain a nonempty version (for example, “1.0.0”)
2. Verify frontmatter: Version field must be in frontmatter, not body
3. Re-export with force: Use --force to overwrite and update

Custom Skill Not Used

If agent uses built-in skill instead of custom:

1. Check method: Ensure method = "skill" in toolchain.toml
2. Verify skill_name: For custom tools, set skill_name field
3. Check precedence: Project skills override user skills
4. Check the description: It must reference {{skill_name}} so the final prompt names the skill
5. Check the file: Custom skills are not exported by Nia; create .agents/skills/<skill_name>/SKILL.md

See Also

• Toolchain Configuration Guide - Configure access methods
• Utility Command Reference - Export skills command
• Agent Skills Standard - Official specification

AI Coding Agent Setup

NIA delegates workflow execution to an external AI coding agent. The agent reads the prompt that NIA generates, uses the available command-line tools, and returns its output to NIA. Configure one supported agent before you run workflows that analyze issues, modify files, run tests, or create pull requests.

Warning: NIA runs agents in autonomous mode. The agent can execute commands and modify files without waiting for approval. Run NIA in a sandbox or development container, and review changes before you accept or push them.

Choose an Agent

NIA includes these built-in agents:

Use the exact agent ID in .nia/config/agents.toml and with the --agent command-line option. Agent IDs are case-sensitive.

Select an agent based on the CLI already approved and authenticated for your environment. NIA does not provide the external agent, its subscription, or its credentials.

Prerequisites

Before configuring an agent, make sure that:

• NIA is installed and available as nia in your PATH.
• The selected agent CLI is installed and available in your PATH, or you know its executable path.
• The selected agent is authenticated according to its own product requirements.
• You have initialized NIA in the repository with nia config init.
• You can run the agent in an isolated development environment.

Use the external agent’s installation and authentication documentation for provider-specific prerequisites. NIA verifies the executable and authentication through the selected agent integration; it does not replace the agent’s login process.

Install a Supported Agent

Install only the agent that your project uses. The commands below install the external CLIs; they do not install NIA.

Install GitHub Copilot CLI

Before installing GitHub Copilot CLI, make sure that Node.js and npm are available and that your GitHub account has access to GitHub Copilot. Install the CLI globally, then verify the executable:

npm install -g @github/copilot
copilot --version

Authenticate with GitHub CLI before running NIA workflows:

gh auth login
gh auth status

NIA uses the standalone copilot command by default. Do not configure GitHub Copilot with command = "gh" or command = "gh.exe"; NIA rejects that wrapper because long prompts can exceed Windows command-line limits.

Install OpenCode CLI

Before installing OpenCode, make sure that the shell can run the installer and that you have credentials for the model provider you plan to use. Install OpenCode with its official installer, then verify the executable:

curl -fsSL https://opencode.ai/install | sh
opencode --version

Complete OpenCode’s provider authentication flow before using NIA. Then test a minimal request:

opencode run hello

OpenCode can also use a custom executable path through the command setting described in Configure an Agent Command.

Install Claude Code CLI

Before installing Claude Code, make sure that Node.js and npm are available and that you have an Anthropic API key. Set ANTHROPIC_API_KEY in the environment used to run NIA:

export ANTHROPIC_API_KEY="your-anthropic-api-key"

On PowerShell, use $env:ANTHROPIC_API_KEY = "your-anthropic-api-key" instead. Do not commit the key or place it in an NIA configuration file.

Install the CLI globally, then verify the executable:

npm install -g @anthropic-ai/claude-code
claude --version

Complete Claude Code’s authentication flow before using NIA. Test a headless request with the same permission and output modes that NIA uses:

claude -p "hello" --permission-mode auto --output-format json

Claude Code’s --permission-mode auto allows headless execution without interactive approval prompts. Run it only in the isolated environment described in the warning at the start of this article.

Initialize NIA with the balanced Claude Code model profile:

nia config init --agent claude_code --models balanced

Run a workflow or ask a question with Claude Code explicitly selected:

nia issue draft --agent claude_code
nia ask "Question" --agent claude_code

Understand the Agent Workflow

NIA uses the following flow for a workflow command:

1. NIA loads .nia/config/agents.toml and selects the configured default agent.
2. A command-line --agent selection can choose a specific registered agent for the current command.
3. NIA creates the selected agent with its configured command override, when one exists.
4. NIA verifies that the executable is available and that the agent can authenticate.
5. NIA sends the generated workflow prompt to the agent in headless mode.
6. NIA captures the agent output and records workflow session information.

The external agent remains responsible for model access, credentials, and provider-specific command behavior. NIA supplies the workflow prompt and coordinates execution.

Configure the Default Agent

Create or edit .nia/config/agents.toml with the following minimum configuration:

schema_version = "1.0.0"

[agent]
default = "github_copilot"

The default value must match one of the built-in IDs listed in Choose an Agent. NIA uses GitHub Copilot when the file selects github_copilot, OpenCode when it selects opencode, and Claude Code when it selects claude_code.

Select OpenCode

schema_version = "1.0.0"

[agent]
default = "opencode"

Select Claude Code

schema_version = "1.0.0"

[agent]
default = "claude_code"

NIA loads agent configuration hierarchically. A repository configuration takes part in the project configuration hierarchy, and user or system configuration can be enabled through the external-source settings described in Hierarchical Configuration. Keep shared configuration limited to settings that are appropriate for every repository that uses it.

Configure an Agent Command

NIA uses the default executable name for each agent unless you set command under the corresponding agent table:

schema_version = "1.0.0"

[agent]
default = "opencode"

[agent.opencode]
command = "/opt/opencode/bin/opencode"

Use an executable name when the command is in PATH, or use an absolute path when the executable is installed elsewhere. NIA validates command values and rejects empty values and shell operators.

For GitHub Copilot, do not set command = "gh" or command = "gh.exe". NIA rejects the GitHub CLI wrapper because it can fail with long workflow prompts. Remove the override so NIA can discover the Copilot installation, install the standalone CLI, or set an explicit path to the Copilot executable.

Configure Model and Agent Options

Add optional settings under the selected agent table:

schema_version = "1.0.0"

[agent]
default = "github_copilot"

[agent.github_copilot]
model = "gpt-4o"
custom_agent = "code-reviewer"
prompt_format = "markdown"

NIA supports these settings at the agent level:

You can also set model, custom_agent, and prompt_format for individual targets or operations with the extended target and operation forms:

[agent.github_copilot.targets]
code = { model = "gpt-4o", custom_agent = "code-reviewer" }

[agent.github_copilot.operations]
"code.review" = { model = "gpt-4o", prompt_format = "markdown" }

Use the AI Model Selection article for model names and provider-specific guidance.

Initialize Configuration with a Profile

NIA can generate an agent configuration during initialization. Use the configuration command from the repository root:

nia config init --agent github_copilot

Replace github_copilot with opencode or claude_code when you want another built-in agent. NIA writes the generated file to .nia/config/agents.toml. If the file already exists, NIA preserves it instead of regenerating the configuration.

When the initialization flow asks for a model profile, choose the profile that matches the external agent and the project requirements. Review generated values before running an autonomous workflow.

Verify the Configuration

Run configuration validation from the repository root:

nia config validate

Validation checks the TOML structure, the required schema_version and agent.default values, command overrides, model values, and supported configuration fields. Warnings about unknown model names do not necessarily prevent execution, because new, preview, or custom models can be valid for the external agent.

Run the status command after validation:

nia status

NIA reports installation and authentication health for the configured dependency check. GitHub Copilot authentication uses GitHub CLI authentication status. The current status implementation does not provide equivalent provider-specific status checks for every registered agent, so test OpenCode or Claude Code directly with a minimal command when nia status does not reflect the selected agent.

If the status command reports a problem, fix the external agent installation or authentication first. Then rerun nia status from the repository that contains .nia/config/agents.toml. For a definitive check of the selected agent, run its own version and minimal-prompt commands.

Run a Workflow

After validation succeeds, run a low-risk workflow in an isolated checkout:

nia code review

Use a specific agent for one command with --agent:

nia code review --agent opencode

The command-line selection applies to that workflow invocation. The configured default remains unchanged.

Troubleshoot Agent Setup

NIA Cannot Find the Agent

Symptom: NIA reports that the selected agent is not installed or cannot be found.

Resolution:

1. Run the agent’s version command directly, such as copilot --version, opencode --version, or claude --version.
2. Confirm that the executable directory is in PATH.
3. Set command to the executable name or absolute path in the matching [agent.<id>] table.
4. Run nia config validate, then run nia status again.

NIA Reports an Authentication Failure

Symptom: The executable is available, but NIA reports that authentication failed.

Resolution:

1. Run the external agent’s authentication or login flow.
2. Confirm that the required subscription, account, or provider credentials are available to the same user that runs NIA.
3. Test the agent directly with a minimal prompt using the agent’s own documented command.
4. Run nia status again.

NIA does not store or refresh provider credentials. Follow the external agent’s security guidance for API keys, tokens, and account sessions.

NIA Uses the Wrong Agent

Symptom: A workflow runs with a different agent than expected.

Resolution:

1. Check [agent].default in the loaded agents.toml file.
2. Check whether the command includes --agent, which selects an agent for that invocation.
3. Confirm that the agent ID uses an underscore, such as github_copilot or claude_code.
4. Run nia config validate from the repository root.

NIA Rejects the Agent Configuration

Symptom: Validation reports a configuration error.

Resolution:

1. Confirm that schema_version is present and non-empty.
2. Confirm that [agent].default is present and non-empty.
3. Use a supported built-in ID: github_copilot, opencode, or claude_code.
4. Remove empty command values and shell operators from command settings.
5. Remove command = "gh" or command = "gh.exe" for GitHub Copilot.
6. Run nia config validate again.

Best Practices

Follow these practices when you configure and run AI coding agents:

• Use a dedicated development container or sandbox for autonomous workflows.
• Start with one default agent and add target or operation overrides only when the workflow requires them.
• Keep credentials outside repository files and follow the external agent’s credential-management guidance.
• Validate configuration after changing agents.toml.
• Test the external CLI directly before troubleshooting NIA integration.
• Run a read-only or review workflow before allowing a workflow that modifies files.
• Inspect the generated changes, command output, and session records before accepting results.
• Keep the selected agent and model documented for reproducible team workflows.

Limitations and Considerations

NIA does not provide the external agent executable, model service, account, subscription, or credentials. Each provider can change its installation, authentication, command-line options, and model availability independently of NIA.

NIA includes three built-in agent integrations. The registry can support additional implementations in code, but an arbitrary default value in agents.toml does not create a new agent.

Headless execution can bypass interactive approval prompts. Treat prompts, repository content, toolchain commands, and agent output as inputs that require review in the environment where NIA runs.

Related Information

• Select and configure models for model names and per-target settings.
• Resolve agent configuration across locations for repository, user, and system configuration sources.
• Configure the project before running workflows.
• Review agent troubleshooting guidance for broader runtime diagnostics.
• Start with the Quick Start workflow for an end-to-end setup path.

AI Model Selection

Configure the AI model that NIA passes to your selected coding agent. NIA supports a default model, target-specific overrides, operation-specific overrides, and generated model profiles.

Model selection helps administrators standardize agent behavior across a project and helps users choose a practical cost and quality tradeoff. NIA does not score models by latency, context size, multimodal capability, or price. It resolves the model name in configuration and lets the selected agent handle execution.

Understand Model Selection

NIA resolves a model for each workflow from the most specific applicable setting:

1. An operation-specific setting, such as issue.draft.
2. A target-specific setting, such as issue.
3. The agent’s default model setting.
4. No model, when none of these settings exists.

A command-line model override has higher precedence than the configuration levels above. NIA validates the override and then passes it to the selected agent.

A target is the broad workflow area, such as issue, code, or pr. An operation combines a target and an action, such as issue.draft or pr.review.

Supported Agents and Profiles

NIA is currently optimised for the Anthropic model family, especially the 4.5 series which has a good balance of cost and performance. There are pre-defined model profiles to help you get started quickly. Otimised and validated prompts for other model families are in progress.

NIA can generate model settings for these agent IDs:

• claude_code—Claude Code CLI.
• github_copilot—GitHub Copilot CLI.
• opencode—OpenCode CLI.

The available profiles are:

• lite—Minimize costs with fast or inexpensive models.
• balanced—Upgrade models for additional planning & review at a reasonable cost.
• stable (recommended) —Configured for reliable & predictable behavior.
• heavy—Uses high-cost models for most operations.

Profile names are case-insensitive when supplied to nia config init. An invalid profile stops initialization and reports the valid values.

GitHub Copilot Profile Mappings

The generated defaults and operation overrides for github_copilot are:

OpenCode Profile Mappings

OpenCode supports multiple model providers as a backend so we fallback to a value of auto when generating the profile.

The generated default and operation model for every opencode profile is auto. The lite, balanced, and stable profiles generate overrides for issue.draft, issue.plan, issue.review, pr.review, and pr.merge; heavy generates no operation overrides.

We recommend you replace default value with provider/claude-sonnet-4.5 and the target-operation over-rides with provider/claude-opus-4.5.

Claude Code Profile Mappings

The generated defaults and operation overrides for claude_code are:

Note that Claude Code uses hyphens in the mode version. For example 4-5 instead of 4.5 in the model name.

Configure Model Selection

Store model settings in .nia/config/agents.toml. The agent.default value selects the agent whose settings NIA resolves. Each agent settings table can contain model, targets, and operations.

Defining a model at the right level of control depends on what you need:

• Use a generated profile when you want NIA to create agent-specific defaults and operation overrides.
• Set only model when one model should handle every target and operation.
• Set targets when different workflow areas need different models.
• Set operations when one action needs a different model from the rest of its target.
• Use a command-line model override for a single execution.

NIA does not determine which model is superior for a task. The profile mapper assigns model names and operation overrides for each supported agent. For manually selected models, use names accepted by the selected agent.

Configure a Default Model

Use model when every workflow should use the same model:

schema_version = "2.1.0"

[agent]
default = "github_copilot"

[agent.github_copilot]
model = "claude-sonnet-4.5"

The schema_version and agent.default fields are required. The agent table name must match the selected agent ID.

Configure Target-Specific Models

Use targets when each target needs a different model:

schema_version = "2.1.0"

[agent]
default = "github_copilot"

[agent.github_copilot]
model = "claude-sonnet-4.5"  # Default

[agent.github_copilot.targets]
issue = "claude-haiku-4.5"  # Use Haiku issues
code = "claude-opus-4.5"       # Use Opus for code

The target setting can be a model string or an extended table when you also need commit, custom-agent, or prompt-format settings. The model string form shown above remains supported.

Result:

• nia issue draft uses claude-haiku-4.5.
• nia code review uses claude-opus-4.5.
• nia pr create uses claude-sonnet-4.5 from the default setting.

Configure Operation-Specific Models

Use operations when one operation needs a more specific override:

schema_version = "2.1.0"

[agent]
default = "github_copilot"

[agent.github_copilot]
model = "claude-sonnet-4.5"

[agent.github_copilot.targets]
issue = "claude-haiku-4.5"

[agent.github_copilot.operations]
"issue.draft" = "claude-opus-4.5"  # Premium for drafting
"code.review" = "claude-opus-4.8" # Max for code review

The operation key uses the form target.operation. NIA checks the complete key, such as issue.draft, before it checks the target setting.

Result:

• nia issue draft uses claude-opus-4.5.
• nia issue triage uses claude-haiku-4.5 from the issue target setting.
• nia code review uses claude-opus-4.8.
• nia code refactor uses claude-sonnet-4.5 from the default setting.

Use Supported Model Names

NIA validates model names with agent-specific patterns. Even though it is currently recommended to use the Claude Sonnet-4.5 and Opus-4.5 models, NIA does not restrict you from using others. Validation produces warnings for unknown models; it does not block execution when the name has a valid format.

NIA warns when a model is empty, contains invalid characters, or does not match the selected agent’s known patterns. A model that has a valid-looking format but is not in the known list produces a warning and execution continues.

For GitHub Copilot, the warning uses this form:

Warning: Model 'gpt-6-preview' doesn't match known patterns.
Known patterns for github_copilot: claude-{tier}-{version}, gpt-{version}[-suffix], or 'auto'

GitHub Copilot Model Patterns

GitHub Copilot accepts these patterns:

• auto.
• claude-{tier}-{version}.
• gpt-{version} with optional -codex, -mini, or -max suffixes.

Model names are case-sensitive. The pattern validator allows future and preview versions that match these forms, but the selected agent still determines whether a model is available at execution time.

Other Agent Models

NIA’s model registry provides agent-specific validation for the configured agent. OpenCode profile output uses auto as a provider-neutral value. Claude Code profile output uses Anthropic model names.

Do not treat the representative model names in NIA’s registry as a complete catalog of models provided by an external agent.

Initialize Model Profiles

Use nia config init with --agent to generate an agent configuration. When --models is omitted, NIA uses the stable profile:

# GitHub Copilot CLI with cost-conscious development
nia config init --agent github_copilot --models lite

# GitHub Copilot CLI with latest-generation models, balanced cost/quality
nia config init --agent github_copilot --models balanced

# GitHub Copilot CLI with predictable behaviour (default profile when --models omitted)
nia config init --agent github_copilot --models stable

# OpenCode with maximum quality for critical projects
nia config init --agent opencode --models heavy

# If --models is omitted, the stable profile is used automatically
nia config init --agent github_copilot

The --agent flag is required when you use --models. The command supports github_copilot, opencode, and claude_code. Model profiles generate .nia/config/agents.toml; they do not select a provider’s account, install an agent, or verify external model availability.

Use Automatic Model Selection

Most agents now support automatic model routing. NIA does support the use of auto as a model name which is then passed to the selected agent as the model name. While supported, we do not recommend this method as it leads to much more variation in output quality and is not reliable. NIA does not control the agent algorithm that selects a model from prompt complexity, context size, cost, or latency. The selected external agent controls the meaning of auto.

The following existing example is valid for GitHub Copilot’s accepted model pattern:

Example with overrides:

[agent.github_copilot]
model = "auto"  # Auto-select for most operations

[agent.github_copilot.operations]
"issue.plan" = "claude-opus-4.5"  # Force premium for strategic planning
"code.fix" = "claude-haiku-4.5"   # Force fast for quick fixes

Troubleshoot Model Selection

Fix a Missing Agent Flag

When --models is supplied without --agent, initialization stops with this error:

Error: --agent flag is required when using --models

Use the agent-specific form:

# Instead of:
nia config init --models stable

# Use:
nia config init --agent github_copilot --models stable
# or
nia config init --agent opencode --models stable

Available agents:

• github_copilot - GitHub Copilot CLI
• opencode - Multi-provider AI CLI

Why this changed: Different AI agents support different models. By requiring the --agent flag, nia ensures your configuration matches your chosen agent’s capabilities.

Fix an Unrecognized Model

If the external agent rejects a model, verify the exact model name with that agent’s documentation. NIA’s pattern validation does not prove that the external agent or provider offers the model.

Error: Unknown model 'custom-model'

Fix Configuration That Is Not Applied

Check the configuration in this order:

1. Confirm .nia/config/agents.toml exists and parses as TOML.
2. Confirm agent.default matches the configured agent table.
3. Check the target name against the command target.
4. Check the operation key format, such as issue.draft.
5. Check for a command-line model override, which takes precedence over file settings.
6. Check for warnings from model validation.

Fix Invalid Model Settings

NIA reports these model configuration problems as warnings:

• An empty model string.
• Invalid model-name characters. Valid names use alphanumeric characters, dashes, underscores, dots, and forward slashes in a model name or provider/model name.
• A model that does not match the selected agent’s known patterns.

Review the warning location, such as model, targets.issue, or operations.issue.draft, and correct the corresponding value.

Follow Model-Selection Practices

Apply these practices when managing model configuration:

• Commit .nia/config/agents.toml when the project needs a shared model policy.
• Use generated profiles when you want NIA’s agent-specific mappings.
• Use operation overrides for high-impact actions instead of changing every workflow.
• Keep model names exactly as the selected agent expects them.
• Treat unknown-model warnings as a prompt to verify provider availability.
• Test a profile in the selected agent before relying on it in an automated workflow.
• Review target and operation precedence when a setting appears to be ignored.

Related Information

• Agent Setup Guide explains agent installation and authentication.
• Toolchain Configuration explains the tools and platforms available to agents.
• Workflow Commands describes workflow targets and operations.
• GitHub Copilot CLI Documentation provides external agent documentation.

Prompt Formats

title: Prompt Formats meta_title: Configure NIA Prompt Formats description: Choose XML or Markdown prompt files with automatic model detection and operation, target, or agent-level overrides. slug: prompt-formats

Prompt Formats

NIA supports XML and Markdown prompt formats. The selected format determines which prompt files NIA loads and which parser it uses for prompt metadata.

Choose a Prompt Format

Use XML or Markdown according to the prompt files and model integration used by your project:

• XML uses XML elements and attributes to structure prompt content.
• Markdown uses headings, lists, and fenced blocks to structure prompt content.

NIA selects a format automatically from the model name unless you provide a valid configuration override. You can also set different formats for an agent, target, or operation.

XML Prompt File

<task>
  <title>Task Name</title>
  <description>Task description</description>
  <process>
    <steps>
      <step>First step</step>
      <step>Second step</step>
    </steps>
  </process>
  <output_requirements>
    <output_path>.nia/work/job_{{issue_id}}/</output_path>
    <required_files>
      <file>
        <name>output.md</name>
        <description>Output file description</description>
        <type>single</type>
      </file>
    </required_files>
  </output_requirements>
</task>

Markdown Prompt File

# Task Name

Task description

## Process

1. First step
2. Second step

## Output Requirements

\```yaml
output_path: .nia/work/job_{{issue_id}}/
required_files:
  - name: output.md
    description: Output file description
    type: single
\```

Understand Format Selection

NIA selects the format before it resolves prompt file paths. The selection order is:

1. Operation-specific override.
2. Target-specific override.
3. Global agent override.
4. Automatic detection from the model name.

An invalid value at one level does not stop selection. NIA ignores that value and checks the next level. If no valid override exists, NIA uses automatic detection.

Automatic detection is case-insensitive:

• A model name containing claude or anthropic selects XML.
• Any other model name selects Markdown.
• No model name selects Markdown.

This detection rule examines the model-name text. It does not inspect provider capabilities, prompt length, latency, cost, context size, or multimodal support.

Compare the Formats

Both formats are available to the prompt system, but they use different file extensions and parsers:

The format changes how prompt content is represented and parsed. The source code does not guarantee that every custom prompt produces identical behavior or output in both formats. Keep the instructions and required metadata aligned when you maintain equivalent prompts in both formats.

Configure Prompt Formats

Configure prompt formats in .nia/config/agents.toml. The configuration belongs under the selected agent table. The global prompt_format field applies to that agent unless a target or operation provides a valid override.

Supported format values are xml, markdown, and md. Values are case-insensitive. The md alias resolves to Markdown.

Set a Global Format

Apply one format to all operations for an agent:

[agent.github_copilot]
prompt_format = "markdown"  # or "xml"

The setting does not change the selected model. It changes the format NIA uses when composing prompts for that agent.

Set a Target Format

Set different formats for broad workflow targets:

[agent.github_copilot.targets]
issue = { model = "gpt-5.4", prompt_format = "markdown" }
code = { model = "claude-sonnet-4.5", prompt_format = "xml" }

The target setting uses the extended form because it contains both model and prompt_format. Target settings can also contain the other supported target-level properties, such as commit or custom-agent overrides.

Set an Operation Format

Set a format for a specific target and operation:

[agent.github_copilot.operations]
"issue.plan" = { model = "claude-opus-4.7", prompt_format = "xml" }
"code.review" = { model = "gpt-5.4", prompt_format = "markdown" }

Use the target.operation key form. The operation setting has higher precedence than the target and global settings.

Apply Precedence

When multiple valid format settings apply, NIA uses this order:

1. Operation-specific—For example, operations["issue.plan"].prompt_format.
2. Target-specific—For example, targets.issue.prompt_format.
3. Global agent—The agent-level prompt_format field.
4. Automatic detection—The model-name rule described earlier.

For example:

[agent.github_copilot]
prompt_format = "markdown"  # Global: Markdown

[agent.github_copilot.targets]
issue = { prompt_format = "xml" }  # Target override: XML for issue

[agent.github_copilot.operations]
"issue.draft" = { prompt_format = "markdown" }  # Operation override wins

In this configuration:

• nia issue draft uses Markdown from the operation override.
• nia issue plan uses XML from the target override.
• nia code review uses Markdown from the global setting.

Use Format Aliases

NIA accepts these format values:

Other values are invalid for format selection. NIA ignores an invalid override and continues with the next precedence level. If all configured values are invalid, NIA falls back to model detection.

Select a Format for Common Scenarios

Use these decision rules when configuring a project:

• Keep automatic selection when the model-name rule matches the format used by your prompt files.
• Set a global override when one agent must consistently load one format.
• Set a target override when issue, code, or pull-request workflows use different formats.
• Set an operation override when one operation needs a different format from its target.
• Use the same explicit format at each relevant level when a team needs predictable configuration across model changes.

Troubleshoot Prompt Format Selection

Prompt Files Do Not Load

Check the selected format before checking the prompt content. NIA chooses the format before resolving prompt paths, and the format determines the directory name and file extension:

• XML uses the xml directory name and .xml extension.
• Markdown uses the markdown directory name and .md extension.

If the model name does not contain claude or anthropic, automatic detection selects Markdown. Add a valid explicit override when the project stores the required prompt in the other format.

An Override Does Not Apply

Check the override value and its location:

1. Use only xml, markdown, or md as the value.
2. Confirm the setting appears under the selected agent table.
3. Confirm target settings use the extended table form when setting prompt_format.
4. Confirm operation keys use the target.operation form.
5. Check for a higher-precedence valid operation or target override.

NIA ignores invalid values instead of treating them as a format. For example, prompt_format = "json" falls through to the next selection level.

The Model Uses an Unexpected Format

Inspect the resolved model name and all format settings. Automatic detection checks whether the model name contains claude or anthropic, without requiring a specific version or provider. A name such as claude-sonnet-4.5 selects XML; a name such as gpt-5.4 selects Markdown.

Set an explicit global, target, or operation override when automatic detection does not match the prompt files your workflow requires.

Observe Limitations

Prompt Formats has these implementation limits:

• NIA supports XML and Markdown only.
• The automatic rule uses model-name text rather than external model metadata.
• Invalid overrides are ignored and do not produce a format-selection error at the selector level.
• The source code does not define performance differences between XML and Markdown.
• The source code does not guarantee identical output between equivalent XML and Markdown prompts.

Follow Configuration Practices

Apply these practices to keep format selection predictable:

• Keep prompt files and their selected format aligned.
• Use explicit overrides when a model name does not identify the intended format.
• Use operation overrides sparingly so the precedence chain remains easy to inspect.
• Keep equivalent XML and Markdown prompts synchronized when both formats are maintained.
• Validate the exact agent, target, and operation keys in .nia/config/agents.toml before troubleshooting prompt content.

Related Information

• Model Selection explains model names, profiles, and model precedence.
• Agent Setup explains agent configuration and authentication.
• Toolchain Configuration explains the tools and platforms supplied to agents.

Custom Agent Configurations

title: Custom Agent Configurations meta_title: Configure Custom Agents in NIA description: Configure specialized custom agents for NIA workflows with CLI, operation, target, and agent-level selection rules. slug: custom-agent-configurations

Custom Agent Configurations

Custom agent configurations select a named agent persona or configuration within the AI coding agent that NIA invokes. Use them when different workflows need different expertise, such as Python development, security review, or technical writing.

NIA keeps custom-agent selection separate from these settings:

• --agent selects the AI coding agent implementation, such as GitHub Copilot CLI, OpenCode, or Claude Code.
• --custom-agent selects a custom configuration within the selected AI coding agent.
• --model selects the model used by the selected agent.

Why Use Custom Agents

Use custom agents when a workflow needs a specialized persona or instruction set that is already defined in the selected AI coding agent. Common uses include the following:

• Assigning a Python-focused agent to code-generation and code-review operations.
• Assigning a security-focused agent to pull-request reviews.
• Assigning a documentation-focused agent to documentation workflows.
• Keeping a general custom agent as the default while overriding selected targets or operations.

NIA passes the selected custom-agent name to the configured agent. NIA does not define the custom agent’s instructions or validate that the selected agent platform contains a matching configuration.

Prerequisites

Before configuring a custom agent, verify the following requirements:

1. Install and authenticate the AI coding agent selected by NIA.
2. Create the custom agent in that AI coding agent’s configuration system.
3. Add the custom-agent name to .nia/config/agents.toml or pass it with --custom-agent.
4. Use a non-empty custom-agent name.

The exact command for creating a custom agent depends on the AI coding agent platform. For GitHub Copilot CLI, the original setup examples are:

# Create specialized agents for different tasks
gh copilot config set agent python-expert "Expert in Python development and best practices"
gh copilot config set agent code-reviewer "Senior code reviewer focused on quality"
gh copilot config set agent doc-writer "Documentation specialist"

Note: Custom agent configuration varies by AI coding agent platform. Consult the platform documentation for the creation and installation steps.

How Custom Agent Selection Works

NIA resolves one custom-agent value for each workflow command. The resolution process uses this order, from highest to lowest precedence:

1. The --custom-agent command-line option.
2. The operation-specific entry in custom_agent_operations.
3. The target-specific entry in custom_agents.
4. The agent-level custom_agent value.
5. No custom agent when none of the preceding settings applies.

NIA builds the operation key from the target and operation in the form target.operation, such as issue.draft. If an operation-specific entry does not match, NIA checks the target map and then the agent-level default.

When a custom agent is selected, NIA omits the built-in role prompt from the composed prompt. The custom agent supplies its own persona. If no custom agent is selected, NIA includes the role prompt selected for the workflow.

Configure Custom Agents

Store persistent settings in .nia/config/agents.toml. The top-level agent name must match a registered NIA agent, and the agent.default value selects the default agent implementation.

Set an Agent Default

Set custom_agent when one custom agent should apply to all targets and operations that do not have a more specific mapping:

[agent.github_copilot]
custom_agent = "general-assistant"

Use this setting as the baseline for an agent. A matching target or operation entry overrides it.

Set Target Defaults

Use the custom_agents table to map workflow targets to custom-agent names:

[agent.github_copilot.custom_agents]
issue = "issue-specialist"
pr = "pr-reviewer"
code = "code-expert"
docs = "doc-writer"

This configuration applies the following selections:

• nia issue draft uses issue-specialist.
• nia pr review uses pr-reviewer.
• nia code create uses code-expert.
• nia docs generate uses doc-writer.

Use target mappings when all operations for a target share the same custom agent.

Set Operation Overrides

Use custom_agent_operations to map individual target-operation pairs:

[agent.github_copilot.custom_agent_operations]
"issue.draft" = "draft-writer"
"issue.plan" = "planning-expert"
"pr.review" = "senior-reviewer"
"code.create" = "code-generator"
"code.review" = "quality-auditor"

An operation entry overrides both the matching target entry and the agent-level default. Use it when one operation needs specialized instructions without changing the other operations for that target.

Set a Command-Line Override

Pass --custom-agent on an individual workflow command when the selection should apply only to that invocation:

# Use Python expert for issue drafting
nia issue draft --custom-agent python-expert

# Use code reviewer for pull-request review
nia pr review --custom-agent code-reviewer

# Use documentation specialist for documentation generation
nia docs generate --custom-agent doc-writer

# Combine custom-agent and model selection
nia code create --custom-agent python-expert --model claude-opus-4.5

The command-line value takes precedence over every value in agents.toml.

Understand Configuration Properties

The following properties control custom-agent selection in AgentSettings:

The command and model properties are adjacent agent settings. They do not select a custom agent, but they affect which executable and model NIA uses with the selected custom-agent configuration.

NIA also accepts extended target and operation objects in the configuration schema. Those objects include a custom_agent field, but the custom-agent resolver currently reads custom_agents and custom_agent_operations for target and operation selection. Use the dedicated custom-agent maps documented in this article until the resolver supports those extended fields.

Use Non-Empty Names

Custom-agent names are strings. NIA emits a validation warning for an empty agent-level, target-level, or operation-level name. The resolver does not verify the name against the external agent platform.

Use Operation Keys

Operation-specific custom-agent keys must use the target.operation form. NIA emits a configuration warning for a key that does not contain the expected target and operation structure.

Configure the Agent Command

Use the optional command property to override the command or executable path that NIA uses for an agent:

[agent.github_copilot]
command = "/path/to/copilot.exe"  # Direct path to executable

Use Automatic Discovery

When command is omitted, NIA uses automatic discovery for GitHub Copilot CLI. The implementation searches for copilot in PATH, handles native Windows executables, and parses supported Windows npm wrappers. The source code does not specify a universal discovery process for every registered agent.

Use the default when the agent command is available through the environment. Configure command when the executable is installed at a non-standard path or when you need a specific command name.

Avoid Unsupported Commands

The GitHub Copilot CLI checker rejects command = "gh" because the wrapper has Windows command-line length limitations:

[agent.github_copilot]
command = "gh"

Use a native executable or a supported npm installation instead. NIA reports this configuration as unsupported during the installation check.

Use Platform-Specific Paths

Use a direct Windows path with escaped backslashes or forward slashes:

[agent.github_copilot]
# Use double backslashes
command = "C:\\Program Files\\GitHub Copilot CLI\\copilot.exe"

# Or use forward slashes
command = "C:/Program Files/GitHub Copilot CLI/copilot.exe"

Use a direct path on Linux or macOS:

[agent.github_copilot]
command = "/usr/local/bin/copilot"

NIA rejects an empty command and command strings containing shell operators during configuration validation.

Apply Configuration Precedence

Use the following precedence when several custom-agent settings apply:

Resolve Target Settings

This configuration demonstrates target-level resolution:

[agent.github_copilot]
model = "claude-sonnet-4.5"

[agent.github_copilot.custom_agents]
issue = "issue-analyst"
pr = "pr-expert"
code = "coding-specialist"

The result is:

• nia issue draft uses issue-analyst.
• nia pr review uses pr-expert.
• nia code create uses coding-specialist.
• nia job run has no target-specific custom agent and uses no custom agent unless custom_agent is also configured.

Resolve an Operation Override

This configuration demonstrates operation-level precedence:

[agent.github_copilot]
custom_agent = "general-assistant"

[agent.github_copilot.custom_agents]
issue = "issue-specialist"

[agent.github_copilot.custom_agent_operations]
"issue.draft" = "draft-expert"

The result is:

• nia issue draft uses draft-expert from the operation map.
• nia issue refine uses issue-specialist from the target map.
• nia pr review uses general-assistant from the agent default.

Resolve a CLI Override

A CLI value overrides the configuration file:

# Configuration sets an operation-specific custom agent.
# The CLI option takes precedence.
nia issue draft --custom-agent my-special-agent

NIA uses my-special-agent for that invocation, even when the configuration contains another operation, target, or default value.

Handle Roles with Custom Agents

When NIA composes a prompt with a custom agent, it omits the built-in role prompt. This prevents the built-in persona from being combined with the custom agent’s persona.

If a command supplies both --role and --custom-agent, the custom agent takes precedence for prompt composition and the built-in role prompt is omitted. Do not use both options when the custom agent already defines the required persona.

Use --role when the workflow should use one of NIA’s built-in roles:

• product_manager
• software_architect
• software_engineer
• technical_writer
• sre
• security_analyst

Use --custom-agent when the selected AI coding agent provides a specialized configuration that should define the persona.

Configure Common Scenarios

Configure a Python Team

Use one default Python agent and operation-specific variants:

[agent.github_copilot]
custom_agent = "python-expert"

[agent.github_copilot.custom_agent_operations]
"code.create" = "python-generator"
"code.review" = "python-reviewer"

Configure Documentation Workflows

Use target and operation mappings for documentation work:

[agent.github_copilot.custom_agents]
docs = "doc-specialist"
issue = "doc-planner"

[agent.github_copilot.custom_agent_operations]
"docs.generate" = "technical-writer"
"docs.update" = "doc-editor"

Enforce Code Quality Reviews

Use specialized reviewers for code and pull-request workflows:

[agent.github_copilot.custom_agents]
code = "quality-enforcer"
pr = "senior-reviewer"

[agent.github_copilot.custom_agent_operations]
"code.review" = "strict-auditor"
"pr.review" = "security-reviewer"

Combine Model and Custom-Agent Selection

The following complete configuration combines model settings with custom-agent settings:

schema_version = "2.1.0"

[agent]
default = "github_copilot"

[agent.github_copilot]
# Default model for all operations
model = "claude-sonnet-4.5"

# Default custom agent for all operations
custom_agent = "general-assistant"

# Target-specific models
[agent.github_copilot.targets]
issue = "claude-sonnet-4.5"
code = "gpt-5.2-codex"
pr = "claude-sonnet-4.5"

# Target-specific custom agents
[agent.github_copilot.custom_agents]
issue = "issue-specialist"
code = "code-expert"
pr = "pr-reviewer"

# Operation-specific models (highest precedence)
[agent.github_copilot.operations]
"issue.plan" = "claude-opus-4.5"
"code.review" = "gpt-5.1-codex-max"

# Operation-specific custom agents (highest precedence)
[agent.github_copilot.custom_agent_operations]
"issue.draft" = "draft-writer"
"code.create" = "code-generator"
"pr.review" = "senior-reviewer"

The simple string form remains valid for model-only target and operation settings. Use the dedicated custom-agent maps for custom-agent selection.

Troubleshoot Custom Agent Configuration

Custom Agent Is Not Found

NIA passes the configured name to the selected AI coding agent but does not verify that the external platform defines it. When the platform reports that an agent is missing, check the following items:

1. Verify that the custom agent exists in the selected AI coding agent.
2. Check the spelling and casing of the custom-agent name.
3. Confirm that the selected AI coding agent supports custom agents.
4. Review the platform-specific command for listing or configuring agents.

Configuration Has No Effect

Check the resolution source and key names:

1. Confirm that the command uses the intended NIA agent through --agent or agent.default.
2. Check for a CLI --custom-agent value, which overrides the file.
3. Confirm that operation keys use target.operation, such as issue.draft.
4. Confirm that target mappings appear under custom_agents.
5. Confirm that operation mappings appear under custom_agent_operations.
6. Check whether a higher-precedence value is selecting another custom agent.

Enable debug logging when you need to inspect command execution:

RUST_LOG=debug nia issue draft --custom-agent my-agent

Review the workflow trace under .nia/work/job_*/traces/ when the command creates a job and trace file.

Configuration Validation Fails

Check the values that NIA validates locally:

• Remove an empty command or custom-agent value.
• Remove shell operators from command values.
• Replace command = "gh" for GitHub Copilot CLI with a supported executable or omit the field.
• Correct operation keys that do not follow the target.operation form.

A Role Does Not Apply

A custom agent intentionally suppresses the built-in role prompt during prompt composition. Remove --custom-agent when the workflow must use a built-in role, or define the required persona in the external custom-agent configuration.

The Selected Agent Does Not Support Custom Agents

Support depends on the selected AI coding agent implementation and its command-line interface. NIA can continue to execute the workflow without a matching external custom-agent configuration only when the selected agent accepts the invocation. Check the selected agent’s documentation for its custom-agent support and configuration requirements.

Follow Configuration Best Practices

Use these practices to keep custom-agent selection predictable:

• Use clear, consistent names such as python-expert, code-reviewer, and doc-writer.
• Document each custom agent’s purpose in the external agent configuration.
• Start with an agent-level default before adding target or operation overrides.
• Add operation-specific entries only when a target-level agent is not specific enough.
• Keep target and operation keys aligned with the workflow commands that use them.
• Test a custom-agent selection before committing .nia/config/agents.toml.
• Keep model selection and custom-agent selection explicit when both settings matter.
• Use the dedicated legacy-compatible custom-agent maps until extended target and operation custom-agent fields are supported by the resolver.

Reference

Related Information

• Agent Setup explains how to configure and authenticate NIA agents.
• Model Selection explains model precedence and model profiles.
• Prompt Formats explains XML and Markdown prompt selection.
• Toolchain Configuration explains the tools and platforms supplied to agents.

AI Coding Agent Troubleshooting Guide

Use this guide when NIA cannot find an AI coding agent, load project configuration, compose a prompt, or complete a workflow. Start with the status check, then follow the issue that matches the observed error.

Before You Begin

Run commands from the NIA project directory. NIA detects the project root from a .git or .nia directory when available.

Keep these details available when investigating a failure:

• The NIA command and operation that failed.
• The complete error message.
• The configured agent name and command.
• The job ID, when the command created a job.
• The relevant files under .nia/work/<job_id>/traces/.

Do not include API keys, access tokens, or other secrets when sharing diagnostic output.

How Troubleshooting Works

Use this diagnostic sequence:

1. Run nia status --verbose to check the detected project root, the configured coding agent, authentication, toolchain configuration, and configuration warnings.
2. Correct installation, authentication, or configuration problems reported by the status check.
3. Run the failed workflow again and record its job ID.
4. Inspect the trace files for the failed job.
5. Compare the command context, selected agent, model, custom agent, prompt format, and toolchain settings with the intended configuration.

The status command reports problems without failing when the toolchain file is missing. A missing toolchain configuration still prevents workflows that require the toolchain from operating correctly.

Run the Initial Diagnostics

Run a Status Check

Run the verbose status check first:

nia status --verbose

The command reports the following information:

• The detected project root and whether NIA is initialized.
• The default coding agent and its installation status.
• The agent authentication status.
• The toolchain configuration status.
• Configuration warnings when verbose output is enabled.
• The validation duration when verbose output is enabled.

Run the shorter form when you need the same checks without timing and warning details:

nia status

Inspect Workflow Traces

NIA stores session traces under the job directory. List the files for a known job ID:

Get-ChildItem .nia/work/<job_id>/traces

On Linux or macOS, use:

ls .nia/work/<job_id>/traces/

Trace files use the .md extension. Read the trace file that belongs to the failed operation:

Get-Content .nia/work/<job_id>/traces/<trace-file>

On Linux or macOS, use:

cat .nia/work/<job_id>/traces/<trace-file>

A missing traces directory can mean that the job does not exist or that the workflow did not create a trace.

Resolve Agent Installation Problems

NIA Cannot Find the Coding Agent

Symptoms

The status check reports that the coding agent is not installed, or NIA reports an agent installation error.

Exact error message

The agent dependency check returns:

<agent-name> is not installed or not found in PATH.

The status command displays not installed and then reports the underlying error.

Possible Causes

NIA cannot execute the configured command, the command is not in PATH, or the configured command exits unsuccessfully when NIA runs --version.

For GitHub Copilot CLI, NIA uses copilot when no command override exists. On Windows, NIA also handles supported npm wrapper scripts and native executables.

Resolution

1. Check the configured command in .nia/config/agents.toml.
2. Run the configured command with --version.
3. Add the command to PATH, or set an absolute executable path in the agent configuration.
4. Run nia status --verbose again.

Use a direct command or executable path when required:

[agent.github_copilot]
command = "/path/to/copilot.exe"  # Direct path to executable

On Windows, use escaped backslashes or forward slashes:

[agent.github_copilot]
# Use double backslashes
command = "C:\\Program Files\\GitHub Copilot CLI\\copilot.exe"

# Or use forward slashes
command = "C:/Program Files/GitHub Copilot CLI/copilot.exe"

Verification

Run both commands and confirm that the status output identifies the agent as installed:

<configured-command> --version
nia status --verbose

Additional Notes

NIA rejects command = "gh" for GitHub Copilot because the GitHub CLI wrapper has Windows command-line length limitations. Remove that setting and allow automatic detection, or configure a supported executable path.

NIA Uses the Wrong Agent

Symptoms

NIA checks or runs a different coding agent than the one you intended to use.

Exact status message

When no default agent is configured, the status command displays:

No default coding agent configured

Possible Causes

The agent.default value selects the configured default agent. NIA does not silently replace an absent or unknown default with another agent.

Resolution

Set the intended default agent in .nia/config/agents.toml:

[agent]
default = "github_copilot"

Use the agent identifier supported by the current NIA build. The source registry includes github_copilot, opencode, and claude_code; configuration support for another identifier requires verification against the current build.

Verification

Run:

nia status --verbose

Confirm that the reported coding agent matches the agent.default value.

Additional Notes

The selected NIA agent implementation and the model or custom-agent settings are separate configuration choices. See Custom Agent Configurations for custom-agent selection.

Resolve Authentication Problems

The Agent Is Installed but Not Authenticated

Symptoms

NIA reports that the agent is installed but not authenticated, or dependency validation returns an authentication error.

Exact error message

For the GitHub Copilot dependency path, NIA returns:

GitHub Copilot CLI is not authenticated.

To fix:
1. Run: gh auth login
2. Follow the authentication prompts
3. Verify with: nia status

The status command displays (not authenticated).

Possible Causes

The configured agent rejected its authentication check, the authentication session expired, or the credentials required by the external agent are unavailable.

For the GitHub Copilot dependency check, NIA runs gh auth status after confirming that the configured agent command is installed.

Resolution

1. Run the authentication command required by the selected AI coding agent.
2. Confirm that the command completes successfully.
3. Run nia status --verbose again.

For the GitHub Copilot dependency path, the source error provides this command:

gh auth login

Verification

Run:

gh auth status
nia status --verbose

The status check should report the agent as authenticated.

Additional Notes

NIA does not store external agent credentials in .nia/config/agents.toml. Do not place secrets in configuration files or trace files.

Authentication Details Are Unclear

Symptoms

The status output reports an authentication failure but does not identify which external credential is invalid.

Exact status message

The status command displays:

(not authenticated)

With --verbose, it also displays the agent-specific error after Error:.

Possible Causes

Authentication behavior belongs to the selected agent implementation and its external service. The NIA source verifies the result of the agent-specific check; it does not define every provider’s credential format.

Resolution

1. Run the selected agent’s own authentication or status command.
2. Confirm that the command succeeds outside NIA.
3. Re-run nia status --verbose.
4. If the external command succeeds but NIA still reports a failure, capture the complete NIA status output and the configured command for support.

Verification

Run the external agent check and then:

nia status --verbose

Additional Notes

NIA verifies the result of the selected agent’s authentication check. It does not define one authentication procedure for every provider.

Resolve Custom-Agent Problems

A Custom Agent Does Not Apply

Symptoms

The workflow runs, but it uses the built-in role prompt or a different custom-agent configuration than expected.

Exact status message

There is no dedicated custom-agent error when the external platform does not define the requested name. An empty custom-agent value produces a configuration warning whose exact text is reported in the Configuration Warnings: section of nia status --verbose.

Possible Causes

NIA resolves custom agents in this order:

1. The --custom-agent command-line option.
2. custom_agent_operations["target.operation"].
3. custom_agents["target"].
4. The agent-level custom_agent value.
5. No custom agent.

The custom-agent resolver reads custom_agents and custom_agent_operations for target and operation mappings. Extended target and operation objects expose a custom_agent field in the schema, but the current resolver does not use those fields.

Resolution

Use the dedicated maps and the exact operation key format:

[agent.github_copilot]
custom_agent = "general-assistant"

[agent.github_copilot.custom_agents]
issue = "issue-specialist"

[agent.github_copilot.custom_agent_operations]
"issue.draft" = "draft-expert"

Use an invocation-level override when you need to test a value:

nia issue draft --custom-agent my-special-agent

Verification

Run the workflow with --custom-agent and inspect the resulting trace. A selected custom agent causes NIA to omit the built-in role prompt from the composed prompt.

Additional Notes

An empty custom-agent name produces a configuration warning. NIA does not verify that the external agent platform defines the named custom agent.

A Built-In Role Does Not Apply

Symptoms

A workflow does not use the role supplied with --role.

Exact prompt behavior

NIA does not emit a separate error. When a custom agent is selected, the composed prompt omits the built-in role prompt.

Possible Causes

When a custom agent is selected, NIA omits the built-in role prompt because the external custom agent supplies its own persona.

Resolution

Remove --custom-agent when the workflow must use a built-in role. NIA supports these built-in role names:

• product_manager
• software_architect
• software_engineer
• technical_writer
• sre
• security_analyst

Verification

Run the workflow without a custom agent and inspect the trace to confirm that the role prompt is present.

Additional Notes

Use --custom-agent for a persona defined by the external agent platform. Use --role for a role built into NIA.

Resolve Prompt Problems

A Prompt Override File Is Missing

Symptoms

NIA reports a missing prompt override file and includes an expected path.

Exact error message

NIA returns this message shape, with values from the override declaration and resolved path:

Error: Prompt override file not found

Declared: [[prompt_overrides]] target="<target>" operation="<operation>" <role-or-task>="<prompt-name>"
Expected: <expected-path>

The configuration declares a custom <role-or-task> prompt, but the file doesn't exist.

Possible Causes

A [[prompt_overrides]] configuration entry declares an override, but the corresponding file does not exist at the expected location.

Resolution

1. Read the expected path from the error.
2. Confirm that the target, operation, prompt type, and format match the override declaration.
3. Create the declared prompt file at the expected path, or remove the override entry when the override is not needed.
4. Run the workflow again.

Verification

Confirm that the expected file exists and that NIA no longer reports MissingOverrideFile.

Additional Notes

NIA loads prompt files only when an override is declared for them. The format affects the expected extension, such as xml or md.

The Selected Prompt Format Is Unexpected

Symptoms

NIA searches for a prompt file with an unexpected extension or in an unexpected prompt directory.

Exact error message

NIA reports the resulting missing file through the same error:

Error: Prompt override file not found

The Declared: and Expected: lines identify the selected target, operation, prompt, and path.

Possible Causes

NIA selects prompt format from the operation, target, or global prompt-format setting before loading prompt files. Without a valid override, model names containing claude or anthropic select XML; other or missing model names select Markdown.

Resolution

Check the format settings in .nia/config/agents.toml:

[agent.github_copilot]
prompt_format = "markdown"

[agent.github_copilot.targets]
code = { model = "claude-sonnet-4.5", prompt_format = "xml" }

Use xml, markdown, or md as the format value. Operation settings have higher precedence than target settings, and target settings have higher precedence than the agent-level setting.

Verification

Confirm that the prompt file uses the selected format’s path and extension:

• XML uses the xml directory name and .xml extension.
• Markdown uses the markdown directory name and .md extension.

Additional Notes

The target and operation examples above reflect the current configuration schema. Confirm the resolver behavior before relying on extended custom-agent fields; prompt-format fields are handled by the prompt-format selector.

Resolve Configuration Problems

The Agent Configuration File Is Missing

Symptoms

NIA reports that no agents.toml file exists when a workflow requires agent configuration.

Exact error message

NIA returns:

Agent configuration required

No agents.toml file found at: <config-path>

Run the following command to configure your AI agent:

 nia config init --agent <AGENT_NAME>

Possible Causes

The project has not initialized NIA agent configuration, or the command runs outside the intended project root.

Resolution

1. Change to the project directory.
2. Run the initialization command shown by the error:

nia config init --agent <AGENT_NAME>

3. Set the default agent in .nia/config/agents.toml.
4. Run nia status --verbose.

Verification

Confirm that .nia/config/agents.toml exists and that the status output identifies the selected coding agent.

Additional Notes

The supported initialization examples are github_copilot, opencode, and claude_code. Use one of these agent identifiers when running nia config init.

The Toolchain Configuration Is Missing

Symptoms

The status check reports that .nia/config/toolchain.toml is missing.

Exact status message

The status command displays:

Toolchain: Missing (REQUIRED)

Possible Causes

The project has not created its toolchain configuration.

Resolution

Run the initialization command with the required agent, issue, and code values:

nia config init --agent <agent> --issues <name> --code <name>

The status command displays this example for a GitHub configuration:

nia config init --agent github_copilot --issues github_issues --code github

Verification

Run:

nia status --verbose

The toolchain status should report the configuration as configured.

Additional Notes

The status command reports a missing toolchain file without failing. Workflows that need issue or code-platform configuration still require a valid toolchain file.

Configuration Syntax or Validation Fails

Symptoms

NIA reports a TOML parsing error, an invalid configuration error, or a validation warning.

Exact error messages

NIA uses these error formats:

TOML parsing error: <parser-message>
Invalid configuration at <file>:<line>: <message>
Validation error: <message>

Possible Causes

The configuration contains invalid TOML, an empty required value, an unsupported command, an invalid operation key, or a semantic validation error.

Resolution

1. Read the file path and line number in the error.
2. Check quotes, brackets, table names, and value types.
3. Check agent-specific validation rules.
4. Run nia status --verbose to display configuration warnings.
5. Correct the file and repeat the status check.

For example, an agent command must not be empty and must not contain shell operators:

[agent.github_copilot]
command = "copilot"

Verification

Run:

nia status --verbose

Confirm that the configuration warnings are gone and that the related component reports a valid state.

Additional Notes

NIA distinguishes TOML parsing errors from semantic validation errors. Keep the original error text when reporting a configuration problem.

Resolve Execution Problems

The Workflow Fails During Agent Execution

Symptoms

The agent starts, but the workflow ends with an agent error, a nonzero exit code, or a workflow failure.

Exact error messages

Depending on the failure, NIA uses one of these formats:

Agent error: <agent-name> execution failed: <details>
Agent error: <agent-name> returned invalid response: <details>
Workflow failed in state: <state>

Possible Causes

The selected agent process returned an error, the prompt or configuration could not be resolved, or an external service rejected the request. The exact cause appears in the error and trace output.

Resolution

1. Run the failed command again with RUST_LOG=debug.
2. Record the complete error and job ID.
3. Read the trace under .nia/work/<job_id>/traces/.
4. Check the selected model, custom agent, prompt format, and toolchain values.
5. Test the configured agent command with --version.
6. Correct the reported configuration or external-agent problem and retry.

Use debug logging on Linux or macOS:

RUST_LOG=debug nia issue draft

Use debug logging in Windows PowerShell:

$env:RUST_LOG="debug"; nia issue draft

Verification

The workflow should complete successfully and create the expected output. Keep the trace for comparison if the issue returns.

Additional Notes

NIA records the selected model, custom agent, and agent identifier in workflow transaction metadata when those values are available. Do not share traces that contain confidential prompts or credentials.

An Execution Times Out

Symptoms

A workflow or shell step does not complete within its configured timeout.

Exact error message

The current source does not define one universal timeout error string. Capture the complete operation-specific message from the terminal and debug log.

Possible Causes

The process exceeded the timeout assigned to the operation or shell step. NIA’s automation code applies timeout handling to shell execution, but a universal five-minute agent timeout is not established by the source.

Resolution

1. Read the timeout value and operation from the error or debug output.
2. Check whether the command is waiting for external input.
3. Check agent installation, authentication, and network access using nia status --verbose.
4. Reduce the scope of the operation when the prompt or workflow performs too much work.
5. Configure a larger timeout only where the workflow configuration supports that setting.

Verification

Run the command again and confirm that it completes before the configured timeout.

Additional Notes

The current source does not establish a universal agent timeout or a documented user-facing timeout setting. Use the timeout value reported for the specific operation when diagnosing a failure.

A Job Directory Cannot Be Written

Symptoms

NIA reports an I/O error while creating or writing under .nia/work/.

Exact error message

NIA wraps the operating-system message in this format:

IO error: <operating-system-message>

Possible Causes

The project directory is not writable, the path is unavailable, or the process lacks permission to create the job or trace files.

Resolution

1. Confirm that the project root is the intended directory.
2. Check that .nia/work/ exists or can be created.
3. Check the permissions for the project and .nia/work/.
4. Run the workflow again from an account that can write to the project directory.

On Linux or macOS, inspect the directory with:

ls -ld .nia/work/

Create the directory when it is missing:

mkdir -p .nia/work/

Verification

Run a workflow and confirm that NIA creates a job directory and trace files under .nia/work/<job_id>/.

Additional Notes

Avoid changing permissions or ownership recursively unless your operating system administrator approves the change. The source reports filesystem errors but does not prescribe a universal permission command.

Collect Logs and Diagnostic Data

Enable Debug Logging

Set RUST_LOG to debug for command execution details:

RUST_LOG=debug nia issue draft

In Windows PowerShell, use:

$env:RUST_LOG="debug"; nia issue draft

Use trace when support requests the most detailed logging:

RUST_LOG=trace nia issue draft 2>&1 | tee debug.log

In Windows PowerShell, use:

$env:RUST_LOG="trace"; nia issue draft 2>&1 | Tee-Object -FilePath debug.log

Collect a Support Package

Collect the following information without exposing secrets:

1. NIA version from nia --version.
2. Operating system and shell.
3. Selected NIA agent and configured command.
4. The exact workflow command, with secrets removed.
5. The complete error message.
6. Output from nia status --verbose.
7. The relevant job ID and trace file names.
8. Relevant trace content after removing confidential prompts, tokens, and repository data.

Follow Best Practices

Use these practices to reduce repeated troubleshooting:

• Run nia status --verbose after changing agent or toolchain configuration.
• Keep the configured agent command explicit when automatic discovery does not find the intended executable.
• Use the exact target and operation names defined by the workflow.
• Keep prompt override declarations and prompt files synchronized.
• Preserve the original error message, job ID, and trace path when reporting a failure.
• Remove secrets from logs and traces before sharing them.
• Keep model, custom-agent, and prompt-format settings separate when diagnosing selection problems.

Know the Current Limitations

The following limits are verified by the current implementation:

• NIA’s status command checks the detected project root, coding-agent installation, authentication, and toolchain configuration.
• GitHub Copilot installation checks reject the configured command gh.
• GitHub Copilot authentication checks run gh auth status.
• Custom-agent names are passed to the selected agent; NIA does not verify that the external platform defines each name.
• A selected custom agent suppresses NIA’s built-in role prompt.
• Prompt override files must exist when declared by [[prompt_overrides]] configuration.
• Prompt format selection occurs before prompt files are loaded.
• Trace listing and viewing require a known job ID and read files under .nia/work/<job_id>/traces/.

Additional Resources

• Agent Setup explains how to configure and authenticate NIA agents.
• Custom Agent Configurations explains custom-agent selection and precedence.
• Model Selection explains model resolution and model profiles.
• Prompt Formats explains XML and Markdown prompt selection.
• Toolchain Configuration explains issue, ticket, and code-platform configuration.

Command Structure

Nia CLI v2.0.0 introduces a consistent command structure that separates utility and workflow commands.

Command Pattern

All commands follow this pattern:

nia <target> <operation> [--modifier] [--options]

Components

• Target: The entity you’re working with (e.g., issue, code, pr)
• Operation: The action to perform (e.g., draft, review, merge)
• Modifier: Optional flags that customize behavior (e.g., --edit, --fix)
• Options: Additional arguments (e.g., --complexity high)

Command Types

Utility Commands

Utility commands execute static, deterministic operations. They run quickly and don’t require AI backend.

Examples:

nia config validate           # Validate configuration
nia guide open                # Open Nia user guide
nia shell install bash        # Install shell completions

Characteristics:

• Fast execution (< 100ms)
• Deterministic results
• No AI involvement
• Always available

Workflow Commands

Workflow commands are AI agent-driven operations that perform complex tasks.

Examples:

nia issue draft              # Create a task plan
nia code review              # Review code quality
nia code create --fix        # Create code with fix instructions

Characteristics:

• AI-powered execution
• Variable execution time
• Context-aware results
• Customizable via TOML

Examples

Basic Workflow Command

nia issue draft

Creates a draft task plan.

With Modifier

nia issue draft --edit

Creates a draft task plan with editing instructions.

With Options

nia backlog create --major

Plans a major release.

Complex Command

nia code create --fix

Creates code and applies your fix instructions.

Help System

Get help for any command:

nia --help                   # List all commands
nia issue --help             # List operations for issue target
nia issue draft --help       # Help for specific operation

Command Context

Most workflow commands require context to execute properly:

• Issue ID: Required for issue, code, pr commands
• PR ID: Required for pr commands

Set context via environment variables:

export NIA_ISSUE_ID=123
export NIA_PR_ID=456

nia issue draft              # Uses Issue #123
nia pr review                # Uses PR #456 in Issue #123

If context is missing, commands abort with helpful error messages explaining how to set it.

Command Discovery

Use tab completion to discover available commands:

nia <TAB>                    # Shows all targets
nia issue <TAB>              # Shows operations for issue
nia issue draft --<TAB>      # Shows available modifiers

See Shell Completions for installation.

Application Commands

Application commands enable executing nia operations across multiple related repositories as a coordinated unit. This is useful for:

• Microservices architectures (separate repositories per service)
• Multi-tier applications (API, frontend, backend in separate repos)
• Shared library scenarios (library + consumers)

Command Syntax

nia app <target> <operation> [--modifiers] [--options]

The app prefix wraps any standard nia command to execute it at the application level.

Examples:

nia app issue draft              # Draft issue across all repositories
nia app issue plan               # Plan implementation in each repository
nia app code create              # Create code in each repository
nia app pr create                # Create PRs in each repository

Prerequisites

Before using application commands:

1. Create an application configuration (see Multi-Repository Applications):

   cd /path/to/app-root
   nia config init --app
   

2. Opt-in child repositories by adding allow_app UUID to each repository’s project.toml:

   [project]
   # ... other fields ...
   allow_app = "550e8400-e29b-41d4-a716-446655440000"
   

3. Discover repositories:

   nia app discover
   

Execution Modes

Application commands use two execution modes depending on the operation’s app_workflow configuration:

Direct Execution (Default)

Commands without app_workflow configuration execute once at the application level with full application context:

nia app issue draft              # Executes once with all repo metadata
nia app code review              # Reviews entire feature across repos

Behavior:

• Single execution from application root
• Agent sees all repository metadata
• Output written to application-level job directory
• Fast execution for analysis and planning tasks

Use cases:

• Issue drafting (create multi-repo issue plan)
• Issue splitting (decompose issue into per-repo tasks)
• Code review (review feature implementation across repos)
• Documentation generation (cross-repo docs)

Workflow Execution (Opt-In)

Commands with app_workflow configuration execute a workflow in each child repository independently:

nia app issue plan               # Runs workflow in each repo
nia app code create              # Runs workflow in each repo
nia app pr create                # Runs workflow in each repo

Behavior:

• Workflow runs in each child repository
• Repositories execute in parallel (controlled by --max-workers)
• Each repo has independent context and output
• Context (issue_id, ticket_id) propagated via .nia/context.toml

Use cases:

• Issue planning (create implementation plan per repo)
• Code creation (implement changes in each repo)
• PR creation (create PRs for each repo’s changes)
• Test execution (run tests across all repos)

Command Configuration

Configure which commands use workflow execution via commands.toml:

# Built-in configuration (configs/commands.toml)
[[commands]]
target = "issue"

[[commands.operations]]
name = "plan"
description = "Create implementation plan"
app_workflow = "issue-to-plan"    # Uses workflow execution via nia app

[[commands.operations]]
name = "draft"
description = "Draft issue plan"
# No app_workflow = uses direct execution (default)

Key Points:

• Default behavior: Commands without app_workflow use direct execution
• Extensibility: Any new command automatically works via direct execution
• User override: Users can override via .nia/config/commands.toml

Built-in Execution Method Mappings

Supported Flags

Direct Execution Flags

These flags work with direct execution commands:

nia app issue draft --edit       # Interactive editing
nia app code review --fix        # Include fix suggestions
nia app issue draft --model claude-opus-4.8
nia app issue draft --agent custom-agent
nia app issue draft --role security_expert
nia app issue draft --context-file ./extra-context.txt
nia app issue draft --clear      # Clear job directory first
nia app issue draft --quiet      # Suppress output

Allowed flags:

• --edit, --fix: Interactive modifiers
• --model, --agent, --role: Agent configuration
• --context-file: Additional context
• --clear: Clear previous output
• --auto-retry: Automatic retry on failure
• --quiet: Minimal output

Rejected flags:

• --lite: Never supported for multi-repo operations (comprehensive detail required)

Workflow Execution Flags

These flags work with workflow execution commands:

nia app issue plan --quiet                    # Suppress output
nia app issue plan --bypass-approvals         # Skip approval gates
nia app issue plan --start-from review_code   # Resume from step
nia app issue plan --dry-run                  # Validate without executing
nia app issue plan --max-workers 5            # Parallel execution limit

Allowed flags:

• --quiet, -q: Suppress progress output
• --bypass-approvals: Skip approval gates (for CI/automation)
• --start-from <step>: Resume workflow from specific step
• --dry-run: Validate workflow without execution
• --max-workers N: Limit parallel repository execution (default: 3)

Rejected flags (with helpful error messages):

• --model, --agent, --role: Model/agent selection is defined in workflow configuration
• --context-file: Context is propagated via .nia/context.toml, not flags
• --edit, --fix: Workflow run non-interactively across multiple repositories
• --clear: Workflow context is managed per child repository
• --lite: Never supported for app commands

Context Propagation

Application commands share context across repositories:

Shared Context:

• Issue ID: Same issue applies to all repositories
• Ticket ID: Same ticket applies to all repositories

Per-Repository Context:

• PR ID: Generated independently for each repository
• Job outputs: Stored in each repository’s .nia/work/ directory

Context File: Context is written to .nia/context.toml in each child repository:

[context]
issue_id = "123"
ticket_id = "456"
# pr_id is repository-specific, generated during workflow

Examples

Example 1: Draft Multi-Repository Issue

cd /path/to/my-application

# Draft issue that spans multiple services
nia app issue draft

# Output: Creates draft considering all repositories
# Location: .nia/work/job_XXX/issue.md

Example 2: Plan and Implement Feature

# Set issue context
export NIA_ISSUE_ID=123

# Create implementation plans in each repository
nia app issue plan

# Each repository gets:
# - .nia/work/job_123/code/phase_X.md
# - Context propagated via .nia/context.toml

# Create code implementation in each repository
nia app code create

# Each repository gets:
# - Code changes in src/
# - Tests in tests/
# - Job output in .nia/work/job_123/

Example 3: Parallel Execution Control

# Run workflows in 5 repositories at a time
nia app issue plan --max-workers 5

# Quiet mode for CI/automation
nia app issue plan --quiet --bypass-approvals

Example 4: Custom App Workflow Commands

Users can add custom commands with workflow execution:

# .nia/config/commands.toml
[[commands]]
target = "deploy"

[[commands.operations]]
name = "staging"
description = "Deploy to staging"
app_workflow = "deploy-staging"    # Custom workflow

Then use:

nia app deploy staging    # Runs custom workflow in each repo

Status Tracking

Command execution shows per-repository progress:

Executing workflow 'issue-to-plan' in 3 repositories
  [✓] api-service     (12.3s)
  [✓] web-frontend    (8.7s)
  [⚠] worker-service  (failed - see logs at .nia/work/job_123/logs/)

2 of 3 repositories completed successfully

Status Icons:

• [✓] - Completed successfully
• [⚠] - Failed (with log path)
• [⏳] - In progress
• [⏸] - Awaiting approval

Best Practices

1. Use direct execution for analysis: Issue drafting, code review work best with full application context
2. Use workflow execution for implementation: Code creation, PR creation need per-repo independence
3. Control parallelism: Use --max-workers to avoid rate limiting or resource exhaustion
4. Monitor status: Watch for failures and check logs in failed repositories
5. Propagate context: Always set NIA_ISSUE_ID before starting application workflows
6. Test incrementally: Try commands on single repos before scaling to full application

Troubleshooting

“No repositories found”

Cause: Application has no discovered repositories

Solutions:

nia app discover                 # Discover repositories
nia config show --sources        # Verify discovery results

“Repository UUID mismatch”

Cause: Child repository’s allow_app doesn’t match application UUID

Solutions:

# Check application UUID
grep 'id =' .nia/config/application.toml

# Update child repository
cd child-repo
echo 'allow_app = "uuid-from-above"' >> .nia/config/project.toml

“Workflow not supported”

Cause: Unsupported flags for workflow execution mode

Solution: Remove unsupported flags:

# ❌ Wrong - --model not supported in workflow mode
nia app issue plan --model claude-opus-4.8

# ✅ Correct - model defined in workflow configuration
nia app issue plan

Related Documentation

• Multi-Repository Applications - Setup and configuration
• Workflow Commands - Command system overview
• Context Sources - Context management

Utility Commands

Utility commands are fast, deterministic operations that don’t require AI backend. They’re always available and execute in < 100ms.

config

Configuration management and validation.

validate

Validate workflow configuration files.

nia config validate

Validates:

• .nia/config/commands.toml (if exists)
• Built-in workflows TOML
• Project metadata in nia-config.json
• Schema version compatibility
• Protected namespace conflicts

Output:

• ✅ Success: “Configuration valid”
• ❌ Errors: Detailed validation errors with line numbers

Exit Codes:

• 0 - Configuration valid
• 1 - Validation errors found

Example:

$ nia config validate
✓ Schema version: 2.0.0
✓ Metadata valid
✓ 5 workflows loaded
✓ 28 operations registered
✓ No protected namespace conflicts
Configuration valid

validate –file

Validate a specific TOML file.

nia config validate --file path/to/commands.toml
nia config validate -f path/to/commands.toml   # Short form

Useful for testing custom workflows before deploying.

Example:

$ nia config validate --file examples/workflows/custom_commands.toml
✓ Schema version: 2.0.0
✓ Metadata valid
✓ 2 workflows loaded
Configuration valid

export

Export built-in workflows, prompts, and skills for customization.

Note: You must specify what to export using --commands, --prompts, --workflows, --skills, or --all.

nia config export --all          # Export commands, prompts, and workflows
nia config export --commands     # Export only commands.toml
nia config export --prompts      # Export only prompt files
nia config export --workflows    # Export only workflow files
nia config export --skills       # Export only skill files

Creates:

• .nia/config/commands.toml - All built-in workflow definitions (with --commands or --all)
• .nia/prompts/{xml,markdown}/{target}/ - All built-in prompt files organized by format and target (with --prompts or --all)
  • Note: {xml,markdown} and {target} are placeholders - actual paths will be like .nia/prompts/xml/issue/ or .nia/prompts/markdown/role/
  • Init prompts (e.g., issue_draft.task.xml)
  • Delta prompts (e.g., issue_draft_delta.task.xml)
  • Role prompts (e.g., product_manager.role.xml)
• .nia/config/workflows/ - All built-in workflow files (with --workflows or --all)
  • issue-to-plan.toml - Issue planning workflow
  • issue-to-pr.toml - Full issue-to-PR workflow
  • code-to-review.toml - Code creation and review workflow
  • pr-to-merge.toml - PR review and merge workflow
  • ticket-to-response.toml - Support ticket workflow
• .agents/skills/ - Built-in skill files (with --skills only)

Use Case: Bootstrap your custom workflow configuration by exporting defaults.

Example:

$ nia config export --all
Exporting workflow configuration...
✓ Exported all built-in workflows
  Commands: ./.nia/config/commands.toml
  Prompts:  264 files in .nia/prompts/{xml,markdown}/{target}/
  Workflows: 5 files in .nia/config/workflows/

Next steps:
  1. Edit prompts in .nia/prompts/ as needed
  2. Edit workflow files in .nia/config/workflows/ as needed
  3. Modify .nia/config/commands.toml to customize operations
  4. Run: nia config validate
  5. Run: nia config show

export –target

Export only a specific workflow target.

nia config export --prompts --target <TARGET>   # Long form
nia config export --prompts -t <TARGET>         # Short form (equivalent)

Example:

$ nia config export --prompts --target issue
Exporting workflow configuration...
✓ Exported 60 prompt files
  Location: .nia/prompts/{xml,markdown}/{target}/

Next steps:
  1. Edit prompt files as needed
  2. Reference them in commands.toml

export –workflows

Export only built-in workflow files to .nia/config/workflows/.

nia config export --workflows

Example:

$ nia config export --workflows
Exporting workflow configuration...
✓ Exported 5 workflow files
  Location: .nia/config/workflows/

Next steps:
  1. Edit workflow files as needed
  2. Run: nia workflow run <workflow-name>

Available Built-in Workflows:

• issue-to-plan.toml - Create implementation plan from issue
• issue-to-pr.toml - Complete issue-to-PR automation (planning, coding, review, PR creation)
• code-to-review.toml - Code creation with iterative review and approval
• pr-to-merge.toml - PR review automation with merge checks
• ticket-to-response.toml - Support ticket response workflow

Note: User workflows in .nia/config/workflows/ override built-in workflows of the same name. This allows you to customize specific workflows while keeping others at defaults.

export –force

Overwrite existing configuration and prompt files.

nia config export --all --force       # Long form
nia config export --prompts --force   # Export only prompts

Note: --force has no short flag because it’s a destructive operation that should be typed explicitly.

Warning: This will overwrite any customizations you’ve made. Use with caution.

Example:

$ nia config export --all --force
Exporting workflow configuration...
✓ Exported all built-in workflows
  (existing files overwritten)

Combined Flags:

# Export specific target and overwrite if exists
nia config export --prompts --target code --force
nia config export --prompts -t code --force   # Mixing short and long

export –skills

Export all embedded built-in skill files to .agents/skills/.

Skills are packages of procedural knowledge that agents load on demand, following the Agent Skills open standard.

nia config export --skills              # Auto-detect scope from config location
nia config export --skills --force      # Overwrite existing skills
nia config export --skills --scope=project   # Force project scope
nia config export --skills --scope=user      # Force global user scope

Scope Detection:

When you run --skills without --scope, nia auto-detects based on where your toolchain config is found:

Explicit and Automatic Export:

nia config export --skills exports all embedded built-in skills, regardless of which tools are configured in toolchain.toml. This is useful for browsing or customizing the complete built-in skill library.

Selective export happens automatically during nia config init. The initialization flow installs only skills for selected tools that use method = "skill" and always uses project scope.

Example:

nia config init --issues github_issues --code github
# Installs issue-read-github and pr-read-github

nia config export --skills
# Exports all 18 embedded skills; existing files are skipped

Update Detection:

When an embedded skill already exists, nia compares the version strings in the two SKILL.md frontmatter blocks. Any difference is reported as an available update; Nia does not currently apply semantic-version ordering.

$ nia config export --skills
⚠ Skill updates available:
  - issue-read-github: v1.0.0 → v1.1.0
  - pr-read-github: v1.2.0 → v1.3.0

Run 'nia config export --skills --force' to update
Warning: This will overwrite existing files. Back up custom modifications first.

Example - Project Scope:

$ cd /path/to/repo
$ nia config export --skills
Exporting skills for project scope...
✓ Exported 18 skills to .agents/skills/

Skills are available to AI agents (Copilot, Claude, OpenCode).
Customize skill files to match your team's practices.

Example - User Scope:

$ nia config export --skills --scope=user
Exporting skills for user scope...
✓ Exported 18 skills to ~/.agents/skills/

Skills are available globally across all your projects.

See Also:

• Agent Skills Configuration Guide - Complete guide to skills
• Toolchain Configuration - Configure method = "skill"

user

Set user identity for OpenSearch enterprise reporting.

nia config user --name "John Doe" --email "john@company.com"

Stores user identity in .nia/context.toml for use when git config is unavailable (common in CI/CD environments and containers).

Persistence: Unlike other context values (issue_id, pr_id), user identity persists across nia config clear-context calls since it’s considered persistent configuration.

Resolution Order:

1. Environment variables (NIA_USER_NAME, NIA_USER_EMAIL)
2. Context.toml (this setting)
3. Git config (user.name, user.email)
4. System user (OS username)
5. Descriptive fallback

Arguments:

• --name <NAME> (required): Your full name
• --email <EMAIL> (required): Your email address

Example:

$ nia config user --name "Jane Smith" --email "jane.smith@company.com"
✓ User identity saved to .nia/context.toml

Current identity:
  Name:  Jane Smith
  Email: jane.smith@company.com

CI/CD Usage:

# GitHub Actions
export NIA_USER_NAME="${{ github.actor }}"
export NIA_USER_EMAIL="${{ github.actor }}@users.noreply.github.com"

# GitLab CI
export NIA_USER_NAME="$GITLAB_USER_NAME"
export NIA_USER_EMAIL="$GITLAB_USER_EMAIL"

See OpenSearch Integration for user identity configuration and more CI/CD examples.

guide

Access Nia user documentation.

open

Open the Nia user guide in your default browser.

nia guide open

Opens the mdBook documentation at:

• Local build: file:///path/to/nia/user-docs/book/index.html
• Web hosted: https://your-docs-url (if configured)

Characteristics:

• Uses system default browser
• Works offline (embedded docs)
• Falls back to local file if web unavailable

shell

Shell completion installation and management.

install

Install shell completions for your shell.

nia shell install <SHELL>

Supported Shells:

• bash - Bash completion
• zsh - Zsh completion
• fish - Fish completion
• powershell - PowerShell completion

Behavior:

1. Detects shell profile file (~/.bashrc, ~/.zshrc, etc.)
2. Creates timestamped backup of profile
3. Adds completion source line
4. Prompts to restart shell

Example:

$ nia shell install bash
Detected profile: /home/user/.bashrc
Created backup: /home/user/.bashrc.backup.1703012345
Added completion line to profile
✓ Installation complete

Please restart your shell or run:
  source ~/.bashrc

install –manual

Display manual installation instructions without modifying profile.

nia shell install bash --manual

Output:

Manual installation for bash:

Add this line to your ~/.bashrc:
  source <(nia shell completion bash)

Or generate completion file:
  nia shell completion bash > ~/.nia-completion.bash

Then add to ~/.bashrc:
  source ~/.nia-completion.bash

uninstall

Remove completions from shell profile.

nia shell uninstall <SHELL>

Removes the completion line added by nia shell install, but keeps backup files.

Example:

$ nia shell uninstall bash
Removed completion line from /home/user/.bashrc
Backup preserved: /home/user/.bashrc.backup.1703012345
✓ Uninstall complete

Restart your shell to apply changes.

completion

Generate raw completion script (internal use).

nia shell completion <SHELL>

Generates completion script that can be sourced or saved. Typically used internally by install command.

Example:

$ nia shell completion bash > nia-completion.bash
$ source nia-completion.bash

Performance

All utility commands are designed for instant execution:

Protected Namespaces

The following targets are reserved for utility commands and cannot be overridden by user workflows:

• config - Configuration management
• guide - Documentation access
• shell - Shell completion management
• workflow - Stateful workflow execution and management

Attempting to define workflows with these target names will result in validation errors.

Workflow Commands

Workflow commands are AI-powered operations that perform complex, context-aware tasks. They’re defined via TOML configuration and executed by specialized AI agents.

How Workflow Commands Work

Architecture

User Command → CLI Parser → Workflow Registry → Prompt Composer → AI Agent → Result

1. User runs command: nia issue draft --edit
2. CLI parses command: Extracts target (issue), operation (draft), modifier (edit)
3. Registry lookup: Finds workflow definition in TOML config
4. Prompt composition: Combines role + task + input prompts
5. AI agent execution: Sends composed prompt to AI backend
6. Result display: Shows output to user

Prompt Composition

Each workflow operation uses a multi-part prompt system:

1. Role Prompt: Defines the AI agent’s persona and expertise
2. Project Context: Project metadata from project.config.md segment
3. Task Prompt: Specifies the operation to perform
4. Input File: Optional user-provided context (for modifiers)

Example: nia issue draft --edit

Role: prompts/issue_planner.role.md     (who the agent is)
Project: prompts/project.config.md      (project context)
Task: prompts/issue_draft.task.md       (what to do)
Input: .nia/work/job_<job_id>/issue/edit.md  (user context)

The composed prompt is sent to the AI agent for execution.

Common Short Flags

All workflow commands support these short flags:

Examples:

# Select AI coding agent
nia issue draft -a copilot

# Override AI role
nia code review -r software_engineer

# Include single context file
nia pr review -c docs/architecture.md

# Include multiple context files
nia code create -c docs/design.md -c examples/reference.rs -c CHANGELOG.md

# Combine multiple flags
nia issue plan -a copilot -r software_architect -c docs/requirements.md

Note: The -c flag can be used multiple times to include several files as context for the AI agent.

Built-in Workflows

Nia includes 5 built-in workflow targets:

Context Requirements

Most workflow commands require context to operate:

Issue ID

Required for: issue, code, pr commands

Set via environment variable:

export NIA_ISSUE_ID=123
nia issue draft              # Uses Issue #123

PR ID

Required for: pr commands

Set via environment variable:

export NIA_ISSUE_ID=123
export NIA_PR_ID=456
nia pr review                # Uses PR #456 in Issue #123

No Context Required

These targets work without context:

• backlog - Strategic planning
• docs - Documentation workflows

Missing Context Behavior

If required context is missing, commands abort with helpful error:

$ nia issue draft
Error: Missing required context: NIA_ISSUE_ID

To set Issue ID:
  export NIA_ISSUE_ID=123

Or in GitHub Actions:
  env:
    NIA_ISSUE_ID: ${{ github.event.issue.number }}

Modifiers

Modifiers customize operation behavior without changing the core task.

Common Modifiers

How Modifiers Work

Modifiers can:

1. Override task prompt: Use different task prompt (e.g., issue_draft → issue_draft_edit)
2. Load input file: Read user context from .nia/work/job_<job_id>/<target>/<modifier>.md

Example: nia code review --fix

• Task prompt changes: code_review → code_review_fix
• Input file checked: .nia/work/job_<job_id>/code/fix.md (optional)

Input Files

Input files provide job-specific context to modifiers:

# Create input file
mkdir -p .nia/work/Job_42/issue
cat > .nia/work/Job_42/issue/edit.md << 'EOF'
Focus on:
- Performance requirements
- Security considerations
EOF

# Run with modifier
export NIA_JOB_ID=Job_42
nia issue draft --edit       # Reads edit.md as additional context

Note: Input files are optional. Execution proceeds normally if file doesn’t exist.

Execution Flow

Standard Execution

$ nia issue draft
⟳ Initializing workflow...
⟳ Loading prompts...
⟳ Composing request...
⟳ Executing AI agent...
✓ Issue draft created: .nia/work/job_1703012345/issue/draft.md

Performance

Workflow commands execute in variable time depending on:

• AI model response time
• Prompt complexity
• Amount of context provided

Typical execution times:

• Simple operations (draft, ask): 5-15 seconds
• Complex operations (plan, review): 15-60 seconds
• Multi-stage operations (build –fix): 30-120 seconds

Best Practices

1. Set context early: Export NIA_ISSUE_ID and NIA_PR_ID in your shell profile or CI config
2. Use modifiers intentionally: --edit for iterative work, --fix for automated corrections
3. Provide input files: Give context via modifier input files for better results
4. Check help first: Run nia <target> <operation> --help to see available options
5. Validate custom workflows: Always run nia config validate after editing .nia/config/commands.toml

Troubleshooting

Command Not Found

If a workflow command isn’t recognized:

1. Check spelling: nia issue draft not nia issues draft
2. Validate config: nia config validate
3. Check lock file: .nia/.config_lock should exist
4. Regenerate registry: Delete .nia/.config_lock and run any nia command

Workflow Execution Fails

If execution fails:

1. Check context: Ensure NIA_ISSUE_ID is set (if required)
2. Verify prompts exist: Built-in prompts are embedded, custom prompts need .nia/prompts/
3. Check logs: Look in .nia/work/job_<job_id>/traces/ for detailed output

See Troubleshooting for more help.

Modifiers

Modifiers are optional flags that customize workflow operation behavior. They change how an operation executes without changing what it does.

Concept

A modifier transforms an operation by:

1. Overriding the task prompt: Uses a different task prompt variant
2. Loading user input files: Reads job-specific context from .nia/work/<job_id>/<target>/<modifier>.md