CLI Reference

On This Page

🚧 The Passport Prime SDK is in public beta. 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 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 Prime over usb-debug, and launch.

Process:

Runs the full foundation build flow
Starts the bundled foundation-passport-drive MCP helper and connects to 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]

Generate or inspect 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>/

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

`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 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.