CLI Runtime Reference

Spore CLI
Command Surface

End-to-end guide for running Spore from terminal, recovering PATH issues, executing diagnostics, and keeping PromptOps flows deterministic across app, CLI, and Raycast.

Back to Support Promptfile Reference Sharing Guide
• Promptfile v1 strict parsing • output.format strict validation • json input type enforcement

Quick Start

Terminal Flow 
# Local development
swift run spore --help

# Installed binary
spore doctor --workspace "<workspace-path>" --json

# If `spore` is not found on PATH
/Applications/Spore.app/Contents/MacOS/spore link-cli
/Applications/Spore.app/Contents/MacOS/spore doctor --bundle --workspace "<workspace-path>"

Command Catalog

Current Runtime
Command Purpose
spore new <title> --mode <pulse_mode> Create a new .spore.md Promptfile with canonical pulse_mode values.
spore parse <file> [--pretty] Validate and inspect Promptfile structure as JSON.
spore render <file> [--input key=value] [--copy] Render a Promptfile template locally with typed input validation.
spore list [--workspace <path>] [--mode <pulse_mode>] [--json] List indexed prompts from the active workspace.
spore show <id> [--workspace <path>] [--json] Inspect one indexed prompt and its resolved file path.
spore run <id> [--inputs key=value] [--json] Execute a prompt with provider options and optional run persistence.
spore test <id> [--json] Run prompt test assertions (must_include, max_words, regex, etc.).
spore install-defaults [--workspace <path>] [--overwrite] Install bundled defaults into a workspace with non-destructive behavior by default.
spore reindex [--workspace <path>] Rebuild cache/index.v1.json after file changes.
spore doctor [--workspace <path>] [--bundle] [--json] Run deterministic diagnostics and optional support-pack bundling.
spore link-cli [--target <path>] [--force] Install or refresh a stable PATH alias for the CLI binary.
spore watch [--workspace <path>] Watch workspace files and auto-reindex on changes.

Provider and Workspace Resolution

Execution Rules

Provider Modes

openai, apple, and auto are the supported CLI provider values. Auto mode prefers Apple Intelligence when available, then falls back to OpenAI.

Workspace Selection

Use --workspace for deterministic triage. If omitted, CLI resolves workspace through environment and defaults before operating on ~/Documents/Spore.

Schema Strictness

Promptfiles are parsed as v1 only (promptfile: 1 or omitted). Invalid output.format now fails fast instead of degrading silently.

json Input Type

inputs.*.type: json enforces valid JSON values at render/runtime, and nested JSON defaults are preserved in Promptfile parsing.

Diagnostics

SupportOps Core

Offline Doctor Pass

spore doctor --workspace "<workspace-path>" --json

Checks workspace availability, index integrity/freshness, prompt parse health, provider resolution, and credentials without running generation.

Support Pack Bundle

spore doctor --bundle --workspace "<workspace-path>" --json

Produces a sanitized JSON bundle with checks, suggested actions, watcher heartbeat, and recent redacted events for escalation.

PATH Recovery

spore link-cli
# fallback
/Applications/Spore.app/Contents/MacOS/spore link-cli

Creates a stable symlink target and prints PATH guidance when the target directory is not currently exported.

Troubleshooting

Field Cases
zsh: command not found: spore
Run /Applications/Spore.app/Contents/MacOS/spore link-cli. Then reopen shell or export the printed PATH update.
Prompt rejected for output.format
Use only markdown, text, json, or html. Any other value now fails parser validation.
Prompt rejected for promptfile version
Use promptfile: 1 or omit the field. Legacy versions are not accepted by current CLI parsing rules.
json input validation fails at run time
Ensure the provided value is valid JSON text. Example: --inputs payload={"ok":true}. Invalid JSON now fails deterministically.