Command-line interface — published Scarp v0.0.5-alpha.4

Historical, release-pinned Scarp alpha.4 CLI: v0.0.5-alpha.4, released November 3, 2026 from source 79141329176f5dce51457e90a6652902f6432135. These commands are in the tagged interpreter prerelease, not just proposals. The language and project manifest are still experimental. For downloaded native packages and SHA-256 verification use Installation.

This page covers alpha.4. Preserve the separate historical alpha.3 file CLI and alpha.1 CLI for their actual command boundaries.

Published commands

Not yet in this published tag: scarp inspect modules --json DIRECTORY (development source only), scarp build, scarp compile, a package manager, arbitrary program-argument forwarding, native .srp executables or implicit project discovery. Older run, check, tokens, modules commands remain for migration, but check can execute runtime paths and is not a replacement for verify.

Create and run the first project

Run this in a writable parent directory where hello-world does not already exist. From an extracted package, use .\scarp.exe in PowerShell or ./scarp on Linux/macOS instead of a possibly older executable on PATH.

scarp version
scarp guide
scarp diagnose --json
scarp create hello-world
scarp verify hello-world
scarp launch hello-world
scarp verify hello-world/src/main.srp
scarp exec hello-world/src/main.srp

create generates hello-world/Scarp.project and hello-world/src/main.srp. It refuses to overwrite any existing directory, even an empty one. The exact generated manifest:

scarp-project: 1
name: hello-world
entry: src/main.srp

The exact generated source:

print("Hello from Scarp!");

Both launch hello-world and exec hello-world/src/main.srp print:

Hello from Scarp!

Source, manifest and stdout are pinned in the published alpha.4 conformance suite. See the first project quickstart.

File commands versus project commands

verify FILE.srp checks syntax, imports, names and types without executing normal runtime statements. verify DIRECTORY first validates that directory's explicit Scarp.project and its entrypoint, then performs the same static source checks. Successful verification is silent and creates no artifacts, but does not guarantee that launch will succeed at runtime. exec FILE.srp executes an individual source file. launch DIRECTORY executes the entrypoint declared in its manifest through the same interpreter.

The project manifest is UTF-8 with a 4096-byte maximum, exactly three ordered v1 fields (scarp-project: 1, name:, entry:). The entry must be a relative project-contained .srp path. Path traversal, unsafe symlink escapes, invalid fields and duplicated fields fail. The CLI never searches parent directories for the project manifest. See source path safety and alpha.3→alpha.4 migration.

Budgets, JSON and exit codes

launch and exec accept runtime flags before the path: --max-steps, --max-prints, --max-call-depth, --max-calls, --max-live-slots, --max-capture-bytes, --max-vector-bytes, --max-text-bytes. Static verify rejects runtime flags with exit status 2. Quote paths with spaces, and use -- for a path starting with a dash.

scarp launch --max-steps 500000 hello-world
scarp verify --diagnostic-format=json hello-world
scarp launch --diagnostic-format=json hello-world
scarp inspect modules --json hello-world/src/main.srp

diagnose --json reports "project_workflow":true and "native_executable":false. Successful inspect modules --json FILE emits schema-v1 inventory. The option --diagnostic-format=json on verify or launch changes error diagnostics on stderr only; a successful launch still writes ordinary program output, not successful JSON.

inspect tokens does not type-check, and inspect ast outputs a human-readable unstable tree, not successful JSON. See diagnostics, runtime budgets and compatibility.

Evidence: published release, tagged CLI, project parser and project tests. This page's commands and both language variants are checked by TypeScript documentation CI and a real tagged compiler conformance job.