# Installation

Kanject ships as a .NET global tool — but you don't need any prior .NET setup to install it. Start at the top: install the SDK if this machine has never run .NET, install the CLI, then run `kanject doctor` to confirm everything is wired up. If something fails, [Common installation issues](https://www.kanject.com/docs/installation/#common-installation-issues) is ranked by how often each failure actually happens.

**You'll learn**

- Install the .NET SDK itself if you're coming from Node, Python, Go, or any non-.NET stack
- Verify the common .NET foundation, then install only the tools your shipping path needs
- Install the `kanject` CLI as a .NET global tool from public NuGet
- Fix the most common setup failure — `kanject` not found on `PATH` — on macOS, Linux, and Windows
- Confirm the setup with `kanject doctor`, and know how to upgrade or uninstall

## Install the .NET SDK first

kanject rides on the .NET SDK — but you may already have it. One command tells you:

```bash
dotnet --version
```

**What did `dotnet --version` print?**

_10.0 or higher — the SDK is already here:_

You're set — skip straight to [Verify the toolchain](https://www.kanject.com/docs/installation/#verify-the-toolchain). kanject installs on top of the SDK you already have; there's nothing else .NET-specific to do.

_command not found — or a version below 10.0:_

Install the SDK — pick your OS below. Whether you're coming from Node, Python, Go, or anywhere else, this is the only .NET-specific setup you'll do:

**Windows**

```powershell
winget install Microsoft.DotNet.SDK.10

dotnet --version       # 10.0 or higher works
```

**macOS**

```bash
brew install --cask dotnet-sdk

dotnet --version       # 10.0 or higher works
```

**Linux**

```bash
# official install script — installs to ~/.dotnet
curl -fsSL https://dot.net/v1/dotnet-install.sh | bash -s -- --channel 10.0
echo 'export PATH="$HOME/.dotnet:$HOME/.dotnet/tools:$PATH"' >> ~/.bashrc
source ~/.bashrc

dotnet --version       # 10.0 or higher works
```

Or skip the terminal entirely: download the installer from the official .NET website below and run it — pick the **SDK**, not the *Runtime*.

**Download from the .NET website**

- [Download .NET (all platforms and versions)](https://dotnet.microsoft.com/download) — Microsoft — choose the SDK installer for your OS

Either way, open a **new** terminal afterwards and re-run `dotnet --version` — 10.0 or higher means you're ready to continue.

## Verify the toolchain

The .NET 10 SDK is the common requirement. The remaining checks are path-specific: AWS CLI + Lambda tools for service deployment, git for cross-repository dependencies, and AWS CLI when desktop downloads use S3 destinations.

```bash
dotnet --version       # 10.0 or higher
aws --version          # aws-cli/2.x
git --version          # git version 2.x
dotnet lambda --version
```

A missing path-specific tool does not block an unrelated package workflow. Install it before entering the command family that uses it; `kanject doctor` and `doctor --features` report requirements in the context of the repository and feature being checked.

## Install the AWS Lambda tooling

Required by `kanject aws deploy` (Lambda packaging) and `kanject test` (local Lambda TestTool):

```bash
dotnet tool install -g Amazon.Lambda.Tools
dotnet tool update  -g Amazon.Lambda.Tools
```

## Install kanject

The CLI ships on public NuGet — no feed credentials, no `--add-source`:

```bash
dotnet tool install -g Kanject.Cli
```

> **The #1 setup failure happens right after this step:** If the very next `kanject --version` says *command not found* (macOS / Linux) or *is not recognized* (Windows), the install almost certainly **worked** — the .NET global-tools folder just isn't on your `PATH`, and the shell you installed from won't pick it up on its own. This is by far the most common installation failure we see. The fix is two commands: [Common installation issues](https://www.kanject.com/docs/installation/#common-installation-issues).

## First-run check

```bash
kanject --version
kanject doctor
```

Without `--env`, `doctor` only checks the foundations: the .NET SDK, the global-tools PATH, and the manifest if you're inside a kanject project. A clean run looks like:

```bash
✓ dotnet 10.0.x
✓ global tools on PATH (~/.dotnet/tools)
✓ kanject-cli/manifest.json (schema v1)

ok: 3   warn: 0   error: 0
```

If you're not inside a kanject project yet, the manifest check is skipped — that's expected. The next step is *Quick Start*.

## Common installation issues

Ranked by how often they hit — start at the top. Each one ends with `kanject --version` resolving.

**1 · `kanject` is not found — any OS.** This is the failure behind nearly every installation report. What it looks like:

```text
# macOS / Linux (zsh)
zsh: command not found: kanject

# Windows (PowerShell)
kanject : The term 'kanject' is not recognized as the name of a cmdlet,
function, script file, or operable program.
```

The cause: `dotnet tool install` puts the binary in `~/.dotnet/tools` (`%USERPROFILE%\.dotnet\tools` on Windows) but does **not** put that folder on your `PATH` — it only *prints* the line you'd need. The tool is installed; your shell just can't see it. Confirm that first:

```bash
dotnet tool list --global              # lists kanject.cli if the install worked
ls ~/.dotnet/tools                     # macOS / Linux
dir $env:USERPROFILE\.dotnet\tools     # Windows
```

Add the folder to `PATH` — pick your OS:

**Windows**

```powershell
# 1 — fix the window you're in right now (session only)
$env:Path += ";$env:USERPROFILE\.dotnet\tools"
kanject --version

# 2 — persist for every future window (writes the User PATH only)
[Environment]::SetEnvironmentVariable(
  "Path",
  [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:USERPROFILE\.dotnet\tools",
  "User")
```

Two commands because registry `PATH` changes never reach already-open terminals — the first fixes the window you're in, the second persists for every window after it.

**macOS**

```bash
echo 'export PATH="$HOME/.dotnet/tools:$PATH"' >> ~/.zprofile
source ~/.zprofile
```

Or just open a new terminal — the profile line applies from then on.

**Linux**

```bash
echo 'export PATH="$HOME/.dotnet/tools:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

Assumes bash; on zsh, use `~/.zprofile` as shown in the macOS tab.

> **Typing it by hand? [Environment]:: takes no space:** PowerShell parses `[Environment] ::SetEnvironmentVariable(…)` — note the space — as two tokens and fails with `Unexpected token '::SetEnvironmentVariable'`. The type name and `::` must be joined: `[Environment]::…`. And persist by appending to the **User** value as shown above, not to `$env:Path` — `$env:Path` is the combined Machine + User PATH, and writing it back into the User key duplicates every entry on it.

**2 · You just installed it and the *same* window still can't find it.** Even with `PATH` persisted correctly, the terminal you ran the install in was launched before the change. Run the session-fix line above (Windows) or `source` your profile (macOS / Linux) — or simply open a new terminal.

**3 · `dotnet` itself is not found.** The machine doesn't have the .NET SDK — go back to [Install the .NET SDK first](https://www.kanject.com/docs/installation/#install-the-net-sdk-first), then re-run the install.

Once `kanject` resolves, `kanject doctor` takes over the diagnosis: it raises **KANCLI018** whenever the global-tools directory isn't on `PATH`. It can only tell you that once the command itself runs — which is why this page front-loads the `PATH` fix.

## Upgrade

Once kanject is on your `PATH`, the ergonomic upgrade path is its own command — it checks both the CLI and the template pack and applies them together:

```bash
kanject update           # interactive; checks CLI + templates
kanject update --yes     # non-interactive (CI)
```

If you're on a build that predates `kanject update`, fall back to:

```bash
dotnet tool update -g Kanject.Cli
```

## Uninstall

```bash
dotnet tool uninstall -g Kanject.Cli
```

**Recap**

- No .NET on the machine? Install the SDK first — `winget` on Windows, `brew` on macOS, the dot.net install script on Linux — then `kanject` installs as a .NET global tool from public NuGet.
- The #1 setup failure is `PATH`, not the install: add `~/.dotnet/tools` (macOS / Linux) or `%USERPROFILE%\.dotnet\tools` (Windows), fix the current window too, then re-run `kanject --version`. `kanject doctor` flags it as **KANCLI018**.
- On Windows, `[Environment]::` must have no space before the `::`, and persist by appending to the *User* `PATH` value — not `$env:Path`.
- `kanject update` upgrades the CLI and template pack together; the fallback is `dotnet tool update -g Kanject.Cli`.
- A clean `kanject doctor` (0 warn, 0 error) means you're ready for *Quick Start*.

---
_Source: https://www.kanject.com/docs/installation/ · Kanject Docs_