Command reference

Projects, services, deploys, variables, domains and the database console, named and flagged. Use naijacloud project to look around when you do not know what you want, and these when you do.

7 min read

Look around

Terminal

bash

naijacloud project

The interactive view. It walks the resource tree the way the platform models it, project then environment then service, one level per screen, down to a service's deployments, variables, domains and database console. Reach for it when you do not already know the name of the thing you want.

What a service offers depends on its type. A web service has deployments, variables and domains. A cron job has deployments and variables but no domains, since nothing routes traffic to it. A database has its connection details and a console.

It is also where you create a database: pick an environment, then + New database, and choose the engine and size. There is no flag-driven command for creating a database yet.

Projects and environments

Terminal

bash

naijacloud projects ls                     # every project, across every team
naijacloud projects show karakata          # environments, and the services in each
naijacloud projects create shop --team acme

naijacloud environments ls --project shop
naijacloud environments create prod --project shop
naijacloud environments rm shop/staging    # and every service in it

environments is spelled in full. env is the variables command, not a shorthand for this one.

Services and deploys

Terminal

bash

naijacloud services ls                     # flat list, one request
naijacloud services show karakata-api      # repo, branch, build command, URL
naijacloud services create api --env shop/prod --repo acme/shop --dotenv .env

naijacloud deployments ls --service api --limit 10
naijacloud deployments show <id>
naijacloud deployments logs <id>           # build output
naijacloud redeploy api                    # build the service's branch tip
naijacloud cancel <id>                     # stop an in-flight build
naijacloud rollback <id>                   # put an earlier deployment's image back live

redeploy and rollback wait for the deployment by default and exit non-zero if it fails, so they gate a pipeline on their own. --no-wait returns once it is queued. rollback releases the exact image an earlier successful deployment ran, without rebuilding; find its id with deployments ls.

Where a service's code comes from

services create takes one of three sources, the same three the dashboard offers:

Terminal

bash

# a repository the Naijacloud GitHub App can reach (a github.com URL works too)
naijacloud services create api --env shop/prod --repo acme/shop

# any public git repository, on any host, without the GitHub App
naijacloud services create api --env shop/prod --git https://gitlab.com/acme/shop

# a prebuilt public Docker image, run as it is
naijacloud services create api --env shop/prod --image ghcr.io/acme/shop:1.8.0 --port 8080

A cron job also needs --type cron, a --schedule and, from a repository, the --command to run on each schedule:

Terminal

bash

naijacloud services create nightly --env shop/prod --type cron \
  --git https://github.com/acme/jobs --schedule "0 3 * * *" --command "node cleanup.js"

The service is created at the Free size unless --tier names a paid one. Run naijacloud services create --help for every option. Local code that is not in a repository can only go up as a static site.

Environment variables

Terminal

bash

naijacloud env ls --service api
naijacloud env set DATABASE_URL --service api --secret
naijacloud env rm OLD_FLAG --service api
naijacloud env import .env --service api   # upserts, leaves other keys alone

Values are masked by default, because env ls gets run on shared screens and piped into build logs.

env ls

output

KEY           SCOPE  SECRET  VALUE
DATABASE_URL  ALL    yes     ******** (106)
NODE_ENV      ALL    no      ******** (5)

--reveal opts in. env set KEY with no value reads it from a hidden prompt, or from stdin when piped, so a credential need not land in your shell history or the process table:

Terminal

bash

op read "op://vault/db/url" | naijacloud env set DATABASE_URL --service api --secret

A value that starts with -- goes after a lone --, which ends the options:

Terminal

bash

naijacloud env set NODE_OPTIONS --service api -- --max-old-space-size=4096

Domains

Terminal

bash

naijacloud domains ls --service api
naijacloud domains add app.example.com --service api
naijacloud domains verify app.example.com --service api
naijacloud domains rm app.example.com --service api

domains add prints the DNS records to create, exactly as the platform works them out for the region the service runs in: an A record to the server's address in some regions, a CNAME plus ownership and certificate TXT records in others. It also lists any existing record that would stop the domain verifying. domains verify checks the records and issues the certificate. It exits 1 until the domain is active, so a CI step can wait on it.

--service can be left out in a directory whose naijacloud.json names the service. See custom domains for what the records mean.

The database console

Terminal

bash

naijacloud db tables --service shop-db          # tables, views, row estimates
naijacloud db describe users --service shop-db  # columns, types, keys, FKs
naijacloud db query "SELECT id, email FROM users LIMIT 10" --service shop-db
naijacloud db shell --service shop-db           # REPL
naijacloud db dump --format sql --service shop-db
naijacloud db export users --format csv --service shop-db

The shell is a REPL over the same operation, with the psql meta-commands already in your fingers. Statements end with ; and may span lines.

db shell

output

shop-db · POSTGRES · prod
Type \? for help, \q to quit.

prod/shop-db=# SELECT id, email
            -# FROM users;
id  email
──  ─────────────
1   a@example.com
1 row · 4 ms

prod/shop-db=# \dt
NAME          KIND   SCHEMA  ~ROWS
users         table  public     42
active_users  view   public      -

Queries run as the service's own database user and can write.

There is no read-only mode to ask for.

Two things guard against a mistake, and neither is a prompt on every statement, because a console that nags is one you stop reading.

The prompt tells you where you are. environment/service=#, so a production database never looks like a scratch one.
Irreversible statements are confirmed in a terminal. DROP, TRUNCATE, ALTER, GRANT, REVOKE, and an UPDATE or DELETE with no WHERE clause. Every statement in the input is checked, and comments and strings are read for what they are, so BEGIN; DROP TABLE t; COMMIT; and DELETE FROM t -- WHERE id = 1 are confirmed too. So is anything the check cannot read for certain, such as an unclosed quote or a DO block. A filtered write runs unchallenged.

a confirmed statement

output

$ naijacloud db query "DELETE FROM users" --service shop-db
This deletes every row (no WHERE clause).
Run it against shop-db (prod)? [y/N]: n
Not run.

Outside a terminal the prompt is skipped rather than failed. A statement passed as an argument in CI was written deliberately, and psql -c makes the same call. --yes skips it explicitly.

db dump and db export print an expiring presigned URL on stdout, with the filename, size and expiry on stderr, so this works:

Terminal

bash

naijacloud db dump --service shop-db | xargs curl -O

Postgres, MySQL, MariaDB and MongoDB have a console. Redis and Valkey take commands rather than statements, so db declines them and says so.

Naming things

Services and projects are referenced by name or id, so nothing needs a UUID copied out of the dashboard. Where one name matches two services, the CLI refuses to guess and lists the candidates. Qualify it as project/name:

an ambiguous name

output

$ naijacloud services show atelier-os
Error: 'atelier-os' matches 2 services. Use the id, or qualify it as project/name:
  30d76735-…  atelieros/atelier-os
  7cd6a26f-…  atelieros/atelier-os

In a directory whose naijacloud.json names a serviceId, --service is optional. naijacloud env ls targets the linked service the same way naijacloud deploy does.

Scripting

The resource commands take --json and write their result to stdout, while prompts, progress, warnings and errors go to stderr. So this is safe to pipe:

Terminal

bash

naijacloud services ls --json | jq -r '.services[] | select(.type == "WEB") | .name'

Errors are plain text on stderr, not JSON. project, launch, db shell, logout and schema are interactive or have their own output, and take no --json.

Every command has its own help: naijacloud deploy --help, or naijacloud help deploy. It prints the help and does nothing else. An unknown or misspelt option is an error rather than being ignored, so --servcie api stops with "did you mean --service?" instead of acting on another service.

Exit status	Meaning
`0`	It worked
`1`	The command ran and failed, including `domains verify` on a domain that is not active yet
`2`	It was typed wrong: an unknown option, or a missing value or argument
`130`	You backed out of a prompt

--yes skips the confirmation on cancel, env rm, env import, environments rm and domains rm, which is what CI needs. --limit caps rows.

Next steps

Environment variablesScopes, secrets and secret files.