Install the CLI

One command line tool to deploy and manage what you run on Naijacloud. Install it, log in once, and the rest of this section is what you can do with it.

4 min read

The CLI installs under two names, naijacloud and the shorter njc. They are the same executable, so use whichever you prefer. These docs use the long name, and describe version 1.5.0.

It is not nc. That is netcat, which exists on nearly every Unix machine, and taking the name would shadow it on your PATH.

Install

npm

If you have Node.js 20 or newer:

Terminal

bash

npm install -g @naijacloud/cli

You can also run it without installing:

Terminal

bash

npx @naijacloud/cli login

The old unscoped naijacloud-cli package is deprecated and frozen. Releases go to @naijacloud/cli. Nothing about usage changed.

macOS

Terminal

bash

brew install naijacloud/tap/naijacloud

The formula is in the naijacloud/tap tap, not homebrew-core, so it needs the prefix. Run brew tap naijacloud/tap once and plain brew install naijacloud works after that.

Linux

Download the .deb or .rpm from the latest release and install it directly. There is no apt or yum repository to add.

bash

v=$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/naijacloud/nc-cli/releases/latest | sed 's|.*/v||')
curl -fLO "https://github.com/naijacloud/nc-cli/releases/download/v$v/naijacloud_${v}_amd64.deb"
sudo dpkg -i "naijacloud_${v}_amd64.deb"

The first line looks up the latest version, so the commands keep working after each release. On an ARM machine use _arm64.deb or .aarch64.rpm.

Both packages embed their own runtime, so they install on a machine that has never seen Node. Since there is no repository behind them, apt upgrade will not carry the CLI forward. Install a new release the same way you installed this one, or use the install script below, which resolves the latest version for you.

Windows

Terminal

powershell

scoop bucket add naijacloud https://github.com/naijacloud/scoop-bucket
scoop install naijacloud

Or use the install script under WSL, or npm with Node 20 or newer.

Install script

Terminal

bash

curl -fsSL https://raw.githubusercontent.com/naijacloud/nc-cli/main/install.sh | sh

Installs into your home directory, without sudo, and picks the latest release.

Read the script before you pipe it to a shell. Piping a URL into sh runs whatever that server returns, and a swapped host owns your account the moment you run it. Save it, read it, then run it.

Log in

Terminal

bash

naijacloud login

You are prompted for your Naijacloud email and password. The password is not echoed and is never written to disk. Only the returned token is stored.

If your account has two-factor authentication on, you are then asked for the 6-digit code from your authenticator app, or one of your recovery codes. In a script, pass it with --code:

Terminal

bash

naijacloud login --email you@example.com --password "$NC_PASSWORD" --code 123456

API keys and --token never need a code. Two-factor protects signing in, and a key is not a sign-in.

The token is checked against the API before anything is saved, so a bad credential fails immediately rather than at your next command. On success it goes to ~/.naijacloud/config.json with mode 0600, inside a 0700 directory.

A password login also sends this machine's device id, a random value created once in ~/.naijacloud/device and kept when you log out. Naijacloud emails you about a sign-in from a device it has not seen before, so the first login from a machine may send that email and later ones do not.

For CI or scripting, use a workspace API key rather than your password. Create one under Settings → API keys in the dashboard. It starts with nc_live_. Give it the Platform API scope, which every command works with. A key with only Deploys can run redeploy <service-id> and read deployments and logs, but cannot ship a static site or look a service up by name.

Terminal

bash

naijacloud login --token "$NAIJACLOUD_API_KEY"                    # check it and store it
HOSTING_API_TOKEN="$NAIJACLOUD_API_KEY" naijacloud deploy --yes   # or pass it per command

A key does not expire after a few days the way a login session does, and you can revoke it on its own. naijacloud login --email … --password … also works, but it leaves your password in your shell history.

Check and clear:

Terminal

bash

naijacloud whoami    # prints the account, or exits 1
naijacloud logout    # deletes the stored credentials

logout deletes the file but does not end the session on the server. The token stays valid until it expires, which is 7 days for a password login. An API key stays valid until you revoke it under Settings → API keys.

Configuration

Variable	Default	Purpose
`HOSTING_API_TOKEN`		Access token or `nc_live_` API key. Takes precedence over stored credentials, so you can override the account per shell
`HOSTING_API_BASE_URL`	`https://api.naijacloud.com`	API base URL. Must be `https://`; plain `http://` is only accepted for `localhost`
`HOSTING_API_TIMEOUT_MS`	`30000`	Per-request timeout
`HOSTING_UPLOAD_TIMEOUT_MS`	`600000`	Timeout for a static site upload, which is one large PUT rather than an API call
`NAIJACLOUD_DEPLOY_TIMEOUT_MS`	`900000`	How long `deploy` and `redeploy` wait for a build to finish

Tokens resolve in the order HOSTING_API_TOKEN, then ~/.naijacloud/config.json. With neither, every command fails with Not logged in. Run 'naijacloud login' first. rather than a raw 401.

The CLI refuses to send a token or password over plain http:// to anything but your own machine. If HOSTING_API_BASE_URL points somewhere other than the API your saved login came from, it warns before sending the token there.

Check it worked

Terminal

bash

naijacloud --version   # 1.5.0 or newer
naijacloud whoami
naijacloud projects ls

Next steps

Command referenceProjects, services, deploys, variables, domains and the database console.