Utility Commands

Utility commands are fast, deterministic operations that don’t require AI backend. They’re always available and execute in < 100ms.

Config Location	Export Location
`.nia/config/toolchain.toml` (repository)	`.agents/skills/` (project)
`~/.config/nia/toolchain.toml` (user)	`~/.agents/skills/` (global)

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"

init

Initialize nia configuration for a repository.

nia config init                    # Manual initialization (prompts for all values)
nia config init --interactive      # AI-assisted with per-field approval
nia config init -i                 # Short form of --interactive

Creates .nia/config/project.toml with project metadata used by AI agents for context and decision-making.

Manual Initialization (default)

Prompts for each configuration value:

$ nia config init
Enter project name: my-service
Enter description: User authentication microservice
Select language: Rust
Select framework: axum
Select testing framework: cargo test
Select package manager: cargo

✓ Configuration created at .nia/config/project.toml

Best for:

Full control over all metadata
Projects with non-standard structure
Critical repositories requiring precise configuration

Interactive Mode (`--interactive`)

The interactive mode provides a guided setup experience that configures your complete nia environment in four phases:

Phase Flow:

Agent Configuration (Selection-based) - AI coding agent and model profile
Project Configuration (AI-assisted) - Repository metadata, analyzed with the agent chosen in phase 1
Toolchain Configuration (Selection-based) - Development tools
Summary & Confirmation - Review and write all configuration files

By default, Phase 3 skips the per-tool access-method choice and uses skill for every selected tool. Add --advanced to be prompted for each tool’s access method (skill, cli, mcp, api) instead — see Access Methods.

$ nia config init --interactive

════════════════════════════════════════════════════════
Phase 1: Agent Configuration
Configure your AI coding agent
════════════════════════════════════════════════════════

Agent
  Select the AI coding agent you want to use

  1. claude_code - Claude Code CLI (uses Claude models)
  2. github_copilot - GitHub Copilot CLI (uses GitHub and BYOK models)
  3. opencode - OpenCode CLI (uses BYOK models)

Select (1-3): 2
✓ Selected: github_copilot

Model Profile
  Choose quality vs. cost trade-off

  1. lite - Minimize costs with fast/cheap models
  2. balanced - Good performance at reasonable cost
  3. stable - Predictable behaviour with previous-generation models (default)
  4. heavy - Maximum quality for critical operations

Select (1-4) (default: 3):
✓ Selected: stable

════════════════════════════════════════════════════════
Phase 2: Project Configuration
AI-assisted project metadata setup
════════════════════════════════════════════════════════

ℹ Analyzing repository...

name: 'my-project' (detected from directory name)
Accept? [Press Enter] or enter custom value:
✓ Accepted: my-project

description: 'A Rust web service using Axum' (inferred from README.md)
Accept? [Press Enter] or enter custom value: My custom description here
✓ Accepted: My custom description here

language: 'Rust' (detected from Cargo.toml)
Accept? [Press Enter] or enter custom value:
✓ Accepted: Rust

framework: 'axum' (detected from Cargo.toml dependencies)
Accept? [Press Enter] or enter custom value:
✓ Accepted: axum

testing_framework: 'cargo test' (detected from Cargo.toml)
Accept? [Press Enter] or enter custom value:
✓ Accepted: cargo test

package_manager: 'cargo' (detected from Cargo.toml)
Accept? [Press Enter] or enter custom value:
✓ Accepted: cargo

════════════════════════════════════════════════════════
Phase 3: Toolchain Configuration
Configure your development tools
════════════════════════════════════════════════════════

Issue Tracker
  Configure where you track work items and bugs

  1. github_issues - GitHub Issues
  2. jira - Jira
  3. azure_devops - Azure DevOps Boards
  4. shortcut - Shortcut
  5. local - Local issue tracking
  6. skip - Skip this configuration

Select (1-6): 1
✓ Selected: github_issues

ℹ Access method: skill (change it in toolchain.toml, or rerun with --advanced)

Code Platform
  Configure your source code hosting platform

  1. github - GitHub
  2. github_enterprise - GitHub Enterprise
  3. bitbucket - Bitbucket
  4. azure_devops - Azure DevOps
  5. local - Local development

Select (1-5): 1
✓ Selected: github

ℹ Access method: skill (change it in toolchain.toml, or rerun with --advanced)

Ticket Tracker
  Configure customer support ticket system (optional)

  1. github_issues - GitHub Issues
  2. jira - Jira
  3. azure_devops - Azure DevOps Boards
  4. shortcut - Shortcut
  5. local - Local ticket tracking
  6. skip - Skip this configuration

Select (1-6): 6
✓ Skipped

Security Scanner
  Configure code security scanning tool (optional)

  1. polaris - Polaris SAST
  2. github_sast - GitHub Advanced Security
  3. snyk - Snyk
  4. skip - Skip this configuration

Select (1-4): 4
✓ Skipped

════════════════════════════════════════════════════════
Phase 4: Summary
Review your configuration
════════════════════════════════════════════════════════

Configuration Summary:

[Agent Configuration]
  agent: github_copilot
  model_profile: stable

[Project Configuration]
  name: my-project
  description: My custom description here
  language: Rust
  framework: axum
  testing_framework: cargo test
  package_manager: cargo

[Toolchain Configuration]
  issue_tracker: github_issues (via skill)
  code_platform: github (via skill)

Files to be created or replaced:
  ✓ .nia/config/project.toml
  ✓ .nia/config/toolchain.toml
  ✓ .nia/config/agents.toml
  ✓ .agents/skills/ (skill files for tools using the "skill" access method)

Create these configuration files? [Y/n]:
✓ Configuration files created successfully
✓ Generated configuration validated

Configuration complete! Run 'nia config validate' to verify.

Phase Details:

Phase 1: Agent Configuration (Selection-based)

Agent: Choose your AI coding agent (Claude Code, GitHub Copilot, OpenCode)
Model profile: Select quality tier (lite, balanced, stable, heavy)
Defaults to “stable” profile if not specified
The agent selected here is used for the phase 2 repository analysis; choosing “skip” means the analysis is not run and metadata is entered manually

Phase 2: Project Configuration (AI-assisted)

Analyzes repository structure and manifests
Suggests project metadata based on code analysis
Supports monorepo detection and configuration
Each field can be accepted, modified, or overridden
Uses the agent selected in phase 1; if that agent is unavailable you can retry, enter the metadata manually, or quit

Phase 3: Toolchain Configuration (Selection-based)

Issue tracker: Choose from GitHub Issues, Jira, Azure DevOps, Shortcut, or local
Code platform: Select GitHub, GitHub Enterprise, Bitbucket, Azure DevOps, or local
Ticket tracker: Optional customer support system
Security scanner: Optional security analysis tool (Polaris, GitHub SAST, Snyk)
Skip option available for optional components
Access method: Each non-local tool selected defaults to skill without prompting; run with --advanced to be prompted per tool instead (see Access Methods below)

Phase 4: Summary & Confirmation

Review all selections before writing files
Shows complete configuration summary, including each tool’s access method and any files being preserved rather than overwritten
Creates all files atomically (all or none)
No partial configuration on cancellation
Validates the generated toolchain.toml/agents.toml immediately after writing and reports “Generated configuration validated” (or a hint to run nia config validate if a problem is detected)

Access Methods (Interactive Mode)

Choosing between skill, cli, mcp, and api is an expert decision, so whether Phase 3 prompts for it depends on --advanced:

Method	Description
`skill`	Agent skill (recommended, default). Exports a skill file to `.agents/skills/` that teaches the agent to use the tool’s CLI/API directly.
`cli`	The agent invokes the tool’s command-line interface directly.
`mcp`	The agent connects to the tool via an MCP server.
`api`	The agent calls the tool’s API directly.

Default path (no --advanced): every non-local tool is set to skill (or, on a re-entered field, whatever method was already chosen) without prompting. nia prints where to change it later:

✓ Selected: github_issues

ℹ Access method: skill (change it in toolchain.toml, or rerun with --advanced)

--advanced path: nia prompts for the access method for every non-local tool that supports more than one method:

$ nia config init --interactive --advanced

✓ Selected: github_issues

Access method for github_issues
  How should the agent reach this tool?

  1. skill - Recommended: agent uses a generated skill file (default)
  2. cli - Agent shells out to the tool's CLI
  3. mcp - Agent talks to an MCP server
  4. api - Agent calls the tool's REST API directly

Select (1-4) (default: 1):
✓ Selected: skill

Only methods supported by the selected tool are offered; tools with a single supported method (or local tools) never prompt, in either path. When skill is chosen for any tool, nia exports the corresponding skill file(s) to .agents/skills/ as part of writing the configuration, and this is disclosed in the Phase 4 summary and “Created:” list.

Repository/Instance Identifier (Interactive Mode)

After selecting an access method for a non-local issue tracker, code platform, or ticket tracker, nia prompts for an optional repository/instance identifier:

ℹ Repository/instance identifier for github_issues (optional)
  e.g. owner/repo, e.g. octocat/hello-world
  Detected from Git remote: octocat/hello-world
Repository (press Enter to use auto-detected value, or type to override):

If nia can’t detect a repository from the current directory’s Git remote (origin, falling back to upstream), the prompt states that clearly instead of showing a detected value:

ℹ Repository/instance identifier for github_issues (optional)
  e.g. owner/repo, e.g. octocat/hello-world
  No Git remote detected.
Repository (press Enter to skip):

Press Enter to skip — the tool falls back to auto-detecting the repository from the Git remote at runtime, same as before this prompt existed (showing the detected value up front is a display-only aid so you can confirm it looks right, or catch a wrong remote such as a fork, before accepting it).
Type an identifier and it’s validated the same way as toolchain.toml’s repository field elsewhere (accepts a bare owner/repo slug like octocat/hello-world, or a full Git URL such as https://github.com/owner/repo.git or git@github.com:owner/repo.git). Invalid input is rejected with guidance and re-prompted (up to 3 attempts before falling back to skipping).
When set, the value is written as repository = "..." in the corresponding toolchain.toml section and shown in the Phase 3 and Phase 4 summaries.
Security scanners are excluded from this prompt since they’re not typically scoped to a single repository.
Known limitation: JIRA’s host-only base URL example (e.g. https://yourcompany.atlassian.net) has no path segment, so it doesn’t pass the reused Git URL validator. Either append a path segment (e.g. a project key) or press Enter to skip and let JIRA fall back to auto-detection.

Model Overrides (Interactive Mode)

After selecting an agent and model profile (and only when the profile itself wasn’t pre-specified via --models), nia offers to override the profile’s default model and every operation-specific model it defines, one at a time:

Optionally override the default models chosen for this profile.
Press Enter to keep a default, or type a model name to override it.
ℹ Default model [gpt-5.4]:
ℹ issue.plan [gpt-5.4]:

Press Enter at any prompt to keep the profile’s default for that entry.
Type a model name to override it. If the model isn’t recognized for the selected agent, nia shows a warning and asks whether to use it anyway.
The fully resolved set of models (defaults plus any overrides) replaces the profile’s built-in values in the generated agents.toml.

Pre-specified Flags:

You can pre-populate selections using flags (skips those prompts):

nia config init --interactive --issues github_issues --code github --agent github_copilot

Best for:

Complete nia environment setup in one session
First-time nia users who want guided configuration
Projects that need both project metadata and toolchain setup
When you want to review AI suggestions before committing

Protection:

Prompts when config already exists (Option C)
Offers to edit existing config or cancel
Validates all inputs before writing configuration
When toolchain.toml or agents.toml already exists, prompts separately for each (“Replace it with your new selections? [y/N]”) before regenerating it; declining preserves the existing file untouched and skips the corresponding prompts entirely

Editing Existing Configuration

When you run --interactive on a repository that already has project.toml, you’ll be prompted:

⚠ Configuration already exists at .nia/config/project.toml

Would you like to:
  [E] Edit existing configuration interactively
  [C] Cancel

Choice [E/C]:

Edit mode (choose E):

Loads current configuration values
Analyzes repository for AI suggestions
For each field, you choose:
- [K]eep - Keep current value (default)
- [A]ccept - Accept AI suggestion
- [C]ustom - Enter your own value
Shows before → after summary for modified fields

Example edit session:

name
  Current:  my-service
  AI suggests: my-microservice

  Choice [K/A/C] (default: Keep): A
  ✓ Accepted AI: my-microservice

description
  Current:  Old description
  AI suggests: Modern REST API service

  Choice [K/A/C] (default: Keep): C
  Enter custom value: My custom description
  ✓ Custom: My custom description

Cancel (choose C): Exits without making changes.

Comparison: When to Use Each Mode

Mode	Command	Use Case	Configuration Created	Setup Time
Interactive	`--interactive`	Complete guided setup with AI assistance	project.toml + toolchain.toml + agents.toml	2-4 min
Manual	(default)	Full control, non-standard projects	project.toml only	2-5 min

Note: To configure only toolchain or agent without interactive mode, use:

nia config init --issues github_issues --code github        # Toolchain only
nia config init --agent github_copilot --models stable      # Agent only

Troubleshooting Interactive Mode

Common issues and solutions:

AI analysis takes too long (>30 seconds)

Check agent connectivity: nia status
Verify your AI agent is configured: nia config show-context
Fall back to manual mode: nia config init (without --interactive)

# Check if agent is responding
nia status

# If agent is slow, use manual mode instead
nia config init

AI suggests incorrect framework/language

The AI makes suggestions based on:

Manifest files (Cargo.toml, package.json, go.mod)
Directory structure
README content

If suggestions are wrong:

Simply type the correct value when prompted
Framework detection works best for well-known frameworks
Consider updating your manifest files for better detection

“Interactive mode requires user input” error

Interactive mode reads field values from stdin and requires actual user input. A closed or empty stdin (EOF) is rejected with an explicit error rather than silently accepting suggested values, so it cannot be scripted by piping empty input.

# These will fail (no user to provide input):
echo "" | nia config init --interactive       # Error: EOF detected
cat /dev/null | nia config init --interactive # Error: EOF detected

# Solutions for non-interactive environments:
nia config init                 # Manual mode - prompts for each field
nia config init --app           # App mode - minimal prompts
nia config init --name "myapp"  # Explicit values via flags

Why this restriction?

Interactive mode is designed for guided human interaction. Auto-accepting AI suggestions without explicit user approval would violate the principle of informed consent - users should knowingly approve each configuration value.

“Configuration already exists”

When project.toml already exists:

⚠ Configuration already exists at .nia/config/project.toml

Would you like to:
  [E] Edit existing configuration interactively
  [C] Cancel

Choose E to modify existing values while preserving unchanged fields.

Validation errors on custom input

Custom values must meet these requirements:

name: Non-empty, ≤100 characters, no control characters
description: Non-empty, ≤250 characters, no control characters
All fields: No TOML-unsafe characters

# Invalid inputs:
name: "my-project\n"      # Control character (newline)
description: ""            # Empty not allowed
name: "x" * 101           # Exceeds 100 char limit

Privacy & Data

What data is sent to the AI agent?

Interactive mode sends the following to your configured AI agent:

Data Type	Content	Purpose
File listing	Top 100 file/directory names	Detect language and structure
Manifest contents	Cargo.toml, package.json, go.mod (first 3 found)	Extract name, dependencies
README excerpt	First 50 lines of README.md	Generate description

What is NOT sent:

Source code contents (only manifest files)
Environment variables
Git history or commits
Credentials or secrets
Files in .gitignore

Data flow:

Repository → nia CLI → Your AI Agent → Suggestions → Local config file
             (local)    (configured)    (returned)    (.nia/config/)

All data is processed by the AI agent you have configured (GitHub Copilot, Gemini, Claude, or OpenCode). Review your agent’s privacy policy for data handling details.

Disabling AI analysis:

If you prefer not to send repository structure to AI:

# Use manual mode instead
nia config init

# Or use app mode with explicit values
nia config init --app

See Also:

Project Configuration - Configuration file reference
Hierarchical Loading - Multi-source configuration

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:

Environment variables (NIA_USER_NAME, NIA_USER_EMAIL)
Context.toml (this setting)
Git config (user.name, user.email)
System user (OS username)
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.

update

Update nia to the latest version. See the Update Command for full details, including --check, --version, and --force, package-manager detection, and troubleshooting.

nia update

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:

Detects shell profile file (~/.bashrc, ~/.zshrc, etc.)
Creates timestamped backup of profile
Adds completion source line
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:

Command	Typical Duration
`config validate`	< 50ms
`guide open`	< 10ms
`shell install`	< 100ms
`shell completion`	< 20ms

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.

Nia CLI User Guide

Utility Commands

config

validate

validate –file

export

export –target

export –workflows

export –force

export –skills

init

Manual Initialization (default)

Interactive Mode (`--interactive`)

Access Methods (Interactive Mode)

Repository/Instance Identifier (Interactive Mode)

Model Overrides (Interactive Mode)

Editing Existing Configuration

Comparison: When to Use Each Mode

Troubleshooting Interactive Mode

Privacy & Data

user

update

guide

open

shell

install

install –manual

uninstall

completion

Performance

Protected Namespaces

Keyboard shortcuts

Nia CLI User Guide