CLI Reference

🚧 The Passport Prime SDK is in public beta, currently 1.0.0-beta.1. Got an idea, or want a dev unit to play with? We'd love to hear from you, hello@foundation.xyz .

The foundation CLI is the single entrypoint for every developer workflow: scaffold, build, simulate, sideload, sign, and preview. Every command listed here is stable within the current major version.

Global behavior

SDK root discovery, The CLI resolves the SDK root by checking FOUNDATION_SDK_ROOT, then walking up from the working directory, then walking up from the executable path. This means the same foundation binary works inside the KeyOS-dev repo and inside an installed SDK bundle.
Project discovery, Commands that need a project (build, sim, sideload) walk upward from the working directory looking for app-config.toml.
Nix shell required, build, sim, and sideload expect to run inside foundation develop. If you're not in one, they'll prompt you.
User-scoped state, ~/.foundation/ holds the SDK install, shell rc files, and per-identity signing material.

Commands

`foundation new`

foundation new [name] [--template TEMPLATE] [--no-git]

Scaffold a new app from a template.

Prompts for friendly name, launcher name, description, publisher name, contact email, support URL, icon path, app ID, version, and minimum KeyOS version
Leave app ID blank to generate a random 128-bit hex ID prefixed with 0x
Writes app-config.toml, source files, and resources
Runs git init in the new directory (use --no-git to skip)

Available templates:

default-app, single-page starter (default)
multi-page-app, router-based multi-screen starter

`foundation develop`

foundation develop

Enter the SDK Nix shell. Every build, simulate, and sideload command should be run from inside this shell.

Requires nix
Uses your login shell (zsh or bash); isolates config via ZDOTDIR=~/.foundation for zsh or --rcfile ~/.foundation/.bashrc for bash
Exports FOUNDATION_SDK_ROOT and FOUNDATION_SDK_BIN, and prepends the packaged bin/ to PATH

`foundation exit`

foundation exit

Garbage-collect Nix state. Runs nix-collect-garbage -d and removes ~/.cache/nix. Best-effort, does not remove installed SDK bundles or signing identities.

`foundation build`

foundation build [--release]

Compile, strip, and sign a hardware-targeted KeyOS app bundle.

Requires: cargo, arm-none-eabi-strip, cosign2, and a usable cosign2.toml (either via cosign2-config in your app-config.toml or a configured signing identity under ~/.foundation/signing/).

Process:

Runs cargo build --target armv7a-unknown-xous-elf --package <app-name> [--release] with RUSTFLAGS="--cfg keyos -C relocation-model=pic -C link-arg=-pie"
Strips the binary into target/keyos/<app-name>/app.elf
Writes target/keyos/<app-name>/manifest.json with resolved permissions
Signs app.elf in place with cosign2

If multiple signing identities exist and none is selected via signing-identity or cosign2-config, the CLI prompts interactively. In non-interactive contexts it fails with a clear error.

`foundation clean`

foundation clean

Removes the generated build and theme artifacts: target/, the generated manifest.toml, and the ui/ui mapping. It walks up to the directory holding app-config.toml without parsing the config, so it still works when the config is mid-edit or the build is broken, which is exactly when you need it.

Run this after every SDK update, followed by foundation build, so the regenerated manifest, themes, and @ui mapping match the new bundle.

`foundation pack`

foundation pack [--release] [--out PATH]

Builds, signs, and wraps the app into a single installable .app archive, a gzip-wrapped tar holding manifest.json first and then every file it hashes, sorted by name. Users install it on device from Settings > Apps > Install App, from a USB drive, the Airlock, or internal storage.

The archive carries no signature of its own. The cosign2-signed manifest.json and its fileHashes cover every other file, so trust is the same as a sideloaded bundle.
The packer is handed its file list by the build rather than walking the directory, so what ships is exactly what the signature covers.
Archives are reproducible: fixed timestamps, uid/gid, and a sorted entry order, so the same bundle packs to identical bytes anywhere.
Installs are capped at 64 MiB, measured as the device reads the archive, tar framing included.
--out must not point inside the bundle being packed, and must not be a symlink. Creating the archive truncates whatever is at that path before the bundle is read.

`foundation sim`

foundation sim

Build for hosted execution and launch the bundled simulator.

Runs cargo build --package <app-name> with RUSTFLAGS="--cfg keyos"
Copies the binary and manifest.json to <sdk-root>/target/apps/<app-name>/
Resolves the simulator in this order: bundled foundation-simulator → foundation-simulator on PATH → repo-layout fallback to just sim
Your app appears in the simulator's on-device launcher

`foundation sideload`

foundation sideload [--release] [--no-run]

Build, sign, upload to a connected Passport Prime over usb-debug, and launch.

Process:

Runs the full foundation build flow
Starts the bundled foundation-passport-drive MCP helper and connects to Passport Prime over USB
Confirms Developer Mode is enabled
Confirms a trusted publisher certificate is installed
Uploads app.elf, manifest.json, the app icon, and generated resources over usb-debug
Launches the app through passport-drive MCP unless --no-run is set

Use --no-run to upload without launching. The passport-drive MCP server is the host-facing control interface for device-side developer features: sideloading, simulating touch and keyboard input, and taking screenshots. It is not an app-to-app messaging API and does not grant app permissions.

`foundation cert`

foundation cert gen [name] [--publisher-name NAME] [--contact-email EMAIL] [--support-url URL]
foundation cert print [name]
foundation cert fingerprint <path>
foundation cert install [name]

Generate, inspect, and register a publisher signing identity.

cert gen:

Defaults the name to [publisher].name in app-config.toml, or developer
Reads publisher metadata from app-config.toml and prompts for any missing fields (name, contact email, support URL)
Uses OpenSSL to emit a secp256k1 private key, a compressed public key, a self-signed X.509 code-signing certificate, and a matching cosign2.toml
Writes everything to ~/.foundation/signing/<name>/, with the certificate named after the identity, for example My Company.crt

cert print: Print the fingerprint and metadata for an existing identity.

cert fingerprint: Print the canonical fingerprint of a certificate file. Publish this fingerprint on your official website or GitHub so users can check that a certificate really is yours before allowing it.

cert install: Allow your publisher on a connected Passport Prime, so apps you sign will run on it. See Building Apps, Registering your developer certificate for the full flow. Requires the device unlocked, connected over USB, with Developer Mode enabled.

`foundation theme`

foundation theme [path]

Opens the visual theme editor, with undo/redo, for the current app's theme (resources/theme.json by default). You can also pass a relative or absolute path to any theme JSON.

Edits are written back to the theme JSON, then compiled to Rust by foundation build / foundation sim. See Building Apps, Theming for the full pipeline.

`foundation themes`

foundation themes build
foundation themes list
foundation themes new <name> [--from <base>]

Manages the named themes in ~/.foundation/themes/json/.

build, compiles theme JSON to Rust in ~/.foundation/themes/rust/. foundation build and foundation sim invoke this for you.
list, lists the themes available to inherit from.
new, creates a new named theme, inheriting from base_theme unless --from says otherwise. Use this for a reusable brand theme that several apps point at.

`foundation doctor`

foundation doctor

Advisory environment check. Verifies:

nix
Active Nix shell markers
SDK root discovery
cargo
armv7a-unknown-xous-elf target support
arm-none-eabi-strip
cosign2
foundation-slint-viewer or slint-viewer
git

Prints pass/fail plus a suggested fix per check. Advisory only, failed checks do not force a non-zero exit today.

`foundation preview`

foundation preview [file]

Live-preview a Slint UI file with hot reload. Defaults to ui/app.slint.

Uses foundation-slint-viewer, falls back to slint-viewer
If the file belongs to a Cargo project with a build.rs, runs cargo check --quiet --package <package> first to materialize generated Slint files (ui/gen/router.slint, ui/gen/navigate.slint, ui/gen/tr.slint, ui/gen/exports.slint)
If plain cargo check fails and the SDK root is known, retries via nix develop <sdk-root> --command cargo check ...

VS Code with the official Slint extension is the recommended editor; foundation preview provides the out-of-editor live reload story.

`foundation logs`

foundation logs [--timeout SECONDS]

Opens the Passport USB log viewer, streaming device logs over the USB debug interface. --timeout sets how long to wait before retrying USB discovery (default 3 seconds). Requires Developer Mode on the device.

`foundation plugin`

foundation plugin search <query>
foundation plugin install <plugin>
foundation plugin uninstall <plugin>

Manage external CLI plugins. Plugins extend foundation with new subcommands, useful for project-specific workflows.

`foundation completions`

foundation completions <bash|zsh|fish|powershell> [--install]

Emit shell completion scripts. Use --install to drop the script into the right place for your shell.

Environment variables

Variable	Effect
`FOUNDATION_SDK_ROOT`	Pin SDK root; skips the upward search
`FOUNDATION_SDK_BIN`	Path to the packaged `bin/` directory (set by `foundation develop`)
`SLINT_DIR`	Maintainer-only: point the build at a local Slint checkout

Exit codes

0, success
Non-zero, command-specific failure. foundation doctor is advisory and always exits 0 today even with failing checks.