nkapp plan

Preview all infrastructure and service changes that would be applied, without actually executing them. This is the dry-run equivalent for Nanokit.

nkapp plan [options]

Guarantees

• Read-Only: plan is strictly non-mutating. It never creates, modifies, or destroys real resources on any provider, and it never writes the deploy watermark file (.nanokit/deploy-state.json).
• Environment Isolation: Changes are calculated strictly for the specified environment (-e). It does not detect or interfere with resources in other environments.
• Deep Discovery: Nanokit queries the provider's live API to identify orphans or drift from your nanokit.yml.

Options

Flag	Type	Default	Description
-e, --env <env>	string	local	Environment to plan for
--output <path>	string	.nanokit/plans/latest.json	Save the plan to a specific JSON file

---

Plan Persistence

Every time you run nkapp plan, Nanokit automatically saves the generated plan to .nanokit/plans/latest.json. This file contains the complete structural diff and can be used for auditing or automated validation in CI/CD pipelines.

The plan object includes:

• Timestamp: When the plan was generated.
• Project Context: Project name and ID.
• Infrastructure Delta: Detailed list of resources to create or delete.
• Warnings: Potential issues detected during discovery.

---

Output Sections

Infrastructure

Shows instances to create or destroy based on the infra block:

Infrastructure:
  + Create instance of type t3.medium (role: manager)
  - Destroy resource abc123def456 (running)

Databases

Shows database branching operations for non-production environments:

Databases:
  ⇄ main_db: Create branch from production
  • staging_db: Standard provisioning

Services

Shows container-level changes with the reason for each action:

Services:
  + web: Create new service
  ~ api: Restart/Update (image changed)
  - old-worker: Remove service (removed from config)
  • docs: No changes needed (Status: running)

Deploy scope

A preview of what a nkapp deploy -e <env> from this working copy would touch — the same resolver deploy itself runs:

Deploy scope:
  partial — 2/9 services — changed: web (source)
      - web (source)
      - api (dependent)
  preview only — run nkapp deploy -e stage to apply it (--all forces every service)

It reports the dirtiness (all or partial), the n/total count, the reason string, and every in-scope service with its cause. It is strictly read-only and fails open to silence: if the resolver errors, the section is simply omitted rather than failing the plan.

Two different denominators

plan counts the environment's effective service set (a non-empty environments.<env>.services: block replaces the root set). deploy's own scope line counts the union of the two, so the two totals can differ on such an environment. Neither figure feeds a decision — both are reporting only.

Mail

When a mail: block is configured, the resolved delivery mode for the target environment is reported alongside the rest of the plan.

---

Action Types

Symbol	Action	Description
+	CREATE	New service will be created
~	RESTART	Existing service will be restarted (config changed)
-	DELETE	Service will be removed
•	NO_OP	No changes needed

---

Examples

# Preview changes for local environment
nkapp plan -e local

# Preview production deployment
nkapp plan -e production

# Save the plan somewhere else for CI auditing
nkapp plan -e production --output ./artifacts/plan.json

TIP

Always run nkapp plan before nkapp up or nkapp deploy in production environments to review changes.