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.
| Command | What it does |
|---|---|
login | Store an API key and check it |
whoami | Show the account the key belongs to |
results tail | Print workflow results as they arrive |
mock | Serve the results endpoints with the demo scenario |
conformance | Check a bridge against the mock API |
bridge new | Scaffold a bridge in Python, TypeScript or Go |
bridge run | Run the official Yamcs or Lattice bridge |
verify | Verify a release folder's checksums and signature |
version | Print the version |
help | Print 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.
| Flag | Default | Meaning |
|---|---|---|
--key | Prompted | An API key from the Keys page |
--url | https://api.constellation.space | The 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.
| Flag | Default | Meaning |
|---|---|---|
--json | Off | One JSON object per item: cursor, run_id, workflow, item |
--once | Off | Stop once caught up. Any failure ends it with exit code 1 |
--after | The newest run | Start after this cursor |
--from-start | Off | Start at the oldest run the API still holds |
--consumer | None | Read as this connection: only its outputs. The API lists it as a reader. |
--every | 15s | How 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:
| Endpoint | Query |
|---|---|
GET /predictions/feed | after, 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.
| Flag | Default | Meaning |
|---|---|---|
--port | 7070 | The port on 127.0.0.1 |
--scenario | demo | The 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.
| Flag | Default | Meaning |
|---|---|---|
--json | Off | Print the result as JSON: {"passed": true, "checks": [{"name", "ok", "detail"}]} |
--port | A free port | The mock's port on 127.0.0.1 |
--timeout | 60s | How long each of the two runs has to catch up with the results |
--settings | The manifest's defaults | JSON 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:
| Variable | Value |
|---|---|
CONSTELLATION_API_URL | The mock |
CONSTELLATION_API_KEY | conformance-key |
CURSOR_FILE | A file in a temporary folder, kept across the restart |
POLL_SECONDS | 1 |
CONSTELLATION_CONFORMANCE_LOG | A file in the same folder |
| Exit code | Meaning |
|---|---|
0 | Every check passed: conformant |
1 | A check failed |
2 | It 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.
| Flag | Default | Meaning |
|---|---|---|
--lang | Required | python, ts or go |
--dir | ./NAME | The 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
| Variable | Default | Read by |
|---|---|---|
CONSTELLATION_API_URL | https://api.constellation.space | Every command that calls the API, and every bridge. Overrides what login stored; the stored key is not sent to another origin. |
CONSTELLATION_API_KEY | None | Sent as x-api-key. Overrides what login stored. Bridges need a key with predictions:read. |
CURSOR_FILE | cursor.txt | Bridges: where the last applied cursor is kept. The actions carried out are kept beside it, in CURSOR_FILE.acted. |
POLL_SECONDS | 15 | Bridges: how often to poll once caught up |
BACKFILL | Unset | SDK 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_LOG | Unset | Bridges: the file to append the conformance log to. Conformance sets it. |
PYTHON | python3 | bridge 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):
| System | Path |
|---|---|
| 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.