The CLI and the API

Everything the dashboard does, from a terminal or a script.

Everything the dashboard does, it does through CloudJod's API, so everything can be done from a terminal or a script as well. The cloudjod command is the easy way; the API is there for anything else.

The cloudjod command

Install it

On Linux or macOS:

curl -fsSL https://api.cloudjod.com/install/cli.sh | sh

The script downloads the build for your machine, checks it against the checksum it carries, and installs it in /usr/local/bin if it can write there, or ~/.local/bin if not. To choose the directory, put CLOUDJOD_INSTALL_DIR=~/bin before sh.

On Windows, download cloudjod-windows-amd64.exe (or the ARM build), rename it cloudjod.exe, and put it in a folder on your PATH.

Sign in

cloudjod login --api-url https://api.cloudjod.com
cloudjod org use acme

It asks for your email, your password and, if your account has one, a code from your authenticator. It keeps the address, a session and your default organization in cloudjod/config.json in your user configuration folder, readable only by you, and nothing in the folder you run it from. cloudjod logout ends the session.

What it does

See what is there	`cloudjod apps` · `cloudjod app show api` · `cloudjod logs api` · `cloudjod usage api`
Create and deploy	`cloudjod app create api` · `cloudjod connect api https://github.com/acme/api` · `cloudjod build api --wait` · `cloudjod deploy api --image ghcr.io/acme/api:1.4`
Releases	`cloudjod releases api` · `cloudjod rollback api DEPLOYMENT`
Settings	`cloudjod env set api STRIPE_KEY sk_live_… --secret`
Run and schedule	`cloudjod run api python manage.py migrate` · `cloudjod release-command api rake db:migrate` · `cloudjod schedule add api nightly --at "0 2 * * *" -- rake report`
Scale	`cloudjod scale api web=2 worker=3` · `cloudjod scaling api --mode cpu --min 2 --max 8` · `cloudjod sizes`
Start and stop	`cloudjod app start api` · `cloudjod app stop api` · `cloudjod app restart api`
Access	`cloudjod access api team` · `cloudjod vpn add laptop --out laptop.conf`
One-click apps	`cloudjod catalog` · `cloudjod install wordpress blog`

Every command takes --org SLUG to work in another organization for that command, and --json to print the API's answer instead of a table. cloudjod help lists every command.

The API

The API is at https://api.cloudjod.com/v1. It takes and returns JSON.

Authenticate

Make a token under API tokens in the dashboard. Choose a name, the role it acts with (at most your own) and when it expires; its secret, starting cjd_, is shown once. Send it in the Authorization header of every request:

curl -H "Authorization: Bearer $CLOUDJOD_TOKEN" https://api.cloudjod.com/v1/orgs/acme/apps

Credentials are only ever read from that header, never from a cookie or the address. A token acts as the person who made it: never above their role, and if their changes wait for an owner, so do the token's.

A few calls

# Create an app, and release an image to it
curl -X POST -H "Authorization: Bearer $CLOUDJOD_TOKEN" https://api.cloudjod.com/v1/orgs/acme/apps \
  -d '{"slug":"api","container_port":8080}'
curl -X POST -H "Authorization: Bearer $CLOUDJOD_TOKEN" https://api.cloudjod.com/v1/orgs/acme/apps/api/deployments \
  -d '{"image":"ghcr.io/acme/api:1.4"}'

# Set a sealed variable
curl -X PUT -H "Authorization: Bearer $CLOUDJOD_TOKEN" https://api.cloudjod.com/v1/orgs/acme/apps/api/env/STRIPE_KEY \
  -d '{"value":"sk_live_…","is_secret":true}'

# A database, attached to the app
curl -X POST -H "Authorization: Bearer $CLOUDJOD_TOKEN" https://api.cloudjod.com/v1/orgs/acme/addons \
  -d '{"kind":"postgres","slug":"main-db"}'
curl -X POST -H "Authorization: Bearer $CLOUDJOD_TOKEN" https://api.cloudjod.com/v1/orgs/acme/addons/main-db/attach \
  -d '{"app":"api"}'

Answers

A failure is a status code and a body such as {"error": {"code": "invalid_request", "message": "…", "fields": {"slug": "…"}}}. message is written to be shown to a person, code is for a program to branch on, and fields names the inputs at fault.
A change that has to wait for an owner answers 202 with {"approval": {…}} and an X-CloudJod-Approval header, so a script can tell it from one that happened.
A name that is not yours answers 404, whether or not it exists, so nobody can learn what other organizations have.

For automation

Give each script or CI job a token of its own, with the smallest role that does the job, and an expiry.
A repository connected to an app already deploys on every push; a CI job only needs the API for the rest, such as releasing a build it made itself.
Builds and commands are queued and run in the background: the API answers with what it queued, and you follow it from there, as cloudjod build api --wait does.

Next: Plans and limits