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 or can be run via npx.


npm install -g nkapp
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.
`--verbose`	Enables detailed logging of infrastructure events and SSH communications.

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 stop`	Stop running services without removing them
`nkapp destroy`	Stop and remove services (keeps volumes by default)
`nkapp clean`	Full project reset: wipe remote infra and local state
`nkapp plan`	Strictly read-only preview of upcoming changes

Deployment

Command	Description
`nkapp deploy`	Deploy directly to a VPS via SSH

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

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 infra`	Manage cloud infrastructure settings
`nkapp infra destroy`	Forcefully wipe all remote infrastructure
`nkapp auth`	Manage cloud provider credentials

Bootstrapping

Command	Description
`nkapp configure`	Interactive wizard to setup a new project
`nkapp init`	Initialize a new Nanokit project