SuperCIDocumentation

Commands and coding agents

Run everything the dashboard does from a terminal or a coding agent: sign in once, then status, runners, repositories and updates as commands with JSON output.

Everything the dashboard does is also a command, so a script or a coding agent can run SuperCI without a browser. A command fills in the same form its page has and runs the same code, so the two never differ.

Commands have one shape, the Stripe CLI’s:

superci <resource> <operation> [id] [--param=value]

The operations are list, retrieve, create, update and delete wherever they fit.

npx @superci/cli            # lists the commands
npx @superci/cli status

superci help RESOURCE (or superci RESOURCE --help) says more about one. The dashboard itself is superci dashboard.

Signing in

A person signs in once, in the browser. SuperCI keeps that sign-in in its own folder (~/.superci), and commands use it from then on.

superci login            # any cloud; the first screen asks which
superci login aws        # or cloudflare, modal
superci logout           # removes the sign-ins from this computer

SuperCI reads no other tool’s credentials: no AWS profile, no wrangler or Modal login. An AWS sign-in ends after twelve hours at most, as AWS has it. Looking goes on working after that; a change in AWS asks for the sign-in again.

For a coding agent

  • Add --json to any command: one JSON object with what was done or read.
  • Add --dry-run to a change: it checks the flags, the sign-in and the control plane, and says what it would do.
  • A command never asks a question. What it would delete needs --confirm.
  • When a person is needed first, the answer says so and the status is 3:
{ "ok": false, "error": "SuperCI's AWS sign-in has ended…", "needs": "superci login aws" }

Statuses: 0 done, 1 failed, 2 not a command or not a whole one, 3 a person is needed first.

A key that only reads

An agent on your own machine uses SuperCI’s sign-ins, and can do everything you can. To let one look and change nothing, or to let it run on another machine, give it a key instead:

superci keys create agent          # shows the key once
SUPERCI_PLANE=https://… SUPERCI_KEY=superci_read_… superci jobs list --json

With those two set, whatever looks works with no sign-in. Your control plane keeps only the key’s SHA-256. A key ends by itself after 30 days (--days for another length), or at once with superci keys delete agent.

What needs a person

Three things always need a person, once: the first sign-in to each cloud, creating the GitHub App and choosing its repositories (GitHub offers that only on its own pages; superci github create OWNER opens them), and making a GitLab token.

Jobs

superci jobs list
superci jobs retrieve 113201388423              # one job, with the end of its log

Control plane

superci status
superci planes list
superci planes create aws --region=us-east-1    # or: cloudflare [--account=ID], modal
superci planes update                           # to this program's version
superci planes move ID
superci planes allow                            # gives its AWS role what this version asks for
superci planes delete ID --confirm              # one that is not in use
superci leave --confirm                         # stops SuperCI and deletes what it made

Runners

superci runners list
superci runners create aws --region=us-east-1   # or: cloudflare, modal
superci runners order aws aws-on-demand cloudflare
superci runners update aws --max-jobs=20 --monthly-usd=500 --regions=us-east-1,us-east-2
superci runners update aws-on-demand --enabled=false
superci runners update cloudflare --location=weur
superci runners delete modal --confirm
superci machine retrieve                        # what `runs-on: superci` alone gets
superci machine update --cpu=4 --ram=16 --arch=arm64
superci limits retrieve
superci limits update --max-cpu=32 --max-hours=12   # the largest machine; the longest job

More on what these mean: Order and limits, Labels and machines.

Repositories

superci github list
superci github create acme                      # opens GitHub for a person
superci github delete other-org --confirm
SUPERCI_GITLAB_TOKEN=… superci gitlab create --url=https://gitlab.com
superci gitlab_projects list
superci gitlab_projects update 123456 --enabled=true
superci public_repos create acme/site           # a public repository allowed to run here