CLI
/
Command reference
Command reference
Everything the dashboard does, 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
naijacloud projectThe 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 and domains. A database has a console. A cron job has a schedule and its run history.
Projects and environments
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 itenvironments is spelled in full. env is the variables command, not a
shorthand for this one.
Services and deploys
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 buildredeploy waits for the build by default and exits non-zero if it fails, so it
gates a pipeline on its own. --no-wait returns once the build is queued.
Environment variables
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 aloneValues are masked by default, because env ls gets run on shared screens and
piped into build logs.
env ls
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:
op read "op://vault/db/url" | naijacloud env set DATABASE_URL --service api --secretDomains
naijacloud domains ls --service api
naijacloud domains add app.example.com --service api
naijacloud domains verify app.example.com
naijacloud domains rm app.example.comdomains add prints the DNS record to create. domains verify checks it and
issues the certificate. See custom domains for
what the records mean.
The database console
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-dbThe 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
shop-db · POSTGRES · prod
Type \? for help, \q to quit.
prod/shop-db=# SELECT id, email
-# FROM users;
id email
── ─────────────
1 [email protected]
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.
DROP,TRUNCATE,ALTER,GRANT,REVOKE, and anUPDATEorDELETEwith noWHEREclause. A filtered write runs unchallenged.
a confirmed statement
$ 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:
naijacloud db dump --service shop-db | xargs curl -OPostgres, 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
$ 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-osIn 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
Every command takes --json and writes its result to stdout, while prompts,
progress and warnings go to stderr. So this is safe to pipe:
naijacloud services ls --json | jq -r '.[] | select(.type == "web") | .name'Exit status is non-zero on failure.
--yes skips the confirmation on cancel, env rm, env import,
environments rm and domains rm, which is what CI needs. --limit caps rows.