Nim-Cli

# Nim-Cli `Nim-Cli` is a terminal agent developed using `C# / .NET 10`, with providers currently focused on `NVIDIA Inference Microservices (NIM)`, and provides: - `nim-cli`: CLI entry point - `nim-tui`: TUI entry point - shared core: CLI / TUI shared `AgentOrchestrator`, `ContextBuilder`, `ToolRegistry`, `ToolPolicyService`, `CodingPipeline`, `SessionState` / `SessionManager` Its goal is not just simple chat, but to handle project analysis, build / run, browser screenshot, DB query, git / ftp, MCP, and coding workflow on Windows terminal agents. The overall design of `Nim-Cli` integrates the model inference capabilities of `NVIDIA Inference Microservices (NIM)` and common engineering toolchains on Windows into a single CLI / TUI shared core, allowing the same session to continuously complete analysis, execute tools, verify results, and organize summaries / audits. Unlike tools that only provide a single-path chat interface, `Nim-Cli` emphasizes the continuity of engineering workflows: you can perform repo analysis, build / test, browser screenshot verification, and organize summaries or further git / MCP / TUI workflows within the same session. This is why it provides both `nim-cli` and `nim-tui`, but maintains the same orchestrator, policy, context, session, and tool registry. In coding workflows, the project also adopts practices such as `repo map`, `plan before edit`, `build/test verify`, and `commit summary`, which are more inclined towards `aider` style; while in terms of tools, it supplements common terminal agent needs such as browser, DB, FTP, Git, and MCP. ## Current Features - chat / run / doctor / plan - build / run-project / analyze / repo map - browser open / navigate / screenshot - DB query (read-only boundary) - git status / diff / commit / push - ftp upload - session / restore / rewind - MCP status / inspect / ping / registry - CLI / TUI shared summary / audit / policy flow ## System Requirements Currently, README focuses on Windows. Necessary conditions: - Windows 10 or Windows 11 - `PowerShell 7` (`pwsh`) - `.NET 10 SDK` - `Git` - Network connectivity to `NVIDIA Inference Microservices (NIM)` API Depending on functionality, you may need: - Playwright Chromium runtime: required for browser / screenshot functionality - `GitHub CLI` (`gh`): if you want to use PR or part of GitHub workflow ## Quick Installation The repository provides an installation script: - `scripts/install-prerequisites.ps1` This is an environment initialization script for new machines or after cloning the repository. Run in the repository root directory: ```powershell pwsh -ExecutionPolicy Bypass -File ".\scripts\install-prerequisites.ps1" ``` If you also want to install `gh`: ```powershell pwsh -ExecutionPolicy Bypass -File ".\scripts\install-prerequisites.ps1" -InstallGitHubCli ``` If you don't want to install Playwright browser runtime for now: ```powershell pwsh -ExecutionPolicy Bypass -File ".\scripts\install-prerequisites.ps1" -SkipPlaywright ``` This script will: 1. Check and install `.NET 10 SDK` 2. Check and install `PowerShell 7` 3. Check and install `Git` 4. Optionally install `GitHub CLI` 5. Create local `appsettings.secret.json` 6. `dotnet restore` 7. Install Playwright Chromium runtime 8. Run `dotnet build` once ## Manual Installation Process If you don't want to use the script, you can follow the steps below for manual installation. ### 1. Install .NET 10 SDK Confirm if installed: ```powershell dotnet --version ``` If not, use `winget`: ```powershell winget install --id Microsoft.DotNet.SDK.10 --exact --accept-package-agreements --accept-source-agreements --disable-interactivity ``` ### 2. Install PowerShell 7 Confirm if installed: ```powershell pwsh -NoLogo -NoProfile -Command '$PSVersionTable.PSVersion.ToString()' ``` If not: ```powershell winget install --id Microsoft.PowerShell --exact --accept-package-agreements --accept-source-agreements --disable-interactivity ``` ### 3. Install Git Confirm if installed: ```powershell git --version ``` If not: ```powershell winget install --id Git.Git --exact --accept-package-agreements --accept-source-agreements --disable-interactivity ``` ### 4. Optional: Install GitHub CLI If you use GitHub PR / issue / checks workflow: ```powershell winget install --id GitHub.cli --exact --accept-package-agreements --accept-source-agreements --disable-interactivity ``` Confirm: ```powershell gh --version ``` ### 5. Restore NuGet Packages ```powershell dotnet restore ".\Nim-Cli.slnx" ``` ### 6. Install Playwright Chromium Runtime If you want to use browser / screenshot functionality, build CLI once: ```powershell dotnet build ".\src\Nim-Cli\Nim-Cli.csproj" -c Debug ``` Then install Playwright Chromium: ```powershell pwsh -NoLogo -NoProfile -ExecutionPolicy Bypass -File ".\src\Nim-Cli\bin\Debug\net10.0\playwright.ps1" install chromium ``` ### 7. Final Confirmation of Solution Build ```powershell dotnet build ".\Nim-Cli.slnx" ``` ## Configure NVIDIA Inference Microservices (NIM) If you haven't registered or applied for NIM, you can refer to this tutorial: - https://donmatw.blogspot.com/2026/03/nvidia-build-opencode-free-ai-coding-guide.html The article can serve as a reference for registering `NVIDIA Inference Microservices (NIM)`, obtaining API keys, and understanding basic usage. ### 1. Create Local Secret Configuration File The repository already has an example file: - `src/Nim-Cli/appsettings.secret.example.json` - `src/NimTui.App/appsettings.secret.example.json` You can directly copy it for the first time: ```powershell Copy-Item ".\src\Nim-Cli\appsettings.secret.example.json" ".\src\Nim-Cli\appsettings.secret.json" Copy-Item ".\src\NimTui.App\appsettings.secret.example.json" ".\src\NimTui.App\appsettings.secret.json" ``` Then change `ApiKey` to your `NVIDIA Inference Microservices (NIM)` API key. ### 2. Configuration File Location and Precedence The current implementation is roughly as follows: - user-level app home: `%LocalAppData%\NimCli\` - If `NIMCLI_HOME` is set, use that directory - user-level config as base - workspace config as override The files read include: - `appsettings.json` - `appsettings.secret.json` - `appsettings.Local.json` ### 3. Write API Key Using CLI You can also use the command: ```powershell dotnet run --project ".\src\Nim-Cli\Nim-Cli.csproj" -- auth login ``` or: ```powershell dotnet run --project ".\src\Nim-Cli\Nim-Cli.csproj" -- auth login --api-key "<your-key>" ``` ### 4. Verify Provider Status ```powershell dotnet run --project ".\src\Nim-Cli\Nim-Cli.csproj" -- auth status dotnet run --project ".\src\Nim-Cli\Nim-Cli.csproj" -- models list dotnet run --project ".\src\Nim-Cli\Nim-Cli.csproj" -- doctor ``` ## Execution ### CLI ```powershell dotnet run --project ".\src\Nim-Cli\Nim-Cli.csproj" -- ``` or specify the command directly: ```powershell dotnet run --project ".\src\Nim-Cli\Nim-Cli.csproj" -- doctor dotnet run --project ".\src\Nim-Cli\Nim-Cli.csproj" -- plan "summarize current architecture" dotnet run --project ".\src\Nim-Cli\Nim-Cli.csproj" -- run "analyze this repository" ``` ### TUI ```powershell dotnet run --project ".\src\NimTui.App\NimTui.App.csproj" ``` ## Shortest Verification Process After First Installation If you've just completed the installation and want to confirm if the environment is working, follow the sequence below. ### 1. Confirm SDK and Shell ```powershell dotnet --version pwsh -NoLogo -NoProfile -Command '$PSVersionTable.PSVersion.ToString()' git --version ``` ### 2. Confirm Solution Build ```powershell dotnet build ".\Nim-Cli.slnx" ``` ### 3. Confirm CLI Body Can Start ```powershell dotnet run --project ".\src\Nim-Cli\Nim-Cli.csproj" -- doctor ``` ### 4. If You've Filled in NIM Key, Confirm Provider Status ```powershell dotnet run --project ".\src\Nim-Cli\Nim-Cli.csproj" -- auth status dotnet run --project ".\src\Nim-Cli\Nim-Cli.csproj" -- models list ``` ### 5. Confirm Core Test Can Run ```powershell dotnet test ".\tests\NimCli.Core.Tests\NimCli.Core.Tests.csproj" ``` ### 6. If You Have Installed Playwright, Confirm Browser-Related Capabilities ```powershell pwsh -NoLogo -NoProfile -ExecutionPolicy Bypass -File ".\src\Nim-Cli\bin\Debug\net10.0\playwright.ps1" install chromium dotnet test ".\tests\NimCli.Integration.Tests\NimCli.Integration.Tests.csproj" ``` If the above steps all pass, it usually indicates: - SDK is normal - PowerShell 7 is normal - CLI host is normal - DI / build / test main path is normal - provider configuration is basically normal - Playwright browser runtime is ready ## Publishing Executable Files from Source Code If you don't want to use `dotnet run` every time, you can directly publish it as an executable file. ### Publish nim-cli ```powershell dotnet publish ".\src\Nim-Cli\Nim-Cli.csproj" -c Release -r win-x64 --self-contained false -o ".\publish\nim-cli" ``` The executable file will usually be in: ```text publish\nim-cli\Nim-Cli.exe ``` ### Publish nim-tui ```powershell dotnet publish ".\src\NimTui.App\NimTui.App.csproj" -c Release -r win-x64 --self-contained false -o ".\publish\nim-tui" ``` The executable file will usually be in: ```text publish\nim-tui\Nim-Tui.exe ``` ### If You Want Self-Contained This way, the target machine doesn't need to install .NET runtime additionally, but the output will be larger: ```powershell dotnet publish ".\src\Nim-Cli\Nim-Cli.csproj" -c Release -r win-x64 --self-contained true -o ".\publish\nim-cli-self" dotnet publish ".\src\NimTui.App\NimTui.App.csproj" -c Release -r win-x64 --self-contained true -o ".\publish\nim-tui-self" ``` ### Files Recommended to Be Brought Together After Publishing At least confirm that the following files are available in the output directory: - `appsettings.json` - `appsettings.secret.json` or corresponding user-level config - Playwright runtime (if you need browser / screenshot) ### Shortest Verification After Publishing ```powershell .\publish\nim-cli\Nim-Cli.exe doctor .\publish\nim-cli\Nim-Cli.exe auth status .\publish\nim-tui\Nim-Tui.exe ``` ## Common Commands ### Core Commands ```text nim-cli nim-cli chat nim-cli run "<prompt>" nim-cli doctor nim-cli plan "<task>" nim-cli session show nim-cli session resume nim-cli settings show nim-cli settings set <key> <value> nim-cli workspace nim-cli mcp status nim-tui ``` ### Tool-Oriented Commands ```text nim-cli build --project <path> nim-cli run-project --project <path> nim-cli screenshot --url http://localhost:5000 --out shot.png nim-cli db query --conn default --table User --where "id='123'" nim-cli git status nim-cli git diff nim-cli git push --dry-run nim-cli ftp upload --dry-run ``` ## Verification and Testing Common tests: ```powershell dotnet test ".\tests\NimCli.Core.Tests\NimCli.Core.Tests.csproj" dotnet test ".\tests\NimCli.Integration.Tests\NimCli.Integration.Tests.csproj" dotnet test ".\tests\NimTui.Tests\NimTui.Tests.csproj" ``` Complete build: ```powershell dotnet build ".\Nim-Cli.slnx" ``` If you've just installed external dependencies, the recommended sequence is: 1. `dotnet build ".\Nim-Cli.slnx"` 2. `dotnet test ".\tests\NimCli.Core.Tests\NimCli.Core.Tests.csproj"` 3. `dotnet test ".\tests\NimCli.Integration.Tests\NimCli.Integration.Tests.csproj"` 4. `dotnet test ".\tests\NimTui.Tests\NimTui.Tests.csproj"` ## Runtime Data Location Currently, runtime state is saved under the user-level app home in: ```text .nim-cli-runtime/ ``` Contents include: - sessions - checkpoints - state.json The default base directory is: - `%LocalAppData%\NimCli\` Alternatively, you can use: - `NIMCLI_HOME` to override. ## Frequently Asked Questions ### 1. `pwsh` Not Found Please install PowerShell 7 first: ```powershell winget install --id Microsoft.PowerShell --exact --accept-package-agreements --accept-source-agreements --disable-interactivity ``` ### 2. `dotnet` Not Found Please install `.NET 10 SDK` first: ```powershell winget install --id Microsoft.DotNet.SDK.10 --exact --accept-package-agreements --accept-source-agreements --disable-interactivity ``` ### 3. Browser / Screenshot Failure Usually, it's because the Playwright runtime hasn't been installed. Please: ```powershell dotnet build ".\src\Nim-Cli\Nim-Cli.csproj" -c Debug pwsh -NoLogo -NoProfile -ExecutionPolicy Bypass -File ".\src\Nim-Cli\bin\Debug\net10.0\playwright.ps1" install chromium ``` ### 4. `models list` or `auth status` Showing No API Key It means `appsettings.secret.json` hasn't been filled in, or the current workspace/user-level precedence hasn't hit the file you expected. Check: - `src/Nim-Cli/appsettings.secret.json` - `%LocalAppData%\NimCli\appsettings.secret.json` - `NIMCLI_HOME` ### 5. `git push` / `ftp upload` Not Executed Directly This is a design risk control. High-risk operations go through approval/dry-run/policy paths, not unconditional releases by default. ## Related Documents - Architecture Overview: `src/Nim-Cli/ai-guide/nim-cli-architecture.md` - BigPhase Overview: `src/Nim-Cli/ai-guide/BigPhase1-9-overview.md` - Architecture Supplement: `src/Nim-Cli/ai-guide/architecture-overview.md` - Testing Overview: `src/Nim-Cli/ai-guide/testing-overview.md` - Known Limitations: `src/Nim-Cli/ai-guide/known-limitations.md` - Smoke Reports: `src/Nim-Cli/ai-guide/smoke-test/` ## Note - `appsettings.secret.json` should not be submitted to git - `appsettings.secret.example.json` is the submitable template - If a real API key has appeared in conversations, screenshots, logs, or other externally visible locations, consider it exposed and rotate ## Disclaimer - This project is provided "as is" and does not guarantee suitability for any specific purpose or stable operation in all environments, external services, or workflows. - Users are responsible for external service accounts, `NVIDIA Inference Microservices (NIM)` API keys, related fees, permission settings, regulatory compliance, and data security. - Although this project has added approval, dry-run, or safety boundaries to high-risk paths like `git push`, `ftp upload`, shell, DB, users should still assess risks and confirm operation consequences before actual execution. - The project authors and contributors are not liable for any data loss, service interruption, cost increase, credential exposure, environmental damage, or direct/indirect losses resulting from the use of this project. - This project has no official endorsement, affiliation, or agency relationship with `NVIDIA`, `Google Gemini CLI`, `aider`, or other third-party services/trademarks, except for technical references and compatibility goals stated in the document.