CLI reference

Space CLI is the build component of the Parsimoni Platform, and the space binary is the whole of it. It builds an application or system composition, runs it locally, operates the local engine, and assembles a signed release for a satellite or edge target. It can also provision a new target or connect an existing cloud, edge, or satellite resource to the platform.

You can scaffold, build, and run a project without a Parsimoni account:

space init parsimoni-labs/hello-world
cd hello-world
space build
space run

Contexts bind the same verbs to different backends. The built-in local context points at the on-host runner and runs its ground DTN node on the laptop. Hosted or partner contexts bind registry, scheduler, and ground endpoints together; sign in once with space login run.space and select the backend with space context use run.space. run.space operates the managed ground node for its context.

Example

Build and run a local workload:

space build . -t acme/payload:dev
space run acme/payload:dev --runtime run.yaml
space run --name payload-dev acme/payload:dev --runtime run.yaml
space ps
space logs payload-dev
space stop payload-dev

For satellite or edge activation, connect the target once, then deploy a signed release to it:

space target connect cm5-demo --profile cm5-dev \
  --signing-key keys/cm5-demo.pem \
  --endpoint ipn:7.1 --cla-address cm5-demo.local:4556 --always-reachable
space build . -t acme/payload:release --release --signing-profile release
space deploy acme/payload:release --target cm5-demo --plan
space deploy acme/payload:release --target cm5-demo
space status <deploy-id>

space run starts a workload. space target provision creates and connects a new target. space target connect adopts an existing resource. space deploy assembles and enqueues a signed release for a connected target.

Commands

Command	Description
`space init`	Scaffold a project from a template.
`space login`	Authenticate with a hosted context using OpenID Connect. Local runs do not require login.
`space context`	List, create, show, or switch backend contexts.
`space target`	Provision, connect, inspect, or remove deploy targets (`provision`, `connect`, `ls`, `show`, `rm`).
`space target provision NAME`	Plan or apply creation and connection of a new target. Dry-run is the default; `--apply` performs the printed plan.
`space target connect NAME`	Connect an existing cloud resource, edge computer, or satellite by recording its profile, identity, custody, and transport.
`space keys`	Manage build signing identities: `generate`, `use`, `list`, `public`. The first build creates a dev identity automatically.
`space cert`	Issue and inspect deployment certificates that give a project fixed resource limits.
`space build`	Build an OCI app image from a Dockerfile or assemble a target-agnostic signed system composition. `space build ls` lists the host build-provenance records.
`space builder`	Inspect or initialize builder appliances: `list`, `inspect`, `init`.
`space run IMAGE`	Boot an image through the local VM path. `--runtime run.yaml` applies memory, CPU, and isolation placement.
`space run --name NAME IMAGE`	Register and start a named workload under the runner of the current context.
`space deploy IMAGE --target TARGET`	Assemble and enqueue a signed per-board release for a connected target.
`space rollback`	Re-deliver a target’s prior activated release generation as a new authorized operation.
`space ps`	List runner-supervised deployments, starting the local runner on demand.
`space up` / `space down`	Start or stop the local SpaceOS engine explicitly. The engine starts on first use, so this is for pinning its lifetime, such as in CI.
`space status`	Show local runtime state, or the deploy-pipeline checklist when passed a deploy id.
`space report`	Print the machine-readable runtime report used by automation and the dashboard.
`space logs`	Query workload logs (`--tail`, `--follow`, `--since`).
`space stats`	Query workload metrics.
`space image ls` / `space images`	List images known to the runner’s OCI store.
`space volume`	List, create, or remove project storage volumes.
`space sbom`	Print SBOM data (SPDX 2.3 JSON or CycloneDX 1.6) from a build config.
`space push`	Publish a built image or composition to a registry without creating a deployment.
`space registry`	Serve the local OCI store as an OCI distribution registry (`--listen`, `--port`, `--mirror` for pull-through).
`space runner`	Manage this machine’s membership in hosted runner pools (`join`).
`space stop`	Stop a runner-supervised workload.

space bootstrap is maintainer-only and hidden from the default command group; it appears only when SPACE_MAINTAINER=1 is set.

Workloads, targets, and releases

Choose the command from the object you want to change:

Command	Object	Effect
`space run`	Workload instance	Boots locally or starts a named workload on the runner selected by the current context.
`space target provision`	New target	Creates or reconciles its substrate, boots it, and connects it to the selected context.
`space target connect`	Existing target resource	Adopts it by binding its profile, node identity, signing custody, and transport.
`space deploy`	Signed release operation	Resolves a connected target, assembles its release, and enqueues delivery and activation.

Provisioning converges initial bring-up and connection. Connecting starts at the same platform boundary when the cloud VM, edge computer, or satellite already exists. Deployment is the routine release path afterward. A connected cloud VM and a contact-gated satellite use the same deploy verb; their target profiles select different provisioners and their target records select different transports.

Provision a target

The target profile selects the provisioner. A cloud profile uses provider APIs to ensure the boot image, instance, storage, address, and firewall. A physical profile drives the board-specific image, installation, and enrollment path. Both finish with the target connected to the selected context.

A Scaleway profile can ensure a registry namespace, security group, data volume, routed IPv4 address, and VM. It never plans deletion or volume shrinking.

Run without --apply to inspect the plan:

space target provision edge-1 \
  --profile scaleway \
  --type <instance-type> \
  --volume-gib 20 \
  --tcp 443 \
  --registry edge-1 \
  --image <provider-image-id>

Every action that starts recurring charges is marked [billable]. Re-run the same command with --apply only after reviewing the plan.

--image <id> boots an image already registered with the provider.
--image-file <file.qcow2> uploads and imports a QCOW2 image. It requires --bucket <bucket> and --image-volume-gib <gib>, and excludes --image.
Omitting both image options plans the registry, firewall, volume, and IP but does not create the VM.
--zone <zone> overrides the zone from the provider profile.

Provider credentials are used only for provisioning. The provisioner records the platform identity and transport used by routine deploys.

Connect an existing target

Use space target connect when the resource already exists. A cloud VM, a board prepared at a bench, and a satellite in orbit all cross the same platform boundary:

space target connect sat-42 --profile cm5 \
  --signing-key keys/sat-42.pem \
  --endpoint ipn:42.1 --cla-address <host:port> \
  --tle <tle-file> --station <lat,lon,alt>

The profile defines what the computer is. The connection records which node it is, who may sign for it, and how releases reach it. Connecting never creates or alters the underlying cloud or physical resource.

Build forms

space build classifies its source:

Form	Meaning
`space build`	Load `build.yml` or `build.yaml` from the current directory and assemble a system composition.
`space build DIR`	Load `DIR/build.yml` or `DIR/build.yaml`.
`space build build.yaml`	Assemble the named system composition.
`space build app.yaml`	Build one app (`kind: mirage`, `unikraft`, or `oci`) in the builder VM and emit an OCI workload.
`space build -f Dockerfile -t NAME --project-root DIR`	Build an OCI app image from a Dockerfile, using `DIR` as the COPY root.
`space build path/to/Dockerfile`	Shorthand Dockerfile build. The Dockerfile directory becomes the project root.
`space build OCI-REF`	Resolve a published or cached system image.

Signing

Every build signs; there is no unsigned build:

The first space build creates a development identity, trusts it from then on, and prints its fingerprint. space keys manages identities explicitly.
The release boundary is the explicit --release flag. A --release build requires a non-development --signing-profile (or --signing-key) and builds an image whose keystore is sealed against the target’s hardware-backed key.
A release-looking tag (:release, :prod, :production) without --release is refused.
--keystore dev|sealed selects how the node stores keys; a --release build rejects dev.

The build signing identity signs launch trust and provenance. It is separate from the board secure-boot custody used by space target and space deploy.

Common flags

-f, --file FILE: Dockerfile recipe for an app-image build.
-t, --tag NAME: name the produced app image or system composition.
--project-root DIR: build context and staged source root.
--runtime FILE: runtime placement file for space run IMAGE.
--isolation BACKEND: override the service isolation backend for space run.
--volume, -v NAME: attach a named runner volume; repeat per volume.
--headless --timeout SECONDS: CI-friendly local boot. space run reserves exit code 1 for a VM crash or unclean headless shutdown.
--plan / --dry-run: preview a mutating verb without writing state. For space deploy, --plan assembles and validates the per-board release and prints the release descriptor.
--json: machine-readable output on read verbs such as space ps and space report.

space target connect binds the facts a deploy resolves:

--profile: the content-addressed target profile. Required.
--signing-key: boot-signing custody for this node.
--operator-ca, --deploy-cert: the operator certificate and repeatable project limit certificates embedded into a system-image release.
--dtb, --kernel: board facts, the device tree and board kernel.
--endpoint, --cla-address: the uplink transport. The endpoint is the node’s delay-tolerant network name (ipn:7.1); the convergence-layer adapter address is the host and port that carries bundles to it.
Exactly one reachability claim: --always-reachable for a bench node on the local network; --tle (a two-line element set describing the orbit) plus --station for a node reached over real passes; or --contact-start and --contact-stop for a single negotiated window.

A target that names no reachability is refused at deploy time.

Every refusal prints the command that resolves it:

space build: refusing to build a release-looking tag with the dev identity
pass --signing-profile release or --signing-key KEY