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.