nkapp auth

Connect this CLI to your Nanokit account (the SaaS identity, "who you are"). The session token is stored globally in ~/.nanokit/hub-token.json and shared by every project on the machine. It is the same token the Hub bridge uses.

nkapp auth <subcommand> [options]

Looking for cloud provider credentials (AWS, GCP, Azure, DigitalOcean, Cloudflare)? Those live on a separate axis, "where you deploy". See nkapp provider auth.

Subcommands

auth login

Authenticate with your Nanokit account. By default this opens your browser to the Nanokit auth page and signs you in there (email/password, OAuth, passkey, MFA, all handled by the web flow). The CLI runs a temporary loopback listener on 127.0.0.1; after a successful sign-in the auth page redirects back to it, the browser shows a success (or error) page, and the session token is captured and stored. No credentials are typed into the terminal.

nkapp auth login

Opening your browser to sign in to Nanokit...
If it doesn't open automatically, visit:
  https://auth.nanokit.dev/login?redirect=http://127.0.0.1:54312/callback?state=...

✔ Connected as jane.doe@example.com (plan: pro).

For headless environments (CI, a remote shell with no browser), use the terminal flow or a pre-issued token:

nkapp auth login --no-browser            # prompt for email + password (+ MFA)
nkapp auth login --token <jwt>           # store a session token directly

Flag	Type	Default	Description
--no-browser	boolean	false	Sign in with email/password in the terminal instead of the browser
--token <jwt>	string	—	Store an existing session token, no sign-in
--email <email>	string	—	Account email (terminal flow; skips the prompt)
--password <password>	string	—	Account password (terminal flow; skips the prompt)
--auth-url <url>	string	auto	Override the auth UI base URL (browser flow)
--api <url>	string	auto	Override the API base URL (terminal flow)

On success the token is written to ~/.nanokit/hub-token.json (mode 0600).

auth logout

Disconnect the CLI by removing the stored session token.

nkapp auth logout

auth status

Show the connected account. The stored token is validated against the API.

nkapp auth status

Connected as jane.doe@example.com (plan: pro)

If no token is stored, the command tells you to run nkapp auth login.

---

CI and headless environments

No browser and no interactive prompt? Provide the token through the environment instead of logging in. nkapp auth status, nkapp up, and nkapp deploy all read it:

export NANOKIT_TOKEN="<session-or-api-token>"
nkapp deploy -e production -y

NANOKIT_TOKEN (alias NANOKIT_HUB_TOKEN) takes precedence over the stored file and nothing is written to disk. For CI, generate a long-lived, revocable token from the dashboard (Account → API Keys) rather than reusing your interactive session token, then set it as NANOKIT_TOKEN. Cloud provider credentials follow the same pattern via their standard env vars (AWS_ACCESS_KEY_ID, DIGITALOCEAN_TOKEN, GOOGLE_APPLICATION_CREDENTIALS, AZURE_CLIENT_ID/AZURE_CLIENT_SECRET/AZURE_TENANT_ID, CLOUDFLARE_API_TOKEN), which take precedence over .nanokit/auth.json. See nkapp provider auth.

Managing API keys from the CLI

You can mint and manage API keys without leaving the terminal (the same keys shown under Account → API Keys). You must be logged in (nkapp auth login).

nkapp auth token create "github-actions" --expires 90   # prints the secret once
nkapp auth token list                                    # metadata only
nkapp auth token revoke <id>

Command	Description
auth token create <name> [--expires <days>] [--api <url>]	Create a key; the secret is printed once
auth token list [--api <url>]	List your keys (prefix, name, expiry, last used)
auth token revoke <id> [--api <url>]	Revoke a key by id

Put the created secret in CI as NANOKIT_TOKEN.

Token Storage

The account session token is stored globally at ~/.nanokit/hub-token.json ({ "token": "<jwt>" }, file mode 0600), not per project. This is the same location the Hub bridge reads, so logging in via the CLI and via the Hub keep the operator's machine in a single, consistent session.

Important. Credentials are never written to .env. In Nanokit, .env is injected into every remote host and container on deploy, so storing operator tokens or cloud keys there would ship them to production. They live only in ~/.nanokit (account) and .nanokit/auth.json (providers), both 0600 and git-ignored, and neither is included in the deploy payload.

Important. This is your account identity, used to talk to the Nanokit backend (Hub, deployments registry). It is distinct from cloud provider credentials (nkapp provider auth), which are project-scoped and used to provision infrastructure.