Pulse Runtime Reference: pulse validate and pulse run

Pulse is the Kairo runtime environment. It takes the artifacts produced by forge build and either validates them or executes your application. The Pulse CLI exposes two commands: pulse validate for pre-flight checks and pulse run for launching your application. This page is the complete reference for both commands, valid entrypoint signatures, exit codes, and Pulse diagnostic codes.

`pulse validate`

Validates all Forge artifacts produced by forge build without executing any application code. Use pulse validate to confirm that a build output is well-formed before deploying to a target environment.

pulse validate [package-root]

If you omit package-root, Pulse uses the current working directory. What it checks:

Presence — all required artifact files exist under build/ and .forge/.
JSON readability — manifest and plan files are valid, parseable JSON.
Schema versions — artifact schema versions match the expected Pulse version.
Application kind — the application field in kairo.toml is a recognised kind.
Entrypoint metadata — the declared entrypoint function is present and has a valid signature.
Cross-artifact consistency — the build plan, output manifest, and IR handoff agree on module names, entrypoints, and artifact paths.
File existence — every path referenced in the manifest resolves to an actual file on disk.

What it does NOT do:

pulse validate does not execute any application code.
It does not run test cases or perform business-logic checks.

Diagnostic range: PLS000–PLS053

pulse validate ./dist/my-app
# Output:
# PLS000  OK  build plan present
# PLS001  OK  output manifest present
# ...
# Validation passed (53 checks)

Run pulse validate in your deployment pipeline after forge build and before pulse run to catch artifact problems early, without starting your application.

`pulse run`

Loads and executes a Kairo application from pre-built Forge artifacts.

pulse run [package-root]

If you omit package-root, Pulse uses the current working directory. What it does:

Runs pulse validate internally as a pre-flight step. If validation fails, the application does not start.
Reads [application].entry from kairo.toml to locate the entrypoint function.
Loads the compiled IR from .forge/ir-handoff/.
Executes the entrypoint function.
Returns the process exit code derived from the return value (see Exit Codes).

Requirements:

Artifacts must have been produced by forge build for the current source state.
The entrypoint function must match one of the valid signatures listed below.
kairo.toml must declare [application].entry.

pulse run does not rebuild your project. If you modify source files, run forge build before pulse run to ensure you are executing current code.

Entrypoint Signatures

The function named by [application].entry in kairo.toml must match one of the following signatures. Pulse infers the exit-code behaviour from the return type.

Signature	Exit code behaviour
`func main()`	Always exits `0` on completion
`func main(): Int32`	Return value becomes the exit code
`func main(): Result<_, E>`	`Result.success` → exit `0`; `Result.failure` → exit `1`
`async func main()`	Always exits `0` on completion
`async func main(): Int32`	Return value becomes the exit code
`async func main(): Result<_, E>`	`Result.success` → exit `0`; `Result.failure` → exit `1`

Any signature not listed above is rejected by pulse validate with a PLS diagnostic error.

Exit Codes

Exit code	Meaning
`0`	Successful completion (void entrypoint, or `Result.success`)
`1`	Application returned `Result.failure(...)`
`2`	Uncaught root fault during execution
`3`	Startup or artifact validation failure
n	Entrypoint returned integer value n

Exit code 3 is emitted by Pulse itself when pulse validate fails internally during pulse run. Your application code never runs in this case.

Pulse Diagnostic Codes

All diagnostics produced by the Pulse runtime carry the PLS prefix followed by a three-digit number.

Range	Area
`PLS000`–`PLS009`	Artifact presence and file-system checks
`PLS010`–`PLS019`	JSON readability and parse errors
`PLS020`–`PLS029`	Schema version validation
`PLS030`–`PLS039`	Application kind and entrypoint metadata
`PLS040`–`PLS049`	Cross-artifact consistency checks
`PLS050`–`PLS053`	File-existence checks for referenced paths

The full list of individual codes and their messages is available in the Pulse diagnostic reference.

When a pulse run fails with exit code 3, run pulse validate directly to see the full list of failing checks with their PLS codes before filing a bug report.

Language Reference

Forge CLI

Pulse Runtime

Pulse Runtime Reference: pulse validate and pulse run

`pulse validate`

`pulse run`

Entrypoint Signatures

Exit Codes

Pulse Diagnostic Codes

​pulse validate

​pulse run

​Entrypoint Signatures

​Exit Codes

​Pulse Diagnostic Codes

`pulse validate`

`pulse run`

Entrypoint Signatures

Exit Codes

Pulse Diagnostic Codes