Skip to Content
CLI Referencenkapp provider

nkapp provider

The nkapp provider command group manages cloud provider credentials (the infrastructure axis — “where you deploy”). Credentials are stored per project in .nanokit/auth.json and used for infrastructure provisioning (compute, networking, DNS, registries).

Its subcommands live under provider auth:

nkapp provider auth <provider> [options]   # store & validate a provider's credentials
nkapp provider auth status                 # show authenticated providers

Looking to connect your Nanokit account (login)? That is a separate axis — “who you are”. See nkapp auth.

provider auth — authenticate cloud providers

provider auth aws

Authenticate with Amazon Web Services. Also provisions the required IAM policies.

nkapp provider auth aws --key <access_key> --secret <secret_key> [--region <region>]
FlagTypeDefaultDescription
--key <key>string—AWS Access Key ID
--secret <secret>string—AWS Secret Access Key
--region <region>stringus-east-1Default AWS Region

provider auth do (alias: digitalocean)

Authenticate with DigitalOcean.

nkapp provider auth do --token <token>
FlagTypeDefaultDescription
--token <token>string—DigitalOcean Personal Access Token

provider auth gcp (alias: google)

Authenticate with Google Cloud Platform using a service account JSON key.

nkapp provider auth gcp --file <path> [--project <id>]
FlagTypeDefaultDescription
--file <path>string—Path to the service account JSON key
--project <id>string—GCP project ID

provider auth azure (alias: microsoft)

Authenticate with Microsoft Azure using a service principal.

nkapp provider auth azure --client-id <id> --client-secret <secret> --tenant-id <id> --subscription-id <id>
FlagTypeDefaultDescription
--client-id <id>string—Service principal client ID
--client-secret <secret>string—Service principal client secret
--tenant-id <id>string—Azure tenant ID
--subscription-id <id>string—Azure subscription ID

provider auth cloudflare (alias: cf)

Authenticate with Cloudflare (DNS).

nkapp provider auth cloudflare --token <token> [--zone-id <id>] [--account-id <id>]
FlagTypeDefaultDescription
--token <token>string—Cloudflare API token (DNS edit)
--zone-id <id>string—Zone ID
--account-id <id>string—Account ID

provider auth status

Show authentication status for all configured providers.

nkapp provider auth status
Provider credentials:
AWS: Authenticated (Updated: 2026-04-15T12:00:00Z)
DIGITALOCEAN: Authenticated (Updated: 2026-04-14T09:30:00Z)

Three ways to connect a provider

A cloud provider can be authenticated in three ways. They are interchangeable and follow a clear precedence:

  1. nkapp provider auth <provider> (recommended for local dev) — stores the credentials in .nanokit/auth.json (file mode 0600, git-ignored). This is the source of truth and takes precedence over environment variables.
  2. Environment variables (the CI / .env path) — set each provider’s standard vars (see the table below). No file on disk is required, which makes this ideal for CI/CD. Nanokit reads them from the process environment and from the project’s .env file.
  3. OAuth — proposed, pre-implementation. A browser-based connect flow surfaced directly in the Hub Connections panel. It is specced but not yet shipped — see specs/HUB_CONNECTIONS.md. When it lands it sits lowest in this precedence order: a stored .nanokit/auth.json entry wins over environment variables, which in turn win over an OAuth-linked connection.

CI and headless environments

Each provider also reads its standard environment variables. A stored .nanokit/auth.json entry takes precedence; env vars are used when no stored entry exists (so CI never needs the file on disk). Nanokit resolves these from both process.env and the project’s .env file:

ProviderEnvironment variables
awsAWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION (or AWS_DEFAULT_REGION)
doDIGITALOCEAN_TOKEN (or DO_TOKEN)
gcpGOOGLE_APPLICATION_CREDENTIALS (path to the key file) or GOOGLE_CREDENTIALS (inline JSON); optionally GOOGLE_CLOUD_PROJECT
azureAZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID (+ optional AZURE_SUBSCRIPTION_ID)
cloudflareCLOUDFLARE_API_TOKEN (+ optional CLOUDFLARE_ZONE_ID, CLOUDFLARE_ACCOUNT_ID)

The required variables per provider are: aws needs both the access key id and the secret; azure needs client id + client secret + tenant id; the others need just their token / credentials file.

The Hub “Connections” panel

The Hub dashboard shows a Connections section listing every provider with its live status. A provider appears connected when it is authenticated by any of the methods above:

  • connected (keys) — credentials found in .nanokit/auth.json.
  • connected (env) — credentials detected from environment variables / .env (e.g. Cloudflare configured purely via CLOUDFLARE_API_TOKEN in .env).
  • not connected — neither a stored entry nor the required env vars are present.

The Hub only ever displays masked, non-secret metadata — the last 4 characters of an identifier (e.g. AKIA…WXYZ) plus non-secret fields like region, account, or subscription id. Raw tokens, secret keys, and service-account key contents are never sent to the Hub.

Credential Storage

Provider credentials are stored in .nanokit/auth.json inside your project directory (file mode 0600), and merged so adding one provider never clobbers another. nkapp init adds .nanokit/ and .env* to .gitignore automatically.

[!IMPORTANT] Credentials are never written to .env: Nanokit injects .env into every remote host and container on deploy, so cloud keys placed there would ship to production. .nanokit/ is excluded from the deploy payload.

[!IMPORTANT] These credentials are used exclusively for infrastructure provisioning (e.g., EC2 instances, Droplets, DNS records). They are not used for service-level secrets (use nkapp secrets), nor for your account login (use nkapp auth).

nkapp plannkapp restart