Octov0.11.17
Platform

The octopaas CLI

Edit, version, deploy and watch your integrations from the terminal, signed in with your browser or, in CI/CD, with an API key.

octopaas is the command line for the public API. Use it to pull an integration into a folder, edit it with any editor, push it back, freeze it as a version and roll it out, then follow what it logs. Every command acts as you, under your roles, the same as the platform UI. This page covers installing it, signing in, profiles and CI/CD. The command reference lists every command and flag.

Install it

Download the archive for your machine from the latest release, as octopaas_<os>_<arch>.tar.gz (.zip on Windows), and put the octopaas binary on your PATH:

tar -xzf octopaas_darwin_arm64.tar.gz
sudo mv octopaas /usr/local/bin/
octopaas version

The first command you run writes ~/.octopaas/config.yaml, with one profile, default, pointing at https://api.octopaas.dev.

Stay up to date

octopaas checks for a new release at most once a day, in the background. When one is out, it says so on the line after a command's output. To upgrade in place:

octopaas upgrade            # the newest release
octopaas upgrade --check    # only say whether there is one

upgrade downloads the archive for your machine from the release, checks it against the release's checksums.txt, and swaps it in for the binary you are running. If any step fails, your current binary stays as it was. A binary installed with go install is upgraded with go install again, and octopaas prints the exact command. One installed in a folder you cannot write to, such as /usr/local/bin, needs sudo octopaas upgrade.

The check never runs in CI, without a terminal, or with -o json. Set OCTOPAAS_NO_UPDATE_NOTIFIER to switch it off everywhere.

Sign in

People sign in with their browser:

octopaas auth login
octopaas whoami

auth login learns everything it needs from the API itself:

  1. Calling the API without a credential gets a 401 that points at its OAuth metadata. That metadata names the identity provider.
  2. octopaas registers itself with that provider through dynamic client registration. This happens once per provider, and no client secret is involved.
  3. Your browser opens on the provider's sign-in page. PKCE stands in for a secret, and the token is requested for the API as its resource.
  4. The provider sends your browser back to octopaas on 127.0.0.1:8976, and the session is saved for the profile.

The session lives in ~/.octopaas/credentials.yaml, which only you can read. It renews itself until you run octopaas auth logout. whoami shows the account you act as, your roles, and where the platform address and the credential each came from.

On a machine without a browser, run octopaas auth login --no-browser and open the printed link in a browser that can reach that machine's localhost.

Prefer signing in for anything a person runs. A session carries no long-lived secret, ends when you sign out, and is tied to you. Keep API keys for automation.

Work with more than one platform

A profile is one platform: its API address, and optionally an API key. For example, keep production as default and add your local cluster:

octopaas profile add local --url http://localhost:8095
octopaas auth login --profile local
octopaas profile list

A command picks its profile in this order:

  1. --profile (or -p)
  2. OCTOPAAS_PROFILE, for one shell or one job, without changing anything
  3. the current profile, which you set with octopaas profile use <name>

Naming a profile that does not exist is an error. octopaas never falls back to the current profile on a typo.

Work in an environment

A platform can have several environments, such as staging beside the default, octo. Every command acts in one, and only sees that environment's integrations, deployments and logs:

octopaas environments list
octopaas --environment staging integrations list
octopaas environments use staging     # saved on the profile in effect
octopaas environments current         # which one, and why

A command picks its environment in this order:

  1. --environment
  2. OCTOPAAS_ENVIRONMENT
  3. the profile's, which you set with octopaas environments use <name> or octopaas profile add <name> --environment <env>
  4. octo, the default

octopaas environments use checks the name against the platform before saving it. octopaas profile list and octopaas whoami show the environment in effect.

Use it in CI/CD

A pipeline needs no config file and no sign-in. Set the platform and an API key from your secret store, and run commands directly:

# .github/workflows/release.yml (excerpt)
env:
  OCTOPAAS_URL: https://api.octopaas.dev
  OCTOPAAS_KEY: ${{ secrets.OCTOPAAS_KEY }}
steps:
  - run: octopaas integrations push billing ./billing
  - run: octopaas versions create billing "$GITHUB_REF_NAME"
  - run: octopaas deployments rollout billing --version "$GITHUB_REF_NAME"

To ship to an environment other than the default, also set OCTOPAAS_ENVIRONMENT. A key minted while that environment was chosen in the platform is bound to it, and refuses every other.

Mint the key on your account page (see API keys). A key acts as the user who minted it, limited to the roles you gave it. Give a pipeline the CI/CD role: it pushes code, tags versions, runs tests and rolls out, and reads the integrations, versions, deployments, test reports, upgrades and runtimes that takes. It cannot create, scale or delete anything, or read logs, code or configuration (the full list). Create the integration and its first deployment yourself; a CI/CD key ships to them but cannot create them. It rolls out deployments that have no platform access grants; one that has them needs a signed-in person. Keep the key in your CI secret store: what it deploys keeps running after the key is revoked, so a leaked key is a production incident (see API keys). octopaas whoami shows the roles a key carries. When a command needs a role the key lacks, octopaas says so and points you to the account page to mint one that has it. When both OCTOPAAS_URL and OCTOPAAS_KEY are set and there is no config file yet, octopaas does not write one, so a read-only home directory is fine.

In CI, the output is plain automatically: no colours, animations or art. Any slow wait, such as a deploy, prints a line each time its state changes. Add -o json (or -o yaml) to any command for machine-readable output. Results go to stdout and commentary goes to stderr, so piping into jq always works:

octopaas deployments list -o json | jq -r '.[] | select(.status != "running") | .name'

Environment variables

VariableWhat it does
OCTOPAAS_URLThe API to talk to. Overrides the profile's url; --url overrides it.
OCTOPAAS_KEYAn API key (octo_…). Overrides the profile's key and any signed-in session.
OCTOPAAS_PROFILEThe profile to use. --profile overrides it.
OCTOPAAS_ENVIRONMENTThe environment to act in. Overrides the profile's; --environment overrides it.
OCTOPAAS_HOMEWhere config.yaml and credentials.yaml live (default ~/.octopaas).
NO_COLOR, CIEither one switches off colours and animations, as --plain does.
OCTOPAAS_NO_UPDATE_NOTIFIERSet to anything to stop octopaas checking for, and mentioning, new releases.

Flags beat the environment, the environment beats the profile, and the profile beats the defaults.

A typical loop

octopaas integrations pull billing          # into ./billing
$EDITOR billing/integration.yaml
octopaas integrations push billing          # from ./billing
octopaas versions create billing v1.4.0
octopaas deployments rollout billing --version v1.4.0
octopaas logs billing -f

pull refuses to unpack over a folder that already has files unless you add --force. It keeps the bundle's manifest in .octo/octo-bundle.json, out of the integration's own files, and push reads it from there. push sends the folder as it is now: files you added go up and files you deleted are removed. It never sends hidden files such as .git or a local .env, except the hidden resources the platform sent you in the first place. Commands take integrations and deployments by name or by id, and versions by tag.

On this page