CLI reference

The pulse CLI in @pulse-compute/cli@1.0.0-beta.9 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.

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
--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
--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
--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
--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] [--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
--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.
--experimental-native-bounded-size	Experimentally optimize Native Wasm with shrink level 2 without convergence. JavaScript build targets reject this flag.
--experimental-native-size	Experimentally optimize Native Wasm for size. 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.
• Experimental size builds record the exact non-default Native compiler optimization settings.
• 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

Compile the canonical project and realize the deployment provider selected by the active project profile.

Syntax:

pulse build [directory] [--profile <name>] [--out <dir>] [--clean|--no-clean] [--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
--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.
--experimental-native-bounded-size	Experimentally optimize Native Wasm with shrink level 2 without convergence. JavaScript build targets reject this flag.
--experimental-native-size	Experimentally optimize Native Wasm for size. 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 — The experimental Native size optimizer 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, the provider-neutral native module, and the configured provider realization; Native --emit-wat builds also write diagnostic WAT.
• Fastly builds write generated AssemblyScript and direct-host-ABI native Wasm at bin/main.wasm; no JavaScript runtime image is packaged.
• Experimental size builds record the exact non-default Native compiler optimization settings in portable, provider, and build metadata.
• With --json, emits one build result object containing exact portable and provider artifact paths.

Side effects

• Cleans the output directory by default.
• Invokes the native compiler and configured provider realization.
• 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.
--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.
• 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.

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	inspect/build	test/dev	Build result
node	Yes	Yes	Portable Pulse Wasm plus the configured Node-native realization and pulse-build.json.
fastly	Yes	Yes, through local conformance	Portable Pulse Wasm plus generated AssemblyScript and compact direct-host-ABI bin/main.wasm.
none	Compile only	No	pulse compile emits portable Pulse Wasm; pulse build rejects the missing deployment provider.

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.