# Local Development

Reproduce cloud-only behaviour on your machine. `kanject test` runs your service locally — picking the right runner from the project type — and `--pull-env` resolves a stage's real env into the process, so a bug that only appears with production-shaped config is debuggable with local breakpoints.

**You'll learn**

- Run a service locally — webapi or a Lambda — with `kanject test`
- Pull a stage's real `param:` / `secret:` env into the local process, safely
- Inspect plain values and stored parameter/secret bindings with `kanject env`
- Attach an IDE and keep launch profiles and VS Code in sync

## Run it: kanject test

`test` reads the manifest `runtimeMode` (or detects it from the csproj) and launches the matching runner:

- `webapi` — `dotnet run` (or `dotnet watch run` with `--watch`), on port 5000.
- `lambda-tasks` — the `Amazon.Lambda.TestTool` on port 5050; replay a payload with `--event`.
- `lambda-aspnetcore` — the TestTool by default; `--http` flips it to a plain web host.
- `library` — no runner; use `dotnet test` / `dotnet run` directly.

```bash
# Run the service locally — webapi runs with dotnet, a Lambda launches the TestTool
kanject test

# Hot-reload a webapi
kanject test --watch

# Send a Lambda an event payload (from the events/ folder)
kanject test --event events/order-created.json

# Run an aspnetcore-in-Lambda service as a plain web host instead of the TestTool
kanject test --http
```

## Real env, locally: --pull-env

`--pull-env` resolves the stage's `param:` and `secret:` references **live** from Parameter Store and Secrets Manager and injects them into the test process. The values stay in process memory — Kanject never writes them to disk. A summary panel prints the count by source (without the values) before launch.

```bash
# Run locally with a stage's real env resolved in — param: and secret:
# references pulled live from SSM / Secrets Manager, in memory only
kanject test --pull-env --env dev
```

> **Secret safety:** kanject warns (KANCLI044) when SecureString or Secrets Manager values resolve into the process. They are memory-only, but anything that can read your shell's environment — printenv, or an IDE attached to the process — can see them. Pull against a low-stakes stage like dev, not prod.

## Inspect env: kanject env

`kanject env [--env <stage>]` is local-only: it prints each key, source, and stored stage-config value without calling SSM or Secrets Manager. `secret:` and `param:` bindings are masked by default; `--show-values` reveals the binding string, not the remote secret. When stage is omitted on a terminal, the sole stage is selected or a picker appears; scripts must pass it explicitly.

```bash
# Omit --env on a terminal to use the sole stage or choose from a picker
kanject env

# Reveal the stored binding strings — this still makes no AWS call
kanject env --env dev --show-values
```

## Debugging and IDE setup

`--debug` spawns the process so your IDE can attach: it prints the PID and refreshes a kanject-managed **"Attach to Kanject TestTool"** entry in `.vscode/launch.json` (your other launch configs are left untouched). `--setup-ide` writes the IDE profiles and exits without running; `--launch-profile <name>` picks a specific `launchSettings.json` profile for scripting.

```bash
# Spawn the process so an IDE can attach; prints the PID and
# refreshes a .vscode/launch.json "Attach to Kanject TestTool" config
kanject test --debug

# Write the IDE profiles (.vscode/launch.json + launchSettings.json) and exit
kanject test --setup-ide
```

## Guidelines

- **Pull env from a low-stakes stage.** `--pull-env --env dev` resolves live secrets into your shell — don't point it at `prod` casually.
- **Reach for `kanject env` first** to inspect how a key is bound. It masks references by default and never calls AWS or injects anything into a process; use `test --pull-env` when you need to verify remote resolution.
- **`--watch` for the webapi inner loop**, `--event` to replay a real payload through a Lambda from the `events/` folder.
- **Run `kanject test --setup-ide` once** so teammates get the VS Code attach config and launch profiles without hand-editing JSON.
- **In a multi-entry repo, run `test` from the entry's own directory** — it resolves the runtime per project.

**Recap**

- `kanject test` runs your service locally, choosing `dotnet run` for a webapi or the `Amazon.Lambda.TestTool` for a Lambda.
- `--pull-env` injects a stage's real `param:` / `secret:` values into the process, in memory only, with a `KANCLI044` warning for SecureStrings.
- `kanject env` prints local stage bindings, masking parameter and secret references by default; it never fetches their remote values.
- `--debug` / `--setup-ide` keep `.vscode/launch.json` and launch profiles in sync for IDE attach.

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