CLI reference

The pulse CLI in @pulse-compute/cli@1.0.0-beta.10 is the supported project workflow. One command specification generates this page, installed help, and the shipped Bash, Zsh, and Fish completion scripts, so a public command or option cannot drift between those surfaces.

For Native defaults, escape hatches and optional memory settings, see Native build optimization.

Quick start

Use pulse to create, check, run and build a project. The general shape is:

pulse <command> [directory] [options]

Project commands use the current directory when [directory] is omitted. Provider and target come from the selected profile in .pulse/config.ts; --profile <name> selects another profile.

Common usage in an initialized project:

pulse doctor
pulse test
pulse dev
# Stop the foreground server with Ctrl-C before building.
pulse build

Use pulse inspect for project details and pulse report for retained Native build evidence. Global options and each command's options below retain the complete flags, limits and exit behavior.

Command index

Command	Purpose
pulse init	Create a conventional .pulse workspace with an async Pulse application and dedicated test harness.
pulse doctor	Audit project shape, compilation, schemas, provider bindings, output safety, and required tools.
pulse inspect	Report canonical compiler, schema, effect, continuation, capability, provider, and build-mode details.
pulse test	Run configured cases through the selected provider local-conformance runtime.
pulse dev	Start the foreground local server with the selected provider conformance runtime.
pulse compile	Compile the canonical project into provider-neutral Pulse-owned WebAssembly.
pulse build	Build the Native or JavaScript target for the deployment provider selected by the active project profile.
pulse report	Review retained evidence from a completed Native build without rebuilding or executing project code.
pulse docs	Locate the offline documentation shipped with the executing CLI package.

Use build for the configured target and provider. compile is advanced provider-neutral Native output, not a prerequisite for build. See Provider restrictions and build products for target differences.

Meta invocations

• pulse --help | pulse -h | pulse help — Print public help.
• pulse --version | pulse -v | pulse version — Print the installed CLI package version.
• pulse completion <bash|zsh|fish> — Print a shell completion script generated from the public command specification.

Global options

Option	Behavior
--help, -h	Print public CLI help and exit.
--json	Emit machine-readable JSON. pulse dev emits one JSON event per line.
--dry-run, --plan	Resolve and report the command plan without executing it.

Shell completion

Completion output is generated from the same public command and option specification as help and this reference. Tooling can consume the generated machine-readable command specification.

bash

source <(pulse completion bash)

The package also ships completions/pulse.bash.

zsh

source <(pulse completion zsh)

The package also ships completions/_pulse.

fish

pulse completion fish | source

The package also ships completions/pulse.fish.

pulse init

Create a conventional .pulse workspace with an async Pulse application and dedicated test harness.

Syntax:

pulse init [directory] [--name <package-name>] [--force]

Positionals

• directory — Target directory. Defaults to the current directory.

Options

Option	Behavior
--evidence-status	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.
--force	Allow generated files to replace entries in a non-empty target directory.
--name <package-name>	Set the generated npm package name.

Examples

pulse init ./my-pulse-app
pulse init ./edge-app --name @example/edge-app

Related diagnostics

• PULSE_INIT_NOT_EMPTY — Project initialization would write into a non-empty directory without explicit force.
• PULSE_INIT_FILE_EXISTS — Project initialization would replace an existing file that is not safe to overwrite.
• PULSE_PROVIDER_UNSUPPORTED — The selected provider value is not a supported shorthand or package selection.

Output

• Human output lists generated files and next steps.
• With --json, emits one initialization result object.

Side effects

• 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 behavior

0 on success; 2 for invalid usage, provider selection, or unsafe overwrite conditions.

pulse doctor

Audit project shape, compilation, schemas, provider bindings, output safety, and required tools.

Syntax:

pulse doctor [directory] [--profile <name>] [--strict]

Positionals

• directory — Project discovery start. Defaults to the current directory.

Options

Option	Behavior
--evidence-status	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.
--strict	Treat doctor warnings as failed checks.
--profile <profile>	Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile.

Examples

pulse doctor ./my-pulse-app
pulse doctor ./edge-app --strict --json

Related diagnostics

• PULSE_CONFIG_NOT_FOUND — Project discovery did not find an explicit Pulse configuration file.
• PULSE_PROJECT_COMPILE_FAILED — Whole-project compilation failed and contains one or more nested diagnostics.
• PULSE_NODE_VERSION_UNSUPPORTED — The active Node.js version is outside the supported release range.
• PULSE_CANONICAL_NATIVE_COMPILE_FAILED — The provider-neutral native plan could not be compiled into Pulse-owned WebAssembly.
• PULSE_NATIVE_EXPANSION_REPEATED — A repeated HTTP owner has multiple Native plan body instances and at least 1,024 additional lowered-source bytes across registrations.

Output

• Human output prints every check.
• With --json, emits one completed audit object including failed and warning checks.

Side effects

• Reads and compiles the project.
• Does not write the build output.

Exit behavior

0 when the audit passes; 1 when a completed audit contains failed checks; 2–5 only when the audit command itself cannot be completed.

pulse inspect

Report canonical compiler, schema, effect, continuation, capability, provider, and build-mode details.

Supported signatures:

pulse inspect [directory] [--profile <name>]
pulse inspect --artifact <file.json>

Positionals

• directory — Project discovery start. Defaults to the current directory.

Options

Option	Behavior
--evidence-status	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.
--profile <profile>	Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile.
--artifact <file.json>	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

Related diagnostics

• PULSE_CONFIG_NOT_FOUND — Project discovery did not find an explicit Pulse configuration file.
• PULSE_PROJECT_COMPILE_FAILED — Whole-project compilation failed and contains one or more nested diagnostics.
• PULSE_CANONICAL_COMPILE_FAILED — The handler uses a source form outside the canonical Beta authoring subset.

Output

• Human output prints a compact project/compiler summary.
• With --json, emits one inspection or artifact object.

Side effects

• Compiles and validates the project in memory.
• Does not write the build output.

Exit behavior

0 on success; 2–5 according to the emitted stable diagnostic.

pulse test

Run configured cases through the selected provider local-conformance runtime.

Syntax:

pulse test [directory] [--profile <name>] [--case <name>]

Positionals

• directory — Project discovery start. Defaults to the current directory.

Options

Option	Behavior
--evidence-status	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.
--profile <profile>	Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile.
--case <name>	Run one named project test case.

Examples

pulse test ./my-pulse-app
pulse test ./my-pulse-app --case smoke --json

Related diagnostics

• PULSE_TEST_PROVIDER_REQUIRED — Project tests require an executable provider.
• PULSE_PROVIDER_CAPABILITY_MISSING — The selected provider lacks a binding required by the compiled application.
• PULSE_SCHEMA_DECODE — JSON input did not satisfy the explicitly declared schema and content-type policy.

Output

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

Side effects

• Compiles the project and executes configured deterministic or live fixtures.
• Does not write the build output.

Exit behavior

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.

pulse dev

Start the foreground local server with the selected provider conformance runtime.

Syntax:

pulse dev [directory] [--profile <name>] [--host <host>] [--port <port>] [--watch|--no-watch] [--once]

Positionals

• directory — Project discovery start. Defaults to the current directory.

Options

Option	Behavior
--once	Close the development server after the first completed request.
--watch, --no-watch	Enable or disable entry and schema dependency watching. Watching is enabled by default.
--profile <profile>	Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile.
--host <host>	Override the development listen host.
--port <port>	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

Related diagnostics

• PULSE_DEV_PROVIDER_UNSUPPORTED — The development server requires an executable provider.
• PULSE_REQUEST_BODY_TOO_LARGE — A request or forwarded body exceeded its configured byte limit.
• PULSE_FETCH_NETWORK — An outbound fetch failed because the origin or network was unavailable.

Output

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

Side effects

• Binds a foreground HTTP listener.
• Watches the entry and schema dependency graph by default.
• Configuration-file changes require restarting the command.

Exit behavior

0 after a normal server close; 2–5 when setup, compilation, provider, runtime, or toolchain initialization fails.

pulse compile

Compile the canonical project into provider-neutral Pulse-owned WebAssembly.

Syntax:

pulse compile [directory] [--profile <name>] [--out <dir>] [--clean|--no-clean] [--native-shrink0|--experimental-native-size|--experimental-native-bounded-size] [--emit-wat] [--elide-json-cache-arena]

Positionals

• directory — Project discovery start. Defaults to the current directory.

Options

Option	Behavior
--evidence-status	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.
--clean, --no-clean	Remove or preserve the selected output directory before writing artifacts. Cleaning is enabled by default.
--elide-json-cache-arena	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.
--emit-wat	Also emit diagnostic WebAssembly text (WAT). Native builds omit it by default; large text emission can exhaust compiler string capacity.
--native-shrink0	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.
--experimental-native-bounded-size	Compatibility selection for O3/shrink2/no convergence, now the ordinary Native recipe; retains its historical explicit recipe identity. JavaScript build targets reject this flag.
--experimental-native-size	Opt in to O3/shrink2 with convergence for Native Wasm. JavaScript build targets reject this flag.
--profile <profile>	Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile.
--out <dir>	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

Related diagnostics

• PULSE_BUILD_OUT_UNSAFE — The resolved build output can escape or alias outside the project root.
• PULSE_CANONICAL_NATIVE_PLAN_FAILED — The canonical handler could not be represented by the provider-neutral native execution-plan contract.
• PULSE_CANONICAL_NATIVE_COMPILE_FAILED — The provider-neutral native plan could not be compiled into Pulse-owned WebAssembly.

Output

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

Side effects

• 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 behavior

0 on success; 2–5 according to the emitted stable diagnostic.

pulse build

Build the Native or JavaScript target for the deployment provider selected by the active project profile.

Syntax:

pulse build [directory] [--profile <name>] [--out <dir>] [--clean|--no-clean] [--native-shrink0|--experimental-native-size|--experimental-native-bounded-size] [--emit-wat] [--elide-json-cache-arena]

Positionals

• directory — Project discovery start. Defaults to the current directory.

Options

Option	Behavior
--evidence-status	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.
--clean, --no-clean	Remove or preserve the selected output directory before writing artifacts. Cleaning is enabled by default.
--elide-json-cache-arena	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.
--emit-wat	Also emit diagnostic WebAssembly text (WAT). Native builds omit it by default; large text emission can exhaust compiler string capacity.
--native-shrink0	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.
--experimental-native-bounded-size	Compatibility selection for O3/shrink2/no convergence, now the ordinary Native recipe; retains its historical explicit recipe identity. JavaScript build targets reject this flag.
--experimental-native-size	Opt in to O3/shrink2 with convergence for Native Wasm. JavaScript build targets reject this flag.
--profile <profile>	Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile.
--out <dir>	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

Related diagnostics

• PULSE_BUILD_OUT_UNSAFE — The resolved build output can escape or alias outside the project root.
• PULSE_BUILD_PROVIDER_REQUIRED — pulse build requires a configured deployment provider; provider-neutral output belongs to pulse compile.
• PULSE_EXPERIMENTAL_NATIVE_SIZE_UNSUPPORTED — Native optimization selections cannot be used for a JavaScript build target.
• PULSE_NATIVE_TEXT_UNSUPPORTED — Diagnostic WebAssembly text is available only for Native compilation.
• PULSE_CANONICAL_NATIVE_COMPILE_FAILED — The provider-neutral native plan could not be compiled into Pulse-owned WebAssembly.

Output

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

Side effects

• 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 behavior

0 on success; 2–5 according to the emitted stable diagnostic.

pulse report

Review retained evidence from a completed Native build without rebuilding or executing project code.

Supported signatures:

pulse report [directory] [--profile <name>] [--json | --html] [--out <file.html>]
pulse report --artifact <file.json> [--json | --html] [--out <file.html>]

Positionals

• directory — Project discovery start. Defaults to the current directory.

Options

Option	Behavior
--html	Write a self-contained offline HTML report; mutually exclusive with --json.
--evidence-status	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.
--profile <profile>	Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile.
--out <file.html>	HTML destination under the selected root; requires --html. Defaults to .pulse/reports/pulse-report.html.
--artifact <file.json>	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

Related diagnostics

• PULSE_REPORT_INPUT_INVALID — Report evidence is malformed, unsafe, or fails integrity validation.
• PULSE_REPORT_EVIDENCE_MISSING — A matching completed Wasm build and its required retained evidence are missing.
• PULSE_REPORT_STALE — Retained Report evidence does not match the selected inputs or changed during collection.
• PULSE_REPORT_INCOMPATIBLE — The Report input version or output representation is unsupported.
• PULSE_REPORT_OUTPUT_UNSAFE — The HTML output path is not a contained regular .html file.
• PULSE_REPORT_OUTPUT_FAILED — The HTML report could not be written atomically.

Output

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

Side effects

• 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 behavior

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.

pulse docs

Locate the offline documentation shipped with the executing CLI package.

Syntax:

pulse docs [--json]

Options

Option	Behavior
--evidence-status	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

Related diagnostics

• PULSE_DOCS_UNAVAILABLE — The executing CLI package documentation index is missing or unreadable.
• PULSE_DOCS_INVALID — The executing CLI package documentation index has an invalid type, location or text format.

Output

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

Side effects

• 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 behavior

0 on success; 2 for invalid arguments; 5 when packaged documentation is unavailable or the index is invalid.

Configuration discovery and command precedence

Project commands start discovery from their optional positional [directory] or the current directory, then search upward for the single configuration entrypoint:

.pulse/config.ts

Profile selection follows --profile, PULSE_PROFILE, then pulse.defaultProfile. Command-line --out, --host, --port, and watch flags are invocation-local controls. Entry, provider, and target selection belong to .pulse/config.ts: pulse compile remains provider-neutral and pulse build realizes the selected provider. See Project configuration.

JSON and stream contracts

For completed commands, --json emits one JSON object followed by a newline. pulse dev --json is deliberately different: stdout is newline-delimited JSON, with one event object per line. Event names are compiled, ready, reloaded, request, compile-error, and request-error; consumers must not wait for one enclosing JSON document.

Raw configured secret values are not included in project JSON, diagnostics, or runtime error detail fields.

Provider restrictions and build products

Provider	Target	inspect	build	test/dev	Build result
node	Native	Yes	Yes	Node host	Portable Pulse Wasm, configured Node-native realization and pulse-build.json.
node	JavaScript	Yes	Yes	Live JavaScript runtime	Deterministic reachable application source package and pulse-build.json; no Pulse Native compilation.
fastly	Native	Yes	Yes	Local conformance	Portable Pulse Wasm, generated AssemblyScript, direct-host-ABI bin/main.wasm and pulse-build.json; no JavaScript runtime image.
fastly	JavaScript	Yes	Yes	Provider emulation	Deterministic source/deployment package with exact downstream compiler pins, deployment-candidate metadata and pulse-build.json.
none	Compile-only Native	Yes	No	No	pulse compile emits portable Pulse Wasm; pulse build rejects the missing deployment provider.

Target selection is explicit and never falls back automatically. Project eligibility and provider capability restrictions still apply; see Provider and target compatibility. pulse compile requires Native-compatible source regardless of the configured target. Diagnostic WAT is opt-in with --emit-wat; JavaScript builds reject that flag. Fastly JavaScript downstream runtime compilation and candidate validation are separate from source packaging; a build does not deploy or publish. See Fastly deployment candidates.

Build output is cleaned by default. --no-clean preserves the directory, but output safety still rejects absolute, parent-traversal, and symbolic-link traversal outside the project root.

Exit classes

Exit	Meaning
0	Command completed successfully.
1	Completed audit/test failure where documented, or an unexpected uncatalogued internal failure.
2	Usage, project configuration, provider selection, or output-safety error.
3	Canonical/schema/package-lowering/provider-binding failure.
4	Request, test, runtime, fetch, or continuation failure.
5	External toolchain or Fastly local-execution failure.

pulse doctor completes with exit 1 when its audit contains failed checks. pulse test completes with exit 1 when a normal test run has failed cases. Setup failures use their diagnostic exit class.

Failed commands emit stable codes, categories, summaries, remediation, exit classes, and a versioned documentation URL. See Diagnostics and remediation.