{ "schemaVersion": "pulse.cli-command-spec.v5", "cliVersion": "1.0.0-beta.10", "completionShells": [ "bash", "zsh", "fish" ], "metaInvocations": [ { "syntax": "pulse --help | pulse -h | pulse help", "description": "Print public help." }, { "syntax": "pulse --version | pulse -v | pulse version", "description": "Print the installed CLI package version." }, { "syntax": "pulse completion ", "description": "Print a shell completion script generated from the public command specification." } ], "globalOptions": [ { "id": "help", "key": "help", "flags": [ { "name": "--help" }, { "name": "-h" } ], "kind": "boolean", "description": "Print public CLI help and exit." }, { "id": "json", "key": "json", "flags": [ { "name": "--json" } ], "kind": "boolean", "description": "Emit machine-readable JSON. pulse dev emits one JSON event per line." }, { "id": "dry-run", "key": "dryRun", "flags": [ { "name": "--dry-run" }, { "name": "--plan" } ], "kind": "boolean", "description": "Resolve and report the command plan without executing it." } ], "commands": [ { "name": "init", "summary": "Create a conventional .pulse workspace with an async Pulse application and dedicated test harness.", "usage": [ "pulse init [directory] [--name ] [--force]" ], "positionals": [ { "name": "directory", "key": "target", "description": "Target directory. Defaults to the current directory." } ], "options": [ { "id": "evidence-status", "key": "evidenceStatus", "flags": [ { "name": "--evidence-status" } ], "kind": "boolean", "description": "Emit one command-evidence JSON envelope with the original result and bounded evidence status. Does not establish runtime or provider qualification. Excludes dev and --html." }, { "id": "force", "key": "force", "flags": [ { "name": "--force" } ], "kind": "boolean", "description": "Allow generated files to replace entries in a non-empty target directory." }, { "id": "name", "key": "name", "flags": [ { "name": "--name" } ], "kind": "value", "valueName": "", "description": "Set the generated npm package name." } ], "examples": [ "pulse init ./my-pulse-app", "pulse init ./edge-app --name @example/edge-app" ], "diagnostics": [ "PULSE_INIT_NOT_EMPTY", "PULSE_INIT_FILE_EXISTS", "PULSE_PROVIDER_UNSUPPORTED" ], "outputs": [ "Human output lists generated files and next steps.", "With --json, emits one initialization result object." ], "sideEffects": [ "Creates .pulse/config.ts, an async Pulse application, a dedicated test harness, package scripts, and documentation.", "Does not install dependencies or run npm, pnpm, or any network operation." ], "exit": "0 on success; 2 for invalid usage, provider selection, or unsafe overwrite conditions." }, { "name": "doctor", "summary": "Audit project shape, compilation, schemas, provider bindings, output safety, and required tools.", "usage": [ "pulse doctor [directory] [--profile ] [--strict]" ], "positionals": [ { "name": "directory", "key": "directory", "description": "Project discovery start. Defaults to the current directory." } ], "options": [ { "id": "evidence-status", "key": "evidenceStatus", "flags": [ { "name": "--evidence-status" } ], "kind": "boolean", "description": "Emit one command-evidence JSON envelope with the original result and bounded evidence status. Does not establish runtime or provider qualification. Excludes dev and --html." }, { "id": "strict", "key": "strict", "flags": [ { "name": "--strict" } ], "kind": "boolean", "description": "Treat doctor warnings as failed checks." }, { "id": "profile", "key": "profile", "flags": [ { "name": "--profile" } ], "kind": "value", "valueName": "", "description": "Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile." } ], "examples": [ "pulse doctor ./my-pulse-app", "pulse doctor ./edge-app --strict --json" ], "diagnostics": [ "PULSE_CONFIG_NOT_FOUND", "PULSE_PROJECT_COMPILE_FAILED", "PULSE_NODE_VERSION_UNSUPPORTED", "PULSE_CANONICAL_NATIVE_COMPILE_FAILED", "PULSE_NATIVE_EXPANSION_REPEATED" ], "outputs": [ "Human output prints every check.", "With --json, emits one completed audit object including failed and warning checks." ], "sideEffects": [ "Reads and compiles the project.", "Does not write the build output." ], "exit": "0 when the audit passes; 1 when a completed audit contains failed checks; 2–5 only when the audit command itself cannot be completed." }, { "name": "inspect", "summary": "Report canonical compiler, schema, effect, continuation, capability, provider, and build-mode details.", "usage": [ "pulse inspect [directory] [--profile ]", "pulse inspect --artifact " ], "positionals": [ { "name": "directory", "key": "directory", "description": "Project discovery start. Defaults to the current directory." } ], "options": [ { "id": "evidence-status", "key": "evidenceStatus", "flags": [ { "name": "--evidence-status" } ], "kind": "boolean", "description": "Emit one command-evidence JSON envelope with the original result and bounded evidence status. Does not establish runtime or provider qualification. Excludes dev and --html." }, { "id": "profile", "key": "profile", "flags": [ { "name": "--profile" } ], "kind": "value", "valueName": "", "description": "Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile." }, { "id": "artifact", "key": "artifact", "flags": [ { "name": "--artifact" } ], "kind": "value", "valueName": "", "description": "Inspect an existing JSON build or compiler artifact instead of a project." } ], "examples": [ "pulse inspect ./my-pulse-app --json", "pulse inspect --artifact ./dist/pulse-build.json" ], "diagnostics": [ "PULSE_CONFIG_NOT_FOUND", "PULSE_PROJECT_COMPILE_FAILED", "PULSE_CANONICAL_COMPILE_FAILED" ], "outputs": [ "Human output prints a compact project/compiler summary.", "With --json, emits one inspection or artifact object." ], "sideEffects": [ "Compiles and validates the project in memory.", "Does not write the build output." ], "exit": "0 on success; 2–5 according to the emitted stable diagnostic." }, { "name": "test", "summary": "Run configured cases through the selected provider local-conformance runtime.", "usage": [ "pulse test [directory] [--profile ] [--case ]" ], "positionals": [ { "name": "directory", "key": "directory", "description": "Project discovery start. Defaults to the current directory." } ], "options": [ { "id": "evidence-status", "key": "evidenceStatus", "flags": [ { "name": "--evidence-status" } ], "kind": "boolean", "description": "Emit one command-evidence JSON envelope with the original result and bounded evidence status. Does not establish runtime or provider qualification. Excludes dev and --html." }, { "id": "profile", "key": "profile", "flags": [ { "name": "--profile" } ], "kind": "value", "valueName": "", "description": "Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile." }, { "id": "case", "key": "caseName", "flags": [ { "name": "--case" } ], "kind": "value", "valueName": "", "description": "Run one named project test case." } ], "examples": [ "pulse test ./my-pulse-app", "pulse test ./my-pulse-app --case smoke --json" ], "diagnostics": [ "PULSE_TEST_PROVIDER_REQUIRED", "PULSE_PROVIDER_CAPABILITY_MISSING", "PULSE_SCHEMA_DECODE" ], "outputs": [ "Human output uses TAP-like case lines and a summary.", "With --json, emits one test-run object; expected stable errors remain inside their case results." ], "sideEffects": [ "Compiles the project and executes configured deterministic or live fixtures.", "Does not write the build output." ], "exit": "0 when all selected cases pass; 1 when the completed test run has failed cases; 2–5 when setup, compilation, runtime, or toolchain execution fails before a normal result." }, { "name": "dev", "summary": "Start the foreground local server with the selected provider conformance runtime.", "usage": [ "pulse dev [directory] [--profile ] [--host ] [--port ] [--watch|--no-watch] [--once]" ], "positionals": [ { "name": "directory", "key": "directory", "description": "Project discovery start. Defaults to the current directory." } ], "options": [ { "id": "once", "key": "once", "flags": [ { "name": "--once" } ], "kind": "boolean", "description": "Close the development server after the first completed request." }, { "id": "watch", "key": "watch", "flags": [ { "name": "--watch", "value": true }, { "name": "--no-watch", "value": false } ], "kind": "boolean-value", "description": "Enable or disable entry and schema dependency watching. Watching is enabled by default." }, { "id": "profile", "key": "profile", "flags": [ { "name": "--profile" } ], "kind": "value", "valueName": "", "description": "Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile." }, { "id": "host", "key": "host", "flags": [ { "name": "--host" } ], "kind": "value", "valueName": "", "description": "Override the development listen host." }, { "id": "port", "key": "port", "flags": [ { "name": "--port" } ], "kind": "value", "valueName": "", "description": "Override the development listen port. Use 0 to request an ephemeral port." } ], "examples": [ "pulse dev ./my-pulse-app", "pulse dev ./my-pulse-app --port 0 --once --json" ], "diagnostics": [ "PULSE_DEV_PROVIDER_UNSUPPORTED", "PULSE_REQUEST_BODY_TOO_LARGE", "PULSE_FETCH_NETWORK" ], "outputs": [ "Human output reports the ready URL and reload or error messages.", "With --json, stdout is newline-delimited JSON events: compiled, ready, reloaded, request, compile-error, and request-error. It is not one enclosing JSON document." ], "sideEffects": [ "Binds a foreground HTTP listener.", "Watches the entry and schema dependency graph by default.", "Configuration-file changes require restarting the command." ], "exit": "0 after a normal server close; 2–5 when setup, compilation, provider, runtime, or toolchain initialization fails." }, { "name": "compile", "summary": "Compile the canonical project into provider-neutral Pulse-owned WebAssembly.", "usage": [ "pulse compile [directory] [--profile ] [--out ] [--clean|--no-clean] [--native-shrink0|--experimental-native-size|--experimental-native-bounded-size] [--emit-wat] [--elide-json-cache-arena]" ], "positionals": [ { "name": "directory", "key": "directory", "description": "Project discovery start. Defaults to the current directory." } ], "options": [ { "id": "evidence-status", "key": "evidenceStatus", "flags": [ { "name": "--evidence-status" } ], "kind": "boolean", "description": "Emit one command-evidence JSON envelope with the original result and bounded evidence status. Does not establish runtime or provider qualification. Excludes dev and --html." }, { "id": "clean", "key": "clean", "flags": [ { "name": "--clean", "value": true }, { "name": "--no-clean", "value": false } ], "kind": "boolean-value", "description": "Remove or preserve the selected output directory before writing artifacts. Cleaning is enabled by default." }, { "id": "elide-json-cache-arena", "key": "elideJsonCacheArena", "flags": [ { "name": "--elide-json-cache-arena" } ], "kind": "boolean", "description": "Opt in to omitting the json-as arena when string caching is disabled. Native only; preserves enabled caches. May increase peak memory for allocation-heavy workloads." }, { "id": "emit-wat", "key": "emitWat", "flags": [ { "name": "--emit-wat" } ], "kind": "boolean", "description": "Also emit diagnostic WebAssembly text (WAT). Native builds omit it by default; large text emission can exhaust compiler string capacity." }, { "id": "native-shrink0", "key": "nativeShrink0", "flags": [ { "name": "--native-shrink0" } ], "kind": "boolean", "description": "Use the previous Native O3/shrink0/no-convergence recipe instead of the bounded default. Mutually exclusive with the experimental Native size flags; overrides profile nativeOptimization. JavaScript build targets reject this flag." }, { "id": "experimental-native-bounded-size", "key": "experimentalNativeBoundedSize", "flags": [ { "name": "--experimental-native-bounded-size" } ], "kind": "boolean", "description": "Compatibility selection for O3/shrink2/no convergence, now the ordinary Native recipe; retains its historical explicit recipe identity. JavaScript build targets reject this flag." }, { "id": "experimental-native-size", "key": "experimentalNativeSize", "flags": [ { "name": "--experimental-native-size" } ], "kind": "boolean", "description": "Opt in to O3/shrink2 with convergence for Native Wasm. JavaScript build targets reject this flag." }, { "id": "profile", "key": "profile", "flags": [ { "name": "--profile" } ], "kind": "value", "valueName": "", "description": "Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile." }, { "id": "out", "key": "outDir", "flags": [ { "name": "--out" } ], "kind": "value", "valueName": "", "description": "Override the project-relative artifact output directory." } ], "examples": [ "pulse compile ./my-pulse-app", "pulse compile ./edge-app --out ./dist --json", "pulse compile ./edge-app --experimental-native-size", "pulse compile ./edge-app --experimental-native-bounded-size" ], "diagnostics": [ "PULSE_BUILD_OUT_UNSAFE", "PULSE_CANONICAL_NATIVE_PLAN_FAILED", "PULSE_CANONICAL_NATIVE_COMPILE_FAILED" ], "outputs": [ "Writes pulse-compile.json, the canonical program, native plan, generated AssemblyScript, compact Wasm, and native manifest; --emit-wat adds diagnostic WAT.", "The output is provider-neutral and does not package a deployment provider runtime.", "Native builds default to O3/shrink2/no convergence and record the explicit compiler recipe.", "With --json, emits one compile result object containing exact artifact paths and native metadata." ], "sideEffects": [ "Cleans the output directory by default.", "Invokes the lockfile-pinned AssemblyScript compiler.", "Refuses absolute, parent-traversal, and symbolic-link traversal outside the project root." ], "exit": "0 on success; 2–5 according to the emitted stable diagnostic." }, { "name": "build", "summary": "Build the Native or JavaScript target for the deployment provider selected by the active project profile.", "usage": [ "pulse build [directory] [--profile ] [--out ] [--clean|--no-clean] [--native-shrink0|--experimental-native-size|--experimental-native-bounded-size] [--emit-wat] [--elide-json-cache-arena]" ], "positionals": [ { "name": "directory", "key": "directory", "description": "Project discovery start. Defaults to the current directory." } ], "options": [ { "id": "evidence-status", "key": "evidenceStatus", "flags": [ { "name": "--evidence-status" } ], "kind": "boolean", "description": "Emit one command-evidence JSON envelope with the original result and bounded evidence status. Does not establish runtime or provider qualification. Excludes dev and --html." }, { "id": "clean", "key": "clean", "flags": [ { "name": "--clean", "value": true }, { "name": "--no-clean", "value": false } ], "kind": "boolean-value", "description": "Remove or preserve the selected output directory before writing artifacts. Cleaning is enabled by default." }, { "id": "elide-json-cache-arena", "key": "elideJsonCacheArena", "flags": [ { "name": "--elide-json-cache-arena" } ], "kind": "boolean", "description": "Opt in to omitting the json-as arena when string caching is disabled. Native only; preserves enabled caches. May increase peak memory for allocation-heavy workloads." }, { "id": "emit-wat", "key": "emitWat", "flags": [ { "name": "--emit-wat" } ], "kind": "boolean", "description": "Also emit diagnostic WebAssembly text (WAT). Native builds omit it by default; large text emission can exhaust compiler string capacity." }, { "id": "native-shrink0", "key": "nativeShrink0", "flags": [ { "name": "--native-shrink0" } ], "kind": "boolean", "description": "Use the previous Native O3/shrink0/no-convergence recipe instead of the bounded default. Mutually exclusive with the experimental Native size flags; overrides profile nativeOptimization. JavaScript build targets reject this flag." }, { "id": "experimental-native-bounded-size", "key": "experimentalNativeBoundedSize", "flags": [ { "name": "--experimental-native-bounded-size" } ], "kind": "boolean", "description": "Compatibility selection for O3/shrink2/no convergence, now the ordinary Native recipe; retains its historical explicit recipe identity. JavaScript build targets reject this flag." }, { "id": "experimental-native-size", "key": "experimentalNativeSize", "flags": [ { "name": "--experimental-native-size" } ], "kind": "boolean", "description": "Opt in to O3/shrink2 with convergence for Native Wasm. JavaScript build targets reject this flag." }, { "id": "profile", "key": "profile", "flags": [ { "name": "--profile" } ], "kind": "value", "valueName": "", "description": "Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile." }, { "id": "out", "key": "outDir", "flags": [ { "name": "--out" } ], "kind": "value", "valueName": "", "description": "Override the project-relative artifact output directory." } ], "examples": [ "pulse build ./my-pulse-app", "pulse build ./edge-app --out ./dist --json", "pulse build ./edge-app --experimental-native-size", "pulse build ./edge-app --experimental-native-bounded-size" ], "diagnostics": [ "PULSE_BUILD_OUT_UNSAFE", "PULSE_BUILD_PROVIDER_REQUIRED", "PULSE_EXPERIMENTAL_NATIVE_SIZE_UNSUPPORTED", "PULSE_NATIVE_TEXT_UNSUPPORTED", "PULSE_CANONICAL_NATIVE_COMPILE_FAILED" ], "outputs": [ "Writes pulse-build.json and the configured provider realization. Native builds include the provider-neutral native module; JavaScript builds emit a deterministic source package. Native --emit-wat builds also write diagnostic WAT.", "Fastly Native builds write generated AssemblyScript and direct-host-ABI native Wasm at bin/main.wasm without a JavaScript runtime image. Fastly JavaScript builds emit a source/deployment package with exact downstream compiler pins and deployment-candidate metadata.", "Native builds default to O3/shrink2/no convergence and record the explicit compiler recipe in portable, provider, and build metadata.", "With --json, emits one build result object containing exact artifact paths for the selected target and provider." ], "sideEffects": [ "Cleans the output directory by default.", "Native builds invoke the native compiler and configured provider realization. JavaScript builds validate and package the reachable application graph without invoking the Pulse Native compiler.", "Refuses absolute, parent-traversal, and symbolic-link traversal outside the project root." ], "exit": "0 on success; 2–5 according to the emitted stable diagnostic." }, { "name": "report", "summary": "Review retained evidence from a completed Native build without rebuilding or executing project code.", "usage": [ "pulse report [directory] [--profile ] [--json | --html] [--out ]", "pulse report --artifact [--json | --html] [--out ]" ], "positionals": [ { "name": "directory", "key": "directory", "description": "Project discovery start. Defaults to the current directory." } ], "options": [ { "id": "html", "key": "html", "flags": [ { "name": "--html" } ], "kind": "boolean", "description": "Write a self-contained offline HTML report; mutually exclusive with --json." }, { "id": "evidence-status", "key": "evidenceStatus", "flags": [ { "name": "--evidence-status" } ], "kind": "boolean", "description": "Emit one command-evidence JSON envelope with the original result and bounded evidence status. Does not establish runtime or provider qualification. Excludes dev and --html." }, { "id": "profile", "key": "profile", "flags": [ { "name": "--profile" } ], "kind": "value", "valueName": "", "description": "Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile." }, { "id": "out", "key": "outDir", "flags": [ { "name": "--out" } ], "kind": "value", "valueName": "", "description": "HTML destination under the selected root; requires --html. Defaults to .pulse/reports/pulse-report.html." }, { "id": "artifact", "key": "artifact", "flags": [ { "name": "--artifact" } ], "kind": "value", "valueName": "", "description": "Replay a saved Report capsule or supported completed-Wasm manifest without loading project code." } ], "examples": [ "pulse report ./my-pulse-app", "pulse report --artifact ./dist/pulse-compile.json --json" ], "diagnostics": [ "PULSE_REPORT_INPUT_INVALID", "PULSE_REPORT_EVIDENCE_MISSING", "PULSE_REPORT_STALE", "PULSE_REPORT_INCOMPATIBLE", "PULSE_REPORT_OUTPUT_UNSAFE", "PULSE_REPORT_OUTPUT_FAILED" ], "outputs": [ "Default output is a bounded terminal overview; --json emits one complete authoritative Report capsule.", "--evidence-status wraps the unchanged capsule in pulse.command-evidence v1; --json alone remains the authoritative capsule.", "Historical capsule replay preserves evidence identity without claiming current-project freshness.", "--html writes an offline route-first viewer with expandable schemas and full-capsule JSON export; it does not open a browser." ], "sideEffects": [ "Reads retained local evidence only; does not build, run tests, load project code, access secrets or contact the network.", "--plan and --dry-run describe intent without collecting or writing a report.", "--out requires --html; destinations must be contained regular .html files. Artifact roots are the input JSON parent directory.", "HTML writes a bounded .pulse-report-outputs receipt beside its destination; only matching generated bytes are excluded from project input scans. Recorded build inputs cannot be overwritten.", "Reports are build-review artifacts; review contents before sharing publicly." ], "exit": "0 for an eligible report even when optional evidence is unavailable; 2 for usage or unsafe output; 3 for invalid, missing, stale or incompatible evidence or an output write failure." }, { "name": "docs", "summary": "Locate the offline documentation shipped with the executing CLI package.", "usage": [ "pulse docs [--json]" ], "positionals": [], "options": [ { "id": "evidence-status", "key": "evidenceStatus", "flags": [ { "name": "--evidence-status" } ], "kind": "boolean", "description": "Emit one command-evidence JSON envelope with the original result and bounded evidence status. Does not establish runtime or provider qualification. Excludes dev and --html." } ], "examples": [ "pulse docs", "pulse docs --json" ], "diagnostics": [ "PULSE_DOCS_UNAVAILABLE", "PULSE_DOCS_INVALID" ], "outputs": [ "Human output prints the installed CLI version and absolute documentation index path.", "With --json, emits {status: \"ok\", version, docs: {root, index}} with the executing CLI version and absolute physical paths." ], "sideEffects": [ "Reads only the executing package documentation index; does not discover a project, compile code, install dependencies, contact the network, launch a server or open a browser.", "Validates the index type, containment, readability and nonempty UTF-8 text; does not audit every document or establish package integrity.", "--plan and --dry-run describe the locator without reading or validating documentation." ], "exit": "0 on success; 2 for invalid arguments; 5 when packaged documentation is unavailable or the index is invalid." } ] }