npl — CLI Reference

What you can deploy

nonprofits.live runs any application that can be containerized — not just static websites.

Stack	Build type	Notes
Next.js, React, Vue, Svelte	nixpacks	Auto-detected — no config needed
Node.js API / Express	nixpacks	Auto-detected
Python / Django / FastAPI	nixpacks	Auto-detected
Go, Ruby, PHP	nixpacks	Auto-detected
Any app with a Dockerfile	dockerfile	Full control over the build
Plain HTML / CSS / JS	static	Served directly via Nginx

nixpacks is the default and handles most common stacks automatically. Use dockerfile when you need a custom build process or runtime.

Current limitations

Limitation	Workaround
Public GitHub repos only — private repo support (SSH keys) is coming	Connect private repos manually via panel.nonprofits.live
No --image flag — can’t deploy a pre-built Docker image directly	Push source to GitHub and use --build dockerfile
Env vars stored as plaintext — no encryption at rest beyond Dokploy’s Postgres	Use npl env set for standard config; for sensitive secrets (medical data, payment keys) contact TFN for Doppler integration
Docker Compose not exposed via npl	Create multi-container apps directly in the Dokploy panel

---

Installation

One-command install (Linux & macOS):

curl -fsSL https://nonprofits.live/install.sh | bash

Auto-detects your OS and architecture, downloads the right binary from GitHub Releases, and installs it to /usr/local/bin.

Download manually:

Platform	File
Linux (Intel/AMD)	npl-linux-amd64
Linux (ARM)	npl-linux-arm64
macOS (Intel)	npl-darwin-amd64
macOS (Apple Silicon)	npl-darwin-arm64

chmod +x npl-linux-amd64 && sudo mv npl-linux-amd64 /usr/local/bin/npl

Verify:

npl --help

---

Configuration

After npl login, credentials are stored at ~/.config/npl/config.json:

{
  "cp_url": "https://api.nonprofits.live",
  "auth_token": "<JWT>"
}

The file is written with 0600 permissions. The JWT expires after 7 days — run npl login again to refresh.

---

Commands

npl init

The recommended starting point for any new TFN developer. Walks you through everything in one session — no docs required.

npl init

Step	What happens
1. Authenticate	Logs you in with email + password. Skipped if you’re already logged in.
2. Organization	Pick an existing org or create a new one for the nonprofit.
3. Domain	Choose a *.nonprofits.live subdomain or enter the nonprofit’s own domain.
4. Deploy	Optionally connect a GitHub repo and trigger the first build right now.
5. GitHub CI/CD	Wires up auto-redeploy on every git push.

On the domain step: If the nonprofit already has a domain (e.g. amanikenyango.org), choose option 2 and add an A record at their registrar pointing to 138.68.67.49 before running npl deploy.

---

npl login

Authenticate against the nonprofits.live Control Plane.

npl login

Prompts interactively for Control Plane URL, email, and password. On success, saves a JWT to ~/.config/npl/config.json.

Note: Registration is invite-only. A TFN admin must create your account via npl user create before you can log in.

---

npl user create

Admin only. Create a new user account and print a one-time password.

npl user create <email> <name> [--admin]

Flag	Description
--admin	Grant this user admin privileges

---

npl org list

List all organizations you are a member of.

npl org list

Output columns: ID, NAME, SLUG, YOUR ROLE

---

npl org create

Create a new organization. You automatically become its admin.

npl org create <name> [--slug <slug>]

The slug is auto-generated from the name if omitted: "Amani Kenya 2024" → amani-kenya-2024.

---

npl org invoice

Print a resource-cost invoice for an organization’s current billing cycle.

npl org invoice <org-id> [--start YYYY-MM-DD] [--end YYYY-MM-DD]

Rate card: $0.048 per CPU compute-hour · $0.006 per GB-hour of RAM

---

npl deploy

Create a project workspace and deploy a GitHub repository in one command.

npl deploy --repo <owner/repo> --org <id> [flags]

Flag	Short	Required	Default	Description
--repo	-r	Yes	—	GitHub repo: owner/repo or full URL
--org	-o	Yes	—	Organization ID
--name	-n	No	repo name	Project name
--branch	-b	No	main	Git branch to deploy
--build		No	nixpacks	Build type: nixpacks | dockerfile | static
--port	-p	No	3000	Port the app listens on
--domain	-d	No	—	Custom domain

Making a deployment publicly accessible:

Without --domain, the app builds and runs inside Dokploy but has no public URL. Add an A record pointing your domain to 138.68.67.49, then deploy with --domain.

Private repos: SSH key support is coming. For now, npl deploy works with public GitHub repos.

---

npl env list

List all environment variables set on a deployed project.

npl env list <project-id>

Values longer than 40 characters are truncated in the output. Changes take effect on the next deploy.

---

npl env set

Set or update an environment variable on a deployed project.

npl env set <project-id> KEY=VALUE

Examples:

npl env set 3 DATABASE_URL=postgres://user:pass@host:5432/db
npl env set 3 DEBUG=false
npl env set 3 STRIPE_KEY=sk_live_...

Note: Changes are saved immediately but take effect on the next deploy. Push a commit or run npl deploy to apply them.

---

npl env unset

Remove an environment variable from a deployed project.

npl env unset <project-id> KEY

The project must have been deployed (have a running app) before env vars can be managed. Run npl deploy first.

---

npl project list

List all projects across your organizations.

npl project list

---

npl project create

Create a project workspace only (without deploying). Use npl deploy for the full flow.

npl project create <name> --org <id> [--description <desc>]

---

npl project status

Display recent CPU and memory usage for a project.

npl project status <project-id> [--limit <n>]

Each data point = one 15-minute scrape window. Default: 16 points.

---

Global flags

Flag	Description
--help, -h	Show help for any command

---

Error handling

All commands exit with code 1 on failure:

Error: not authenticated — run 'npl login' first
Error: listing organizations: HTTP 403 — access denied
Error: network error — is the Control Plane reachable?
Error: admin access required