Skip to main content

The constellation CLI

constellation is one static binary for Linux and macOS. It logs in with your API key, shows your workflow results, runs a mock API and checks bridges against it, scaffolds new bridges, runs the official ones, and verifies release downloads. Get it from Downloads.

CommandWhat it does
loginStore an API key and check it
whoamiShow the account the key belongs to
results tailPrint workflow results as they arrive
mockServe the results endpoints with the demo scenario
conformanceCheck a bridge against the mock API
bridge newScaffold a bridge in Python, TypeScript or Go
bridge runRun the official Yamcs or Lattice bridge
verifyVerify a release folder's checksums and signature
versionPrint the version
helpPrint the command list

Flags go before or after positional arguments, except for conformance, whose flags go before --.

login​

constellation login [--key KEY] [--url URL]

Asks for the key when --key is not given, calls GET /account/state with it, and stores it only if the API accepts it. The stored key is bound to the API it was stored for: it is only ever sent to that origin. When CONSTELLATION_API_URL points at another API, whoami, results tail and bridge run refuse and say so, unless CONSTELLATION_API_KEY gives a key for that run; run constellation login --url for the other API instead. The CLI never sends a key over plain http except to localhost.

FlagDefaultMeaning
--keyPromptedAn API key from the Keys page
--urlhttps://api.constellation.spaceThe API, such as your enterprise API

whoami​

constellation whoami

Prints the API URL, account id, account type and plan of the key in use.

results tail​

constellation results tail [--json] [--once] [--after CURSOR | --from-start] [--consumer NAME] [--every 15s]

Prints each result as it arrives, from the newest run on, following the cursor: run, workflow, item id, action state, target time and action. A plain forecast shows the state forecast.

FlagDefaultMeaning
--jsonOffOne JSON object per item: cursor, run_id, workflow, item
--onceOffStop once caught up. Any failure ends it with exit code 1
--afterThe newest runStart after this cursor
--from-startOffStart at the oldest run the API still holds
--consumerNoneRead as this connection: only its outputs. The API lists it as a reader.
--every15sHow often to poll once caught up

A refused key or plan stops it with why. Without --once, any other failure is printed and retried.

mock​

constellation mock [--port 7070] [--scenario demo]

Serves the workflow results endpoints on 127.0.0.1 with the same paths, query parameters, cursor semantics and JSON as the API. The endpoints keep their original name, /predictions/feed:

EndpointQuery
GET /predictions/feedafter, limit, consumer, page_records; or cursor and page for the rest of a paged run
POST /predictions/feed/checkin
POST /predictions/feed/deliveries
GET /account/state

It accepts an x-api-key header and does not require one. The demo scenario, the only one, replays the demo fleet with forecast passes, a run in an item shape newer than bridges read, and rain-fade swap runs with an action in every state: advice, pending, approved, rejected and an unknown status. Point a bridge at it with CONSTELLATION_API_URL=http://127.0.0.1:7070.

FlagDefaultMeaning
--port7070The port on 127.0.0.1
--scenariodemoThe scenario to replay

conformance​

constellation conformance [--json] [--port N] [--timeout 60s] [--settings JSON] -- <bridge command...>

Runs the bridge command against its own mock API, kills it once it has caught up, publishes more runs, starts it again, and judges what it asked the API, what it reported and what it wrote to the conformance log. The checks and the log format are in Build a connector.

FlagDefaultMeaning
--jsonOffPrint the result as JSON: {"passed": true, "checks": [{"name", "ok", "detail"}]}
--portA free portThe mock's port on 127.0.0.1
--timeout60sHow long each of the two runs has to catch up with the results
--settingsThe manifest's defaultsJSON settings the mock sends instead, such as '{"min_p10_gb": 5}'

The bridge's output goes to standard error, the result to standard output. The bridge runs with:

VariableValue
CONSTELLATION_API_URLThe mock
CONSTELLATION_API_KEYconformance-key
CURSOR_FILEA file in a temporary folder, kept across the restart
POLL_SECONDS1
CONSTELLATION_CONFORMANCE_LOGA file in the same folder
Exit codeMeaning
0Every check passed: conformant
1A check failed
2It could not run: no command, a bad flag, a taken port, or a command that does not start

bridge new​

constellation bridge new NAME --lang python|ts|go [--dir DIR]

Writes a working bridge into a new folder: the bridge with apply() and act(), connector.json, a test, a Dockerfile and a README.md. NAME is a lowercase slug (letters, digits and -, at most 63 characters) and becomes the connector's name. It refuses a folder that already exists.

FlagDefaultMeaning
--langRequiredpython, ts or go
--dir./NAMEThe folder to write

bridge run​

constellation bridge run yamcs|lattice

Runs an official bridge from the constellation-space Python package, as python3 -m constellation_space.bridges.yamcs or .lattice, with the API URL and key from your environment or login. Every other variable, such as YAMCS_URL, passes through. Install the package with its extra first (see SDKs); the command says so when it is missing. PYTHON picks the interpreter (default python3). The bridge's exit code is passed on.

verify​

constellation verify DIR

Checks with cosign that SHA256SUMS in DIR was signed keyless by the release workflow of constellationhq/connectors for a vX.Y.Z tag, with the signature (SHA256SUMS.sigstore.json) in the public transparency log, then checks every file it lists that is in DIR. A listed file you did not download is noted, not failed; at least one must be there. It refuses, and verifies nothing, when cosign is not installed or the release is not signed. See Downloads.

Environment variables​

VariableDefaultRead by
CONSTELLATION_API_URLhttps://api.constellation.spaceEvery command that calls the API, and every bridge. Overrides what login stored; the stored key is not sent to another origin.
CONSTELLATION_API_KEYNoneSent as x-api-key. Overrides what login stored. Bridges need a key with predictions:read.
CURSOR_FILEcursor.txtBridges: where the last applied cursor is kept. The actions carried out are kept beside it, in CURSOR_FILE.acted.
POLL_SECONDS15Bridges: how often to poll once caught up
BACKFILLUnsetSDK Bridge classes and Go results.NewBridge: 1 makes a first start apply the whole history the API holds instead of starting at the newest run. The Yamcs, Lattice and COSMOS bridges always start at the newest run
CONSTELLATION_CONFORMANCE_LOGUnsetBridges: the file to append the conformance log to. Conformance sets it.
PYTHONpython3bridge run: the Python interpreter

Config file​

constellation login writes the API URL and key to constellation/config.json in your user config folder, readable only by you (mode 0600):

SystemPath
Linux$XDG_CONFIG_HOME/constellation/config.json, or ~/.config/constellation/config.json
macOS~/Library/Application Support/constellation/config.json
{
"url": "https://api.constellation.space",
"key": "..."
}

The environment variables override it, and the key is sent only to the url beside it. Delete the file to log out.

Exit codes​

0 success, 1 a failure (the message says why), 2 a usage mistake or, for conformance, a check that could not run. bridge run exits with the bridge's own code.