CLI reference#

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

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#

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#

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.

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#

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#

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#

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 — An incoming development request exceeded dev.maxBodyBytes.
• 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]

Positionals#

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

Options#

Examples#

pulse compile ./my-pulse-app
pulse compile ./edge-app --out ./dist --json
pulse compile ./edge-app --experimental-native-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, WAT, and native manifest.
• 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]

Positionals#

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

Options#

Examples#

pulse build ./my-pulse-app
pulse build ./edge-app --out ./dist --json
pulse build ./edge-app --experimental-native-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_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.
• 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.

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#

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#

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.