CLI Reference
This page is based on CAPSULE_CLI_SPEC v0.3 command definitions,
separating implemented features from phase-planned features.
Engine Commands
Section titled “Engine Commands”capsule engine features
Section titled “capsule engine features”Status: Implemented
Display available Engine features.
capsule engine featurescapsule engine register
Section titled “capsule engine register”Status: Implemented
Register engine binary to ~/.capsule/config.toml.
capsule engine register --name <name> --path <path> [--default]capsule setup
Section titled “capsule setup”Status: Implemented
By default, fetches and registers nacelle binary.
capsule setup --engine nacelle [--version]Open / Run
Section titled “Open / Run”capsule open
Section titled “capsule open”Status: Implemented
Execute .capsule or capsule.toml. If eager dependencies exist in [ipc.imports], capsule-cli starts Services first and waits for ready.
capsule open <path> [--watch] [--background] [--enforcement]capsule new
Section titled “capsule new”Status: Implemented
Generate new project from template.
capsule new <name> --template <python|node|hono|rust|go|shell>Pack / Keygen / Sign
Section titled “Pack / Keygen / Sign”capsule pack
Section titled “capsule pack”Status: Implemented
Generate distribution using .capsuleignore and manifest settings.
capsule pack [dir] [--init] [--key] [--standalone] [--enforcement]capsule keygen
Section titled “capsule keygen”Status: Implemented
Generate signing key (Ed25519).
capsule keygen [--out] [--force] [--json]capsule sign
Section titled “capsule sign”Status: Implemented
Attach signature to artifact.
capsule sign <target> --key <path> [--out]Process Management
Section titled “Process Management”capsule ps
Section titled “capsule ps”Status: Implemented
List running Capsules.
capsule ps [--all] [--json]capsule close / capsule logs
Section titled “capsule close / capsule logs”Status: Implemented
Stop and log tracking.
capsule close [--id|--name] [--all] [--force]capsule logs [--id|--name] [--follow] [--tail]capsule guest
Section titled “capsule guest”Status: Implemented
Process .sync in Guest mode. Current implementation uses guest.v2 (JSON over stdio), migrating to JSON-RPC 2.0 in future.
capsule guest <sync_path>Validate / Install
Section titled “Validate / Install”capsule validate
Section titled “capsule validate”Status: Implemented
Besides manifest syntax validation, handles IPC reserved prefix conflicts, circular dependencies, and remote = true warnings (v0.3+ requirement).
capsule validate [path]capsule install
Section titled “capsule install”Status: Implemented
Through Store API distribution resolution, only installs distributions meeting signature_status=verified and hash integrity.
capsule install <name|path>IPC Commands
Section titled “IPC Commands”IPC commands are specified by phase. status is v0.3, others are v0.4 planned.
| Command | Phase | Status |
|---|---|---|
capsule ipc status [--json] | v0.3 | Planned/Designed |
capsule ipc services | v0.4 | Planned |
capsule ipc call <svc> <cap> --input '{...}' | v0.4 | Planned |
capsule ipc logs / inspect | v0.4 | Planned |
Source Registration
Section titled “Source Registration”capsule source register
Section titled “capsule source register”Status: Implemented
Register public GitHub repository as Store Source. Better Auth session (CAPSULE_SESSION_TOKEN) linkage recommended.
capsule source register <repo_url> [--registry] [--channel stable|beta]Source: docs/specs/CAPSULE_CLI_SPEC.md (v0.3).