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.
`-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.

Execution Workflow

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

Config Validation: The nanokit.yml file is parsed and validated against the Zod schema.
Environment Merging: Environment-specific overrides are applied to the global configuration.
Secret Resolution: All vault:// or env:// references are resolved into actual values.
Infrastructure Planning: Nanokit compares the desired state with the current state of the provider.
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`	Full-stack orchestration: plan, provision, deploy
`nkapp run`	Deploy services only (requires infrastructure to be ready)
`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`	Deploy directly to a VPS via SSH
`nkapp export k8s`	Translate `nanokit.yml` into Kubernetes manifests (offline)
`nkapp export helm`	Generate a parameterized Helm chart from `nanokit.yml` (offline)

Observability

Command	Description
`nkapp hub`	Open the Nanokit Hub (Bridge)
`nkapp logs`	Stream logs from project services
`nkapp shell`	Open an interactive terminal in a service or database
`nkapp expose`	Expose a service to LAN or globally via tunnel

Database Management

Command	Description
`nkapp db`	Manage database lifecycle, branching, and resets
`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

Bootstrapping & Maintenance

Command	Description
`nkapp configure`	Interactive wizard to setup a new project
`nkapp init`	Initialize a new Nanokit project
`nkapp doctor`	Run an environment health check
`nkapp update`	Update the CLI to the latest published version