# CLI Troubleshooting

Most CLI failures are designed to be diagnosable from `kanject doctor`, command exit codes, and `KANCLI###` diagnostic codes.

## kanject: command not found

The single most common failure — and the one `kanject doctor` can't catch, because if the command itself won't resolve you can't run doctor to be told why. 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 is almost always PATH: the .NET global-tools directory isn't on it. It shows up most often right after `dotnet tool install`/`update`, which *prints* the `export PATH=…` lines but doesn't apply them — so running `kanject` in that same shell, before adding them and reloading, fails.

The fix — pick your OS:

**Windows**

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

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

kanject --version    # now resolves
```

The session fix comes first because already-open terminals never pick up persisted `PATH` changes.

**macOS**

```bash
# .NET installs the shim under ~/.dotnet/tools — put that dir on PATH:
echo 'export PATH="$HOME/.dotnet/tools:$PATH"' >> ~/.zprofile
source ~/.zprofile   # or just open a new terminal

kanject --version    # now resolves
```

**Linux**

```bash
# .NET installs the shim under ~/.dotnet/tools — put that dir on PATH:
echo 'export PATH="$HOME/.dotnet/tools:$PATH"' >> ~/.bashrc
source ~/.bashrc     # or just open a new terminal

kanject --version    # now resolves
```

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'`. Type the name and `::` joined: `[Environment]::…`. And append to the **User** value as shown, not `$env:Path` — that's the combined Machine + User PATH, and writing it back duplicates every entry.

> **Confirm it's only PATH:** The tool installs regardless of PATH — `ls ~/.dotnet/tools` (macOS / Linux) or `dir $env:USERPROFILE\.dotnet\tools` (Windows) lists the binary, and `dotnet tool list --global` shows `kanject.cli`. If the binary is there, it is purely a PATH problem; [Installation → Common issues](https://www.kanject.com/docs/installation/#common-installation-issues) has the full ranked list, including the no-.NET-SDK case.

## Start with doctor

```bash
kanject doctor
kanject doctor --env prod
```

Without `--env`, doctor checks the foundations — **entirely offline**. With `--env`, it also checks stage-specific assumptions such as manifest/stage shape and provider readiness. Only errors flip the exit code to 1; warnings keep it 0.

## Gate CI with doctor --json

`--json` suppresses all human decoration and emits a stable `schemaVersion: 1` envelope — `exitCode`, a `summary` of counts, and a `results[]` array of `{ severity, code, message, hint }` — so a pipeline step can gate on it before spending a build:

```bash
# Fail the job on any error-severity finding, before the build spends a cent
kanject doctor --json --env stage \
  | jq -e '.results | map(select(.severity == "error")) | length == 0'
```

## Common diagnostics

Codes are stable — they never renumber — so they're the thing to search for or paste into a ticket. The three you'll meet first; the [diagnostic-code reference](https://www.kanject.com/docs/cli-diagnostics/) indexes every code the CLI can emit.

- **KANCLI018** — The .NET global tools directory is not on PATH.
- **KANCLI003** — The lockfile drifted. Run `kanject sync` and commit the result if intentional.
- **KANCLI044** — `--pull-env` resolved SecureString values into the local process and is warning you explicitly.

## Inspect env safely

```bash
kanject env --env dev
kanject env --env dev --show-values
```

`kanject env` masks resolved values by default. Use `--show-values` only in a local debugging terminal, never in CI logs.

## Failure patterns

- Manifest/stage mismatch — every stage listed in the manifest needs a matching stage file.
- AWS profile/region issue — confirm the profile exists locally and in CI.
- Artifact bucket missing — create the bucket or let your team IaC provision it before deploy.
- Cross-repo dependency issue — check git access, pinned refs, and `manifest.lock.json` drift.

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