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.

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. The webapi and minimal-api templates don't run in the TestTool, so run them with --http, as a plain web host on Kestrel.
• library — no runner; use dotnet test / dotnet run directly.

# Run the service locally — webapi runs with dotnet, a Lambda launches the TestToolkanject test​# Hot-reload a webapikanject test --watch​# Send a Lambda an event payload (from the events/ folder)kanject test --event events/order-created.json​# Run an API template (ASP.NET Core in Lambda) as a plain web host on Kestrelkanject 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 CLI never writes them to disk. A summary panel prints the count by source (without the values) before launch.

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

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: bindings are masked by default and param: bindings print as written; --show-values unmasks the binding string, never the remote secret. When stage is omitted on a terminal, the sole stage is selected or a picker appears; scripts must pass it explicitly.

# Omit --env on a terminal to use the sole stage or choose from a pickerkanject env​# Reveal the stored binding strings — this still makes no AWS callkanject env --env dev --show-values

Debugging and IDE setup

Normal runs, including --debug, preserve launch settings and VS Code files. --debug launches from the CLI, verifies HTTP readiness, then prints the application child PID or a name-only attach hint. Attach to that API process in your IDE. Startup code may already have run; use the native launch workflow below when you need startup breakpoints.

# CLI launch followed by IDE attach (available today)kanject test --entry api --http --env dev --pull-env --debug​# Generate native Debug/F5 configuration, then exit (CLI 1.0.67+)kanject test --entry api --http --env dev --pull-env --setup-ide --port 20287​# Copy your existing local Project profile settings when needed# Add: --launch-profile "Local API"

Run setup at the service root with the intended entry, stage and --pull-env. It generates Kanject HTTP api (dev), a local bootstrap DLL and a VS Code build task. Setup fetches no secrets and starts no application. Each native Debug/F5 launch resolves fresh stage references before your first application statement, through a private current-user pipe. No retrieved secrets are written into profiles, tasks, env files or logs.

Rider: native Debug

• Open the solution and import/generate run configurations from the selected project’s Properties/launchSettings.json if Rider has not imported them.
• Select Kanject HTTP api (dev) in the run configuration dropdown, set a startup breakpoint before WebApplication.CreateBuilder, then click Debug.
• Continue, request an endpoint your app maps, and confirm an endpoint breakpoint. Stop the session with Rider’s Stop button.

VS Code: native F5

• Open the service root containing the generated .vscode directory. Install a .NET debugging extension supporting coreclr and the SDK matching the project.
• Select Kanject HTTP api (dev) in Run and Debug. Set startup and endpoint breakpoints, then press F5.
• The generated pre-launch task builds the selected project; the IDE launches its actual Debug DLL. A shell export task or an attach configuration cannot supply this startup-debugging behavior.

Visual Studio: native F5 on Windows

• Open the solution and set the selected API project as the startup project.
• Choose Kanject HTTP api (dev) in the launch-profile dropdown, set startup and endpoint breakpoints, then press F5. Use the Project profile rather than IIS Express.
• Continue and request a mapped endpoint to verify the handler breakpoint. These are the intended configuration steps; Windows native debugging acceptance remains pending.

Profiles, credentials and recovery

Managed .NET 8+ is required. Native AOT published binaries, .NET Framework, IIS Express and remote/container debugging are outside this workflow. For Lambda TestTool, omit --http during setup and select Kanject Lambda api (dev). The stage’s AWS profile/region and your existing credential chain must work for the user running the IDE.

Use --launch-profile "Local API" during setup to copy compatible local settings such as Development, InMemory storage and local signing. Local settings override ordinary stage values; freshly retrieved secret/SecureString values override stale local secret literals. User-owned profiles and unrelated VS Code configurations are preserved. Your IDE can inspect the resulting in-memory values.

Rerun setup after moving a checkout or updating Kanject CLI. .kanject/ide/ holds the machine-local bootstrap and is ignored by Git; generated absolute paths must be refreshed on each machine. KANCLI660 stops startup before application code if the bootstrap, credentials or protocol fail. Refresh setup, check AWS login, then run the matching kanject test --entry api --http --env dev --pull-env command in a terminal for normal diagnostics.

Check the correct entry and URL

Use --entry api for a multi-entry service. With --http, a sole HTTP entry is selected automatically; multiple compatible entries require an ID (KANCLI046). An incompatible explicit launch profile fails KANCLI047. Select a Project profile for HTTP, or a TestTool Executable profile for Lambda.

The CLI prints Ready only after an HTTP response from its new server. Any status, including 404 or 401, proves a listener; it does not prove dependency health. / is visible only when your app maps a page, and /health exists only when your app defines it. No browser opens automatically. KANCLI048 means early exit; KANCLI049 means startup timeout. Use --startup-timeout 120 for legitimately slow startup.

Guidelines

• Pull env from a low-stakes stage. --pull-env --env dev resolves live secrets into the child process — don't point it at prod casually.
• Reach for kanject env first to inspect how a key is bound. It masks secret: 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 per machine to write launch profiles and IDE configuration without hand-editing JSON.
• Run test from the service root, where kanject-cli/ lives: --env and --pull-env read the stage from there. In a multi-entry service, select --entry <ID> when more than one entry matches.