🚧 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:

1. Runs cargo build --target armv7a-unknown-xous-elf --package <app-name> [--release] with RUSTFLAGS="--cfg keyos -C relocation-model=pic -C link-arg=-pie"
2. Strips the binary into target/keyos/<app-name>/app.elf
3. Writes target/keyos/<app-name>/manifest.json with resolved permissions
4. 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] [--mount-path PATH] [--serial-port PATH]

Build, sign, copy to a connected Prime over USB mass storage, and launch.

Process:

1. Runs the full foundation build flow
2. Finds the PRIME USB volume — /Volumes/PRIME on macOS, /media/<user>/PRIME or /run/media/<user>/PRIME on Linux — or uses --mount-path
3. Copies app.elf and manifest.json to <prime-mount>/apps/<app-name>/
4. Opens the USB control port (--serial-port, then KEYOS_CONSOLE_DEV, then auto-detect)
5. Sends !foundation ping and expects !foundation ok ping
6. Sends !foundation launch <app-id> and expects !foundation ok launched <pid>

Use --no-run to copy without launching. If the copy succeeds but the USB control handshake fails, the error includes the install path and the failing serial response so you can debug without re-running the build.

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

Exit codes

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