CLI reference
This page documents the CLI at the release commit. The Homebrew package built
from that commit ships it. Run space COMMAND --help=plain to print the help
for one command.
Commands
| Command | Description |
|---|---|
space init [--dir=DIR] [OPTION]… TEMPLATE | Start a new project from a template. |
space build [OPTION]… [SOURCE] | Build your application into a signed image. |
space run [OPTION]… [IMAGE] | Run an image locally, or start it as a named service. |
space stop [OPTION]… NAME | Stop a workload instance. |
space publish [OPTION]… IMAGE… | Publish your application to the marketplace. |
space deploy [OPTION]… IMAGE | Ship a signed release to a satellite or a node. |
space verify --anchor=KEY.pem [--color=WHEN] [OPTION]… IMAGE | Check a delivered image against the evidence it carries. |
space sbom [OPTION]… [FILE] | List everything that went into a build. |
space status [--color=WHEN] [OPTION]… [NAME] | Show what is running and the stage each deploy has reached. |
space logs [OPTION]… [SOURCE] | Show the logs from your running application. |
space image COMMAND … | List, pull, and push images. |
space target COMMAND … | Connect and manage the machines you deploy to. |
space context COMMAND … | Choose where your commands go, and sign in there. |
space keys COMMAND … | Manage the keys that sign your builds. |
space init
Synopsis: space init [--dir=DIR] [OPTION]… TEMPLATE.
Scaffolds the named template’s bundled release snapshot into DIR, creating it if it is missing. A short name resolves in the parsimoni-labs namespace, so space init hello-world selects parsimoni-labs/hello-world. The template writes a minimal Dockerfile service, build.yaml, run.yaml, a short README, and a .gitignore covering what space build writes. Run space build and space run inside the new directory.
Omitted, —dir is the template basename: hello-world for parsimoni-labs/hello-world.
The scaffolded relay authenticates every frame and draws its SDLS association key afresh on every run, so no key is ever typed and none is written down. There is no unauthenticated posture to select.
init overwrites no existing file.
| Argument | Description |
|---|---|
TEMPLATE (required) | Template name, for example hello-world or parsimoni-labs/hello-world. |
| Option | Description |
|---|---|
--dir=DIR | Directory to scaffold into, created if missing. Defaults to the template basename. |
space init also accepts the common options listed below.
space build
Synopsis: space build [OPTION]… [SOURCE].
Build an OCI app image from a Dockerfile, or assemble a SpaceOS system image (initramfs + GPT disk via uniboot).
Dockerfile (Docker shape): space build -f Dockerfile -t name —project-root DIR. -f/—file selects the recipe, -t/—tag names the image space run resolves, and —project-root is the directory shared with the builder as the COPY root. space build path/to/Dockerfile is shorthand: the Dockerfile’s directory becomes the project root and its basename the tag.
System image: a local YAML config file or an OCI image reference as the positional argument; if omitted, build.yml or build.yaml must exist. OCI system images are read from the local SpaceOS system-image cache first and downloaded on a cache miss.
space build composes the logical system once, for any target. —signing-profile selects a named build signing identity; omitted, the current development identity from space keys use is used and its fingerprint is printed. Release-looking tags such as :release and :prod require an explicit —signing-profile or —signing-key. Every build signs. The board, device tree, and secure-boot key belong to the deploy target, so the per-board bootable image (kernel + initramfs + DTB + signed boot.img) is assembled by space deploy for the named target, keyed by (composition, board). See space deploy —help.
space build —plan (alias —dry-run) prints the build dependency graph and exits without building. Each content-addressed derivation (the Linux payloads, each app image, each partition disk) is shown with its key and whether it is already in the local build cache, with the cached artifact’s digest and size, or would be built. A node keyed on a dependency’s built output is shown deferred; its key resolves while that dependency is built.
Every build appends to the host build record: one provenance row per completed build, giving tag, image digest, source, completion time, status, and signing identity fingerprint. Failures are recorded too; a failed build carries no digest and records the failure cause.
| Argument | Description |
|---|---|
SOURCE | With -f/—file, the optional project root shared with the builder (the COPY root). Without it, the build config source: a Dockerfile, a local YAML file, or an OCI index reference. Defaults to build.yml or build.yaml. |
| Option | Description |
|---|---|
--color=WHEN (absent=auto) | Colorize the output. WHEN must be one of auto, always or never. |
--display=MODE (absent=auto) | Select display rendering. Defaults to auto, a live TTY display on terminals. tty forces it. raw disables cursor-control redraws and emits append-only output. |
-f FILE, --file=FILE | Dockerfile recipe to build. The positional argument is then the build project root (the COPY root), defaulting to the Dockerfile’s own directory. |
--issuer=KEY.pem | PEM public key of the publisher to pin for a published IMAGE, replacing whatever this target has recorded. A target with no publisher recorded resolves one from the signing identity this machine has selected and records it beside the target manifest. This flag is needed only for a deliberate re-pin: the publisher rotates its key, or the image comes from somewhere the recorded key does not answer for. |
-k KERNEL, --kernel=KERNEL | Kernel image to boot instead of the one the product supplies: a local file path or an OCI reference. Overrides the config file. |
--keystore=POSTURE | Secret-keystore posture baked into the measured launch plan: dev boots space-secret on the plaintext development keystore, sealed requires a platform-sealed KEK source at boot. Defaults to dev; a —release build defaults to sealed and rejects dev. |
-o DIR, --output=DIR | Output directory for build artifacts. Overrides the config file. |
--plan, --dry-run | Print the build dependency graph and exit without building. Each content-addressed derivation (the Linux payloads, each app image, each partition disk) is shown with its key and whether it is already in the local build cache (with the cached artifact’s digest and size) or would be built. —dry-run is an alias. |
--profile | Record system-image build profiling metrics and write a Prometheus text exposition next to the build manifest. |
--profile-metrics=PATH | Write build profiling metrics to this Prometheus text exposition path. Implies —profile. |
--project-root=DIR | Project root shared with the builder. A Dockerfile build uses it as the COPY root, and defaults to the Dockerfile’s directory. An app build uses it as the staged source tree, and defaults to the app.yaml’s directory. A system-image build resolves local Dockerfile services under it, uses it as their COPY root, and crunches its files into every partition’s boot initramfs. |
--release | Build a production release. It bakes the sealed secret-keystore posture into the measured launch plan and requires an explicit, non-development signing identity (—signing-profile, or —signing-key-ed25519 and —signing-key-mldsa65). A release-looking tag (:release, :prod) without this flag is refused. |
--rollback-index=N (absent=0) | Anti-rollback index published by this signing act. It is stamped into every capability the build mints and into the launch-trust bundle, and a node refuses a launch whose index is below the highest it has already admitted. Advance it on a release that must supersede its predecessor. It is a deliberate counter, so rebuilding the same commit publishes the same index and the same bytes. Defaults to 0, the development domain. A —release build requires 1 or more. |
--signing-key-ed25519=PEM | PEM file holding the classical (Ed25519) half of the release identity that signs the OCI service manifests recorded in the SpaceOS build index. It is the artifact provenance key runner admission checks. It is not the board secure-boot key of space target and space deploy. The post-quantum half is named by —signing-key-mldsa65 and is never looked for beside this file. |
--signing-key-mldsa65=PEM | PEM file holding the post-quantum (ML-DSA-65) half of the release identity. Required with —signing-key-ed25519 and named separately, so the two halves can be held under separate custody. |
--signing-profile=NAME | Named signing identity from space keys. Defaults to the current development identity, and names one that does not exist yet into being. —release requires it or the two —signing-key-* flags, refuses the development identity, and refuses to create the one it is given. |
-t NAME, --tag=NAME | Name for the produced image. A Dockerfile build uses it as the name space run resolves, and defaults to the project-root basename. An app build uses it as the app name. A system-image build registers it in the local OCI store for space run and space image push, and defaults to a generated build id. |
--uefi-disk[=STUB] (default=) | Also assemble a UEFI host disk beside each partition disk. STUB may be a local stub file, a directory containing a platform stub, or an OCI image reference. With no STUB, use uniboot’s digest-pinned default systemd-boot stub. |
--vm-type=TYPE (absent SPACE_VM_TYPE env) | VM backend for VM launches, vz (Apple Virtualization.framework, macOS) or qemu. Defaults to vz where the framework is available, qemu otherwise. |
space build also accepts the observability options
and the common options listed below.
space run
Synopsis: space run [OPTION]… [IMAGE].
space run IMAGE boots IMAGE through the local SpaceOS VM path. Use it on hosts such as macOS, where the Linux runtime runs inside the VM.
space run IMAGE —runtime run.yaml boots IMAGE with runtime constraints from run.yaml: placement, memory, CPU pinning, bridges, and the isolation choices not fixed at build time.
space run —name NAME IMAGE starts a signed, supervised instance when IMAGE produces a staged Solo5 or host-style launch. A runc service runs only from a baked SpaceOS image partition; boot it with space run IMAGE, or deliver a release with space deploy (—bench for the co-located runner).
| Argument | Description |
|---|---|
IMAGE | An OCI image reference or SpaceOS build id/reference. Runtime topology is passed with —runtime. |
| Option | Description |
|---|---|
--bootstrap=FILE | Private bootstrap document to hand the guest, as a provider would. It is attached as a raw config drive and selected on the kernel command line, so the composition itself names no provider and the image booted here is the image space target apply ships. Without it a local node fetches nothing and its workloads start without credentials. |
--color=WHEN (absent=auto) | Colorize the output. WHEN must be one of auto, always or never. |
--context=NAME | Context whose runner —name starts the workload on. Required when the selected context is remote, so an earlier space context use cannot silently decide that a workload starts on a flight computer instead of this machine. The local context needs no flag. |
--deploy-forward=PORT | Open a host->guest CLA forward for a deployed node. It listens on 127.0.0.1:PORT, a ground’s TCPCL drain target, and bridges each connection to the booted node’s in-VM deploy receiver over vsock. Requires —node and the Virtualization.framework backend. |
--dev-inject | Open the development injection channel on the node this boots. The node then accepts a freshly built spacebox pushed over that channel, verifies it against the trust anchors baked into its measured rootfs, installs it outside the measured image and restarts its daemons out of it, so a system-daemon change costs a dune build instead of a payload rebuild and a boot. The push is signed like a release and refused by name if this node does not pin the signing identity. Needs the Virtualization.framework launcher, and is refused by name under any other. |
--display=MODE (absent=auto) | Select display rendering. Defaults to auto, a live TTY display on terminals. tty forces it. raw disables cursor-control redraws and emits append-only output. |
--headless | Run without the interactive boot display. Applies to the local VM boot form. |
--isolation=BACKEND | Override the isolation backend for —name: one of auto, runc, spt, hvt, firecracker, qemu or host. Defaults to the image’s classified backend (a unikernel image runs under its solo5 tender). |
-k KERNEL, --kernel=KERNEL | Kernel image to boot instead of the one the product supplies: a local file path or an OCI reference. Overrides the config file. |
--name=NAME | Register IMAGE as a named, supervised instance on the current context’s runner. space run signs a one-service composition and deploys its staged Solo5 or host-style launch. Address it later by NAME with space status and space logs. A runc service runs only from a baked image partition; use space run IMAGE for the local VM form. |
--node=NODE | Boot the named persistent node. Its writable disk is materialized once under the build output’s nodes/NODE directory on first boot and booted in place on every later run, so guest writes survive a restart. Without this flag each run boots a fresh disposable copy of the built disk. Remove the node directory to reprovision. |
-o DIR, --output=DIR | Output directory for build artifacts. Overrides the config file. |
-p HOST:GUEST, --publish=HOST:GUEST | Publish a guest port on the host as HOST:GUEST. Repeatable. Forwarded through the VM’s user networking on both backends (QEMU’s own hostfwd, and the slirp gateway that drives the Virtualization.framework network attachment), so curl http://localhost:HOST reaches the guest. A host port already in use is refused by name before the VM starts, including one held only on 127.0.0.1, which a wildcard bind would otherwise shadow. |
--plan, --dry-run | Resolve the image/build id and runtime constraints, print the local boot plan, then exit without starting it. |
--profile=PROFILE | Resolve the local run against the named target profile, an operator’s own document winning over the packaged catalog. It must be a host-VMM profile: space run direct-boots a kernel, so a profile whose first stage is UEFI firmware or a board ROM is refused, and space deploy is the verb for it. Defaults to the profile describing this host. |
--progress=MODE (absent=auto) | Select the local boot progress renderer. Defaults to auto. —name instances report progress through space status and space logs. |
--runtime=FILE | Runtime constraints/topology file applied to IMAGE: partitions, memory, relay, ground, and platform specialization. Usually run.yaml. |
-t SECONDS, --timeout=SECONDS | Auto-shutdown after SECONDS seconds. Defaults to no timeout. |
--vm-type=TYPE (absent SPACE_VM_TYPE env) | VM backend for VM launches, vz (Apple Virtualization.framework, macOS) or qemu. Defaults to vz where the framework is available, qemu otherwise. |
--volume=NAME | Bind project volume NAME into the —name instance. Repeatable. |
space run also accepts the observability options
and the common options listed below.
space run exits with a status of its own as well as the shared ones.
| Status | Condition |
|---|---|
0 | on success. |
1 | A VM crashed or the headless run did not shut down cleanly. |
123 | on indiscriminate errors reported on standard error. |
124 | on command line parsing errors. |
125 | on unexpected internal errors (bugs). |
space stop
Synopsis: space stop [OPTION]… NAME.
Asks the space-runner daemon over its control socket to stop the named workload instance, starting the runner on demand if nothing is listening.
| Argument | Description |
|---|---|
NAME (required) | Workload instance name. |
space stop also accepts the common options listed below.
space publish
Synopsis: space publish [OPTION]… IMAGE….
Validates the application manifest locally, assembles the signed launch material for the declared architecture from that image’s signed build, uploads the blobs it names, and asks the selected hosted context to mint one immutable marketplace revision pinned to it. space build then space publish is the whole chain: nothing has to have been deployed first. This command does not push an OCI image, start a workload, or make a qualification claim. Human-issued qualification assertions are attached separately to immutable artifacts.
| Argument | Description |
|---|---|
IMAGE (required) | Image to publish, as ARCH=REF or a bare REF taking the architecture the manifest declares. Repeat once per architecture; the declared one must be among them, because the revision’s launch material is assembled from its signed build. |
| Option | Description |
|---|---|
--category=CATEGORY | Catalogue category. |
--color=WHEN (absent=auto) | Colorize the output. WHEN must be one of auto, always or never. |
--description=TEXT | Full catalogue description. |
--manifest=FILE (required) | Application manifest JSON. Declares the supported target profile and architecture, runtime isolation, input and result schemas, execution limits, cancellation policy, and support owner. |
--name=NAME | Listing name. Defaults to the hosted project name when omitted. |
--plan, --dry-run | Validate the application manifest and the image bindings, then print the publication plan without building, reading credentials, or writing remote state. |
--price-usd-c=CENTS (absent=0) | Price in integer USD cents. Defaults to 0; negative prices are refused. |
--short-description=TEXT | One-line catalogue summary. |
--tag=TAG | Catalogue tag. Repeat for more than one tag. |
space publish also accepts the observability
options and the common options
listed below.
space deploy
Synopsis: space deploy [OPTION]… IMAGE.
space deploy IMAGE —target TARGET ships a durable signed release to a connected cloud node, edge computer, or satellite. space run launches a workload instance; space image push publishes a composition to a registry or staging service. The target profile and transport carry the platform differences.
The composition is target-agnostic. Deploy resolves its signed system partition, then the target profile selects the native assembly. A CM5 gets its board kernel, initramfs, DTB and signed boot image. Hosted macOS-VMM and Scaleway nodes receive the system release under their VMM or UEFI boot boundary. Board-specific inputs come from the connected target; —board, —signing-key, —dtb and —kernel override them for bring-up and recovery.
A real deploy goes through the selected context’s ground service and requires a target with a connected transport (—endpoint/—cla-address). A transport-less target is refused. —bench delivers to the co-located runner for bench testing.
—plan assembles and validates the target release, prints the signed release descriptor, and writes no target state. An operator can inspect, archive, and approve the release before activation.
Deploy is asynchronous and durable. It enqueues a deploy record, returns a deploy id, and advances that record across contact windows. space status ID renders the deploy checklist; bare space status reports runtime state after activation. The deploy phases are published, approved, queued, uplinking, installed, activated, with rejected and failed as terminal outcomes. They are not the runtime control state space status lists.
| Argument | Description |
|---|---|
IMAGE (required) | Published composition or artifact reference to deploy. |
| Option | Description |
|---|---|
--area=BOX | Region to image, as WEST,SOUTH,EAST,NORTH in degrees, spelled —area=BOX so a negative edge does not read as another option. Overrides the acquisition.area the placement file declares. A place name is the portal’s affordance: this path is the scripted one, and a script names the box it means. |
--at=TIME | RFC 3339 instant the work should run at. |
--bench | Deliver to the co-located runner for bench testing. Without it, a deploy uplinks through the context’s ground service and requires a target with a connected transport (—endpoint/—cla-address). |
--board=BOARD | Assert the target profile’s published platform board identifier. The resolved profile’s boot mechanism selects the assembly. |
--color=WHEN (absent=auto) | Colorize the output. WHEN must be one of auto, always or never. |
--display=MODE (absent=auto) | Select display rendering. Defaults to auto, a live TTY display on terminals. tty forces it. raw disables cursor-control redraws and emits append-only output. |
--dtb=DTB | Pin this device-tree blob into the per-board boot image, under verified boot. Overrides the DTB connected for the target with space target connect. With neither, the board firmware supplies the stock device tree. |
--from=TIME | RFC 3339 instant to look from, overriding acquisition.from. Defaults to now. |
--hours=HOURS | How many hours of window to look over, overriding acquisition.hours. Defaults to a day. |
--idempotency-key=KEY | Idempotency key. The same key from this account is the same order, so a retried command reaches the order the first one placed. Omitted, the server derives one from the request itself, which is what a refreshed checkout page gets. |
--input=DIGEST | Content digest of an uploaded input object. Repeat once per object. |
--issuer=KEY.pem | PEM public key of the publisher to pin for a published IMAGE, replacing whatever this target has recorded. A target with no publisher recorded resolves one from the signing identity this machine has selected and records it beside the target manifest. This flag is needed only for a deliberate re-pin: the publisher rotates its key, or the image comes from somewhere the recorded key does not answer for. |
--kernel=KERNEL | Board kernel image (path or OCI ref) for the per-board boot image. Overrides the kernel connected for the target with space target connect. The composition kernel is target-agnostic and is not used for the board image. |
--parameter=NAME=VALUE | Execution parameter, as NAME=VALUE, validated against the app revision’s input contract. Repeat once per parameter. |
--pay | Authorise the non-zero total the plan prints. Separate from —yes deliberately: a caller who automated away the confirmation has not thereby agreed to a price, and money is never a side effect of a flag that means stop asking me. |
--pick=PASS | The pass to acquire, as the portal’s pass list spells it. Omitted, the plan takes the soonest pass the region has, because asking without picking means as soon as it can be imaged. |
--plan, --dry-run | Assemble the target release and print its signed descriptor. Writes no target state and ships nothing. |
--quote=DIGEST | Place the order only if the plan prices this exact quote. DIGEST is the content address a previous —plan printed. A quote that has moved since it was read is refused: the order never lands at the new price, which is what binds a rehearsal to the run that follows it. |
--runtime=FILE | Placement file the acquisition is read from: the acquisition block’s region and window. Usually run.yaml, which is looked for beside the command when this is not given. |
--signing-key=PEM | RSA-2048 PEM private key for the target board’s native secure boot. It signs the per-board boot.img as boot.sig, the signature the Raspberry Pi firmware verifies. Overrides the key connected for the target with space target connect. |
--state-key=SOURCE | Source of the target’s 32-byte device key, which authenticates its boot-state record. One of otp:NVMEM (a fused one-time-programmable range the key is derived from), tpm:DEVICE:INDEX (a TPM NV data index), or a bare path to a file holding the raw key. The source, never the key, is stamped into the signed command line as uniboot.statekey. Overrides the source connected for the target with space target connect —state-key. With neither, the image boots without an authenticated boot-state record. |
--target=TARGET | Target to act on: a connected target name, a path to a target manifest, or a directory holding targets/. Defaults to the target declared in targets/NAME.yaml, else the only one connected to the current context. With more than one in scope the command fails and names them. |
-y, --yes | Place the order the plan describes without asking. This is how a machine says it has read a plan; it is not authority to spend, so a non-zero total still needs —pay. |
space deploy also accepts the observability
options and the common options
listed below.
space verify
Synopsis: space verify --anchor=KEY.pem [--color=WHEN] [OPTION]… IMAGE.
Walk the consumer evidence chain of a delivered SpaceOS build index and report the publisher it verifies under, or name the link that fails. The chain is the one space run and space target apply walk before they act on an index: the index’s build.sbom and build.provenance annotations are digests naming present bytes; those bytes hash back to them and parse as in-toto statements; a detached SCITT Signed Statement over each verifies under —anchor; and both statements name exactly the partitions the index publishes. A failure names which of those links did not hold and exits non-zero.
| Argument | Description |
|---|---|
IMAGE (required) | Delivered image to re-check, an OCI reference already in the local store (pull it with space image pull first). |
| Option | Description |
|---|---|
--anchor=KEY.pem (required) | PEM public key of the publisher whose signature the evidence must carry, the same key space run and space target apply pin. The shared publisher resolver reads it. This command has no reader of its own. |
--color=WHEN (absent=auto) | Colorize the output. WHEN must be one of auto, always or never. |
space verify also accepts the observability
options and the common options
listed below.
space sbom
Synopsis: space sbom [OPTION]… [FILE].
Lists everything a build contains and prints it as a software bill of materials. The list comes from the build config, so space sbom answers before the build runs and describes what that config will produce: the digest-pinned kernel, each partition’s init binary, the OCaml libraries this executable statically links, and the workspace opam closure the dune.lock names.
An OCI reference resolves to the SPDX document its attestation layers carry, and falls back to the config’s own metadata when the image carries none. —cache selects the local OCI cache those attestations are read from, and —lock the workspace lock the closure comes from. —lock none omits the closure, and an installed binary with no checkout around it omits it too.
The default output is a text report on stdout. —json prints SPDX JSON, —format cyclonedx prints CycloneDX JSON, and —output writes the JSON to a file. The creation timestamp comes from SOURCE_DATE_EPOCH and defaults to the Unix epoch, so the same config produces the same document.
—osv scans the same opam closure against the OSV.dev vulnerability database and prints that report in place of the SBOM.
| Argument | Description |
|---|---|
FILE | Build config file. Defaults to build.yml or build.yaml. |
| Option | Description |
|---|---|
--cache=DIR | OCI cache directory. Defaults to _build/space-builder/cache/oci. |
--color=WHEN (absent=auto) | Colorize the output. WHEN must be one of auto, always or never. |
--format=FORMAT (absent=spdx-json) | JSON SBOM format, spdx-json or cyclonedx (cyclonedx-json is an alias). Defaults to spdx-json. Any other format implies JSON output. |
--lock=DIR | Workspace dune.lock directory whose opam closure is enumerated into the SBOM. Defaults to the enclosing checkout’s dune.lock; pass none to omit the closure. |
-o FILE, --output=FILE | Write the JSON SBOM to FILE. Defaults to stdout. |
--osv | Scan the enumerated opam closure against the OSV.dev vulnerability database and print the report instead of the SBOM. |
space sbom also accepts the observability options
and the common options listed below.
space status
Synopsis: space status [--color=WHEN] [OPTION]… [NAME].
Shows the current SpaceOS runtime state: the workloads the runner is supervising, with their lifecycle state, isolation backend, and image digest. It is the terminal view of the web dashboard’s overview page.
Given a deploy id from space deploy, it renders that deploy’s pipeline checklist: published, approved, queued, uplinking, installed, activated, with rejected and failed as terminal outcomes. The runtime control state (running, backoff, exited, failed) is reported once a deploy is activated.
A NAME argument narrows the report to one workload instance, and the command exits non-zero if that instance is not running. The command shows every workload instance when NAME is absent.
—json prints the machine-readable form. It prints the whole runtime report when NAME is absent: workload state plus telemetry, SBOM, signature, downlink and result state, as canonical JSON against Space_schema.Report. A script or an e2e harness reads that report as its oracle. A NAME argument narrows it to the durable deploy record for a deploy id, or to the workload array for a workload instance.
The command queries the live runner through the current context. It reads and starts nothing: no daemon, no image, no VM, and no runtime state is mutated. The command says the runner is not connected and exits 0 on a machine with no local runner. The report form stamps “runner”:{“connected”:false}. SPACE_RUNNER_CONTROL overrides the local control endpoint.
| Argument | Description |
|---|---|
NAME | Show only the named workload instance. Defaults to all. |
| Option | Description |
|---|---|
--color=WHEN (absent=auto) | Colorize the output. WHEN must be one of auto, always or never. |
space status also accepts the observability
options and the common options
listed below.
space logs
Synopsis: space logs [OPTION]… [SOURCE].
Display SpaceOS workload logs. A standalone space-logs collector is read directly when it is configured (SPACE_LOGS_CONTROL, then SPACE_LOGS_SOCKET) and reachable. Otherwise the logs come from the local engine’s in-process collector over the runner control socket, the same path space status reads. It starts no collector and no runner: with neither listening it says so and exits non-zero.
| Argument | Description |
|---|---|
SOURCE | Log source to show. Omitted, show all sources. |
| Option | Description |
|---|---|
--color=WHEN (absent=auto) | Colorize the output. WHEN must be one of auto, always or never. |
-f, --follow | Keep printing new lines as they arrive. |
-n N, --tail=N | Show the last N lines. |
--since=TIME | Show entries since TIME (ISO 8601 timestamp or Unix epoch seconds). |
space logs also accepts the observability options
and the common options listed below.
space image
Synopsis: space image COMMAND ….
Lists the OCI images the runner resolves space run NAME against, queried from the live space-runner over its control socket. It starts no runner: with none listening it says so and exits 0. The store lives where the runner runs, and the current context selects the runner, so the listing is that context’s. It never comes from the client’s filesystem. The columns are what the store knows: repository, tag, manifest digest, platform, and size. The isolation a workload instance ran an image under, and its running time, are in space status.
space image push sends a built image the other way, to the registry its reference names.
| Subcommand | Description |
|---|---|
space image ls [--color=WHEN] [OPTION]… | List images in the runner’s OCI store. |
space image pull [OPTION]… IMAGE | Pull an image into the local OCI store. |
space image push [OPTION]… IMAGE | Publish a built image to a registry. |
Run space image SUBCOMMAND --help=plain for a subcommand’s options.
space image also accepts the common options listed below.
space target
Synopsis: space target COMMAND ….
A target is a deploy node bound to an exact content-addressed target profile. The profile declares its platform board and boot mechanism. The target registry carries only per-device material: keys, kernel/DTB overrides, transport. —board asserts the board the profile declares. If —signing-key is omitted, space target connect generates a local bring-up key when the profile requests a native-board signer.
When targets/NAME.yaml or targets/NAME.yml exists, space target connect NAME reads its profile and connection settings from that file. Explicit flags override file values.
space target catalog sync clones or updates the public parsimoni-labs/targets profile catalog in Space’s managed cache. A project’s own profiles/ directory takes precedence.
A remote node also binds its uplink transport here. —endpoint is the bundle endpoint ID (RFC 9171) its releases are addressed to, —cla-address the TCP convergence-layer (RFC 9174) listener the ground daemon connects to, and —contact-start/—contact-stop/—contact-rate an optional contact window gating the transfer. With no transport fields the target is the local default: the co-located runner, reached over the control socket.
| Subcommand | Description |
|---|---|
space target apply [OPTION]… [NAME] | Reconcile a target’s provider resources and connect it. |
space target auth COMMAND … | Manage target-scoped provider authentication in the system keyring. |
space target catalog COMMAND … | Manage the public target-profile catalog. |
space target connect [OPTION]… NAME | Connect or update an existing deploy target. |
space target console [--color=WHEN] [--duration=SECONDS] [--target=TARGET] [OPTION]… | Stream a provisioned target’s serial console. |
space target inventory COMMAND … | Manage authenticated node inventory. |
space target logs [--color=WHEN] [--tail=N] [--target=TARGET] [OPTION]… [SERVICE] | Read a deployed target’s collected service logs. |
space target ls [--color=WHEN] [OPTION]… | List the targets connected to the current context, marking the one a command with no —target acts on. |
space target node COMMAND … | Manage the SpaceOS daemon set on an OS SpaceOS does not boot. |
space target restart [OPTION]… | Power-cycle a provisioned target and watch it boot. |
space target rm [--color=WHEN] [OPTION]… NAME | Remove a deploy target. |
space target secret COMMAND … | Inspect and rotate a target’s managed secrets. |
space target show [--color=WHEN] [OPTION]… [NAME] | Show one deploy target: its record and its provider state. |
Run space target SUBCOMMAND --help=plain for a subcommand’s options.
space target also accepts the common options listed
below.
space context
Synopsis: space context COMMAND ….
A context is a named binding of the registry, scheduler, and ground-service endpoints the CLI talks to. The current context decides where commands such as space run go. The built-in local context (the on-host runner) is always available; other contexts are stored under the XDG config directory.
A context that names a hosted endpoint needs a credential before it answers: space context login obtains one and stores it beside the context it belongs to.
| Subcommand | Description |
|---|---|
space context create [OPTION]… NAME | Create or replace a named context. |
space context login [--color=WHEN] [--flow=FLOW] [--token=TOKEN] [OPTION]… CONTEXT | Sign in to a hosted context with OIDC. |
space context ls [--color=WHEN] [OPTION]… | List contexts and mark the current one. |
space context show [--color=WHEN] [OPTION]… NAME | Show a context’s endpoints and whether a credential is stored. |
space context use [--color=WHEN] [OPTION]… NAME | Switch the current context. |
Run space context SUBCOMMAND --help=plain for a subcommand’s options.
space context also accepts the common options listed
below.
space keys
Synopsis: space keys COMMAND ….
A signing identity names the artifact provenance key space build signs with. space keys use selects the one development builds default to. A —release build requires an explicit —signing-profile or —signing-key.
space keys ls shows each identity’s name, key fingerprint, and key path, marking the current default. Pass —json for the machine-readable projection: full fingerprints, key paths, and a current flag.
| Subcommand | Description |
|---|---|
space keys generate [--color=WHEN] [--replace] [OPTION]… NAME | Generate a local release signing identity (Ed25519 + ML-DSA-65). |
space keys ls [--color=WHEN] [OPTION]… | List configured signing identities. |
space keys public [--color=WHEN] [OPTION]… NAME | Print a signing identity’s public key PEM. |
space keys rekey [OPTION]… | Wrap fresh SDLS session keys to a node’s ML-KEM key (ground side). |
space keys use [--color=WHEN] [OPTION]… NAME | Select the default signing identity for development builds. |
Run space keys SUBCOMMAND --help=plain for a subcommand’s options.
space keys also accepts the common options listed below.
Observability options
space build, space run, space publish, space deploy, space verify,
space sbom, space status and space logs accept these options.
| Option | Description |
|---|---|
--json | Enable JSON mode. By default logs are emitted with json-logs; commands that produce their own JSON may pass a custom reporter to keep stdout reserved for command output. |
--log=SPEC (absent SPACE_LOG env) | Set log level and per-source overrides. Format: LEVEL[,SRC:LEVEL,…]. Examples: debug, info,tls.tracing:warning, conpool:debug. Source names match exactly or by dot-separated prefix. Levels: error, warning, info, debug. |
--log-tag=TAG | Add a base tag to JSON log output. Can be repeated. Format: KEY=VALUE. Tags are attached to every JSON log record. Example: —log-tag env=prod —log-tag region=us-east-1. |
--no-color (absent NO_COLOR env) | Disable ANSI colour. |
-q, --quiet | Suppress non-error log records. This still allows explicit application output written by the command itself. |
--trace=FILE | Write log records from sources whose name ends in .tracing to FILE. This is the old logs-side protocol trace stream: useful for verbose hexdumps and parser state logs. It is not a memtrace allocation trace and not an ocaml-probe Runtime_events capture. |
-v, --verbose | Increase log verbosity. Use once for info, twice for debug, and three times to also enable log sources whose name ends in .tracing. |
Common options
Every command accepts these options.
| Option | Description |
|---|---|
--help[=FMT] (default=auto) | Show this help in format FMT. The value FMT must be one of auto, pager, groff or plain. With auto, the format is pager or plain whenever the TERM env var is dumb or undefined. |
--version | Show version information. |
Exit status
Every command exits with one of these statuses, and a command that adds one of its own says so in its own section above.
| Status | Condition |
|---|---|
0 | on success. |
123 | on indiscriminate errors reported on standard error. |
124 | on command line parsing errors. |
125 | on unexpected internal errors (bugs). |
