CLI Overview

The Nanokit CLI, invoked via the nkapp command, is the central tool for managing your application's lifecycle. It handles everything from local development bootstrapping to remote cloud orchestration.

Installation

Nanokit is distributed as a global npm package (@nkapp/cli) or can be run via npx.

npm install -g @nkapp/cli
nkapp --version

Global Flags

Most commands support these flags to ensure consistency across different environments and automation flows:

Flag	Description
-e, --env <env>	Specifies the target environment (e.g., local, stage, production). Defaults to local for most commands (stage for deploy).
-y, --yes	Skips interactive confirmation prompts. Essential for CI/CD pipelines.
-V, --version	Prints the CLI version.
--help	Shows help for any command or subcommand.

There is no global --verbose flag. Use nkapp doctor for diagnostics and nkapp logs for service output.

up vs deploy

These two commands were split, and the division of labour is the single most important thing to know about the CLI:

	nkapp up	nkapp deploy
Owns	service reconcile	provisioning · host bootstrap · code sync · service reconcile
Infrastructure plan/apply	skipped by default (--infra opts in)	yes
Remote code sync	skipped by default (--sync opts in)	yes
Typical use	inner loop, local and remote	shipping a change to a target

--legacy (or NANOKIT_UP_LEGACY=1) restores the pre-split up pipeline.

Execution Workflow

When you run nkapp up, Nanokit follows a deterministic multi-stage workflow:

1. Config Validation: The nanokit.yml file is parsed and validated against the Zod schema.
2. Environment Merging: Environment-specific overrides are applied to the global configuration.
3. Secret Resolution: All vault:// or env:// references are resolved into actual values.
4. Infrastructure Planning (opt-in on up; always on deploy): Nanokit compares the desired state with the current state of the provider.
5. Action: The plan is applied, creating or updating resources as needed.

---

Command Reference

Lifecycle Commands

The primary commands you'll use daily to manage your stack:

Command	Description
nkapp up	Reconcile services (change-proportional); infra + sync are opt-in
nkapp run	Deprecated alias of up — use nkapp up
nkapp start	Start stopped services without recreating containers
nkapp stop	Stop running services without removing them
nkapp restart	Restart running services
nkapp destroy	Stop and remove services (keeps volumes by default)
nkapp clean	Full project reset: wipe remote infra and local state
nkapp teardown	State-free, tag-based remote teardown for CI/CD
nkapp plan	Strictly read-only preview of upcoming changes

Deployment

Command	Description
nkapp deploy	Provision, sync and deploy to a VPS via SSH (or a cloud provider)
nkapp migrate	Move an environment to a different deploy target
nkapp ci init	Scaffold a GitHub Actions / GitLab CI workflow that runs nkapp deploy
nkapp export k8s	Translate nanokit.yml into Kubernetes manifests (offline)
nkapp export helm	Generate a parameterized Helm chart from nanokit.yml (offline)
nkapp import k8s	Scaffold a nanokit.yml from existing Kubernetes manifests (offline)

Observability

Command	Description
nkapp hub	Open the Nanokit Hub (Bridge) — aliases: bridge, dashboard
nkapp logs	Stream logs from project services
nkapp shell	Open an interactive terminal in a service or database
nkapp doctor	Read-only environment health check
nkapp certs	Read-only TLS certificate inventory (gateway storage + live probe)

Host Hygiene

Three prune commands with the same shape: a mandatory side-effect-free preview, explicit guards, and an --ssh host override. None of them is wired into up/deploy — detection is automatic in doctor, removal stays explicit.

Command	Description
nkapp volumes prune	Remove orphaned Nanokit-managed volumes
nkapp containers prune	Remove stale (exited/created, aged-out, unclaimed) containers
nkapp images prune	Reclaim Docker image space (dangling by default)

Database Management

Command	Description
nkapp db	Manage database lifecycle, branching, resets and password rotation
nkapp backup	Take manual backups and manage the backup catalog
nkapp restore	Restore a database from a backup

Configuration Management

Command	Description
nkapp config	Unified command to manage all project settings
nkapp service	Add, remove, or modify services in nanokit.yml
nkapp host	Manage project hostnames, SSL trust, and remote bootstrapping
nkapp secrets	Manage secrets and Vault integration
nkapp env	List and sync environment variables
nkapp infra	Manage cloud infrastructure settings
nkapp infra destroy	Forcefully wipe all remote infrastructure

Account, Providers & Teams

Command	Description
nkapp auth	Connect the CLI to your Nanokit account
nkapp provider auth	Manage cloud provider credentials
nkapp team	Manage teams, invites, and role-based access

Agents

Command	Description
nkapp mcp	Start the MCP server for an AI agent host; approve, deny and audit agent requests

Bootstrapping & Maintenance

Command	Description
nkapp configure	Interactive wizard for a new project (refuses if nanokit.yml exists)
nkapp init	Initialize a new Nanokit project
nkapp update	Update the CLI to the latest published version