Sploosh Command Line Interface
Relevant source files
The following files were used as context for generating this wiki page:
The Sploosh Command Line Interface (CLI) is the primary gateway for developers and AI agents to interact with the Sploosh toolchain. As a "safety-first" and "AI-native" language, the CLI is designed not just for human readability but for seamless integration into agentic tool-loops, offering stable error codes and machine-applicable fixes through structured output formats.
The interface serves as the orchestration layer for the Sploosh compiler bootstrap, managing the flow from source code fixtures (.sp files) through the lexer, parser, and eventually to multiple compilation targets including native LLVM, WASM, EVM, and Solana SBF.
Sources: README.md:12-25, VISION.md:79-82, crates/AGENTS.md:5-15
CLI Toolchain Roadmap
The Sploosh CLI is being developed in a phased approach, with core compiler functionality preceding the full developer experience (DX) suite. The orchestration of these commands is planned for Milestone 8 of the project roadmap.
| Command | Purpose | Roadmap Phase |
|---|---|---|
sploosh build | Compiles source to native, WASM, or on-chain targets | Milestone 8 |
sploosh check | Performs type checking and semantic analysis without code gen | Milestone 8 |
sploosh test | Runs unit and integration tests from the source tree | Milestone 8 |
Sources: README.md:92-100, crates/AGENTS.md:65-75
Architectural Data Flow
The CLI acts as the entry point for the compiler pipeline. It coordinates between the bootstrap crates to process Sploosh source code.
The diagram above illustrates how the CLI orchestrates the transformation of code from raw text to target-specific bytecode through the internal crates.
Sources: README.md:79-88, README.md:100-104, VISION.md:50-55
Diagnostics and Agent Integration
A core design principle of the Sploosh CLI is "Diagnostics designed for agents." Unlike traditional compilers that focus primarily on human-readable terminal output, the Sploosh CLI is built to support tool-loop consumption by AI agents.
Structured Output
- NDJSON Support: The CLI is designed to emit diagnostics in Newline Delimited JSON (NDJSON) format, allowing AI agents to parse errors programmatically.
- Stable Error Codes: Every diagnostic is mapped to a stable code, ensuring that agentic instructions remain valid across compiler versions.
- Machine-Applicable Fixes: Where possible, the CLI provides suggested code transformations that can be applied automatically by developer tools.
Sources: README.md:21-25, AGENTS.md:65-75
Support Utilities and Scripts
In addition to the core sploosh binary, the repository includes specialized CLI utilities used for CI/CD and specification maintenance.
Prompt Budget Enforcement
The check_prompt_budget.py script is a CLI utility used in GitHub Actions to ensure the prompt-sized spec mirrors do not exceed token ceilings.
# Usage example for the prompt budget CLI
python scripts/check_prompt_budget.py --core-ceiling 5600 --web3-ceiling 1500 --warn-at 0.9
Sources: scripts/check_prompt_budget.py:34-45, CONTRIBUTING.md:105-115
Docker Integration
For cross-platform consistency, the project provides a PowerShell wrapper for Docker-based checks, ensuring that local validation matches the CI environment.
.\scripts\docker-check.ps1 -Build
Sources: CONTRIBUTING.md:50-55, AGENTS.md:19-25
Project Status and Tooling Availability
The Sploosh CLI is currently in a pre-1.0 state. While the lexer and parser are active under crates/, the full sploosh build|test|check suite and LSP (Language Server Protocol) are designated as future considerations in the roadmap.
Current Developer Workflow
Until the full CLI binary is released, developers interact with the system using Cargo commands to run tests and linters on the compiler crates:
cargo fmt --all -- --checkcargo clippy --workspace --all-targets -- -D warningscargo test --workspace
Sources: README.md:74-77, CONTRIBUTING.md:42-48, crates/AGENTS.md:70-80
The Sploosh CLI represents a shift toward LLM-native development, prioritizing deterministic, machine-readable feedback and multi-target compilation from a single command interface. As the project progresses through its milestones, the CLI will evolve into a comprehensive suite for building and deploying safety-critical applications across web2 and web3 environments.