GETTING STARTED WITH BEAN

bean is the Beanstalk compiler and project tool.

It is the command-line entry point launched by the compiler binary, and it will eventually grow into the Cargo-like tool for Beanstalk projects.

The tooling is still early. Command names, generated project structure, config options, and backend flags may change at this stage in development.

it's main purpose right now is to: create a project, check it, build it, and run the hot-reloading dev server.

If you are running the compiler from the repository instead of an installed bean binary, use cargo run -- before the same commands:


    cargo run -- dev .
    cargo run -- check .
    cargo run -- build .

Current commands

Command	Use	Notes
bean help	Prints the current command list and supported flags.	Use this when the docs and local compiler may be out of sync.
bean --version	Prints the current compiler/tool version.	-v and -V are also accepted.
bean new html	Creates a minimal HTML project scaffold.	Currently prompts for a project path and project name. More project options are planned.
bean check path	Runs project discovery, frontend compilation, type checking, HIR lowering, and borrow validation without writing build artifacts.	Add --terse for compact one-line diagnostics.
bean dev path	Builds the project, starts a local dev server, watches files, and reloads the browser when sources change.	This is the main day-to-day command for working on HTML projects.
bean build path	Builds the project and writes output files.	Without --release, directory projects write to the configured dev output folder. With --release, they write to the configured release output folder.
bean tests	Runs the compiler integration test suite.	Mainly useful when working on the compiler itself. Use --backend html or --backend html_wasm to focus one backend profile.

Current flags

Flag	Applies to	Effect
--release	build, dev	Selects the release build profile and release output folder where supported.
--hide-warnings	Build-style commands	Hides warning output. Use sparingly while developing.
--hide-timers	Build-style commands	Hides timing output.
--html-wasm	HTML builds	Uses the experimental HTML-Wasm backend path. The JavaScript HTML backend is the current Alpha target.
--terse	check only	Prints compact diagnostics for tools, logs, and LLM workflows.
--host, --port, --poll-interval-ms	dev only	Configures the local dev server. Defaults are 127.0.0.1, 6342, and 300.

Create a new HTML project

The current project scaffold is intentionally small. It creates the project config and output folders, then you can add a page entry file. The HTML project builder itself has more rules than this page needs to cover; see the HTML project builder guide for page layout, routing, assets, fragments, and generated output details.

Start a new project:


    bean new html

The command asks for:


    Enter project path:
    Project name:

After the project exists, add an entry page if the scaffold has not created one yet:


    cd path/to/your-project
    mkdir -p src
    nano src/#page.bst

A minimal first page can be:


    # page_title = "Hello Beanstalk"

    [$markdown:
        # Hello from Beanstalk

        Edit this file and save to trigger hot reload.
    ]

Then check it:


    bean check .

Run the dev server

dev is currently the most useful command for normal Beanstalk project work.

It builds the project, serves the generated files locally, watches for source changes, and sends reload events to the browser.


    bean dev .

By default, open:


    http://127.0.0.1:6342/

Useful dev-server options:


    bean dev . --port 8080
    bean dev . --host 0.0.0.0
    bean dev . --poll-interval-ms 100

When a build fails, fix the reported error and save again. The dev server is designed around fast feedback rather than a manual rebuild loop.

Build a project

Use build when you want files written to disk without running the dev server.


    bean build .

For a release build:


    bean build . --release

For HTML projects, generated files are written under the configured output folder. The default scaffold currently uses dev for development output and release for release output.

Check without building

check is the fastest correctness command for editor loops and CI-style validation.

It does not write output artifacts, but it still runs the shared frontend diagnostics used by all backends.


    bean check .

Use terse mode when another tool will read the output:


    bean check . --terse

Terse diagnostics have a stable compact shape:


    E|type|src/#page.bst|4:12|Expected Bool, found Int|help=Use a Bool expression here.
    W|identifier_naming_convention|src/button.bst|1:1|Import alias case mismatch

Reading compiler errors

Beanstalk uses the same formatted diagnostic system across the compiler front end and backend builders. That means syntax errors, type errors, config errors, file errors, borrow-checker errors, dev-server errors, and backend errors use the same basic shape.

A normal diagnostic contains:

the error kind
the main message
the source file path, line, and column
the source line when available
a caret underline for the offending span
guidance lines when the compiler has a useful suggestion

Example shape:


    Type Error (ಠ_ಠ) 🔥
    Declaration 'count' has incompatible initializer type. Expected 'Int', but found 'String'.

      --> src/#page.bst:6:17
        |
      6 | count Int = "wrong"
        |             ^^^^^^^
      Use an Int value here, or change the declaration type.

Read diagnostics from top to bottom:

The kind tells you which part of the compiler rejected the program.
The message tells you the actual rule that failed.
The file/line/column points to the primary source location.
The caret shows the token or expression the compiler is complaining about.
The guidance lines are suggestions, not a separate error.

Error kinds

Kind	Meaning	Usual fix
Syntax Error	The source text could not be parsed as Beanstalk syntax.	Check punctuation, block delimiters, template brackets, imports, and declaration shape.
Type Error	The expression type does not match the expected type.	Check annotations, return types, function arguments, collection element types, and contextual casts.
Language Rule Error	The syntax is valid, but it violates a language rule.	Check things like mutability, import visibility, unsupported feature surfaces, duplicate names, or invalid top-level code.
Missing File or Directory	The project references a file, directory, import path, or output path that cannot be resolved.	Check spelling, relative paths, root folders, and project config.
Malformed Config	The project config exists but contains unsupported, missing, or invalid settings.	Check #config.bst and backend-specific config rules.
Borrow Checker Violation	The program violates Beanstalk's access and ownership rules.	Check mutable/exclusive access, later uses after possible moves, and overlapping borrows.
Dev Server Issue	The local server could not start, watch, build, or serve the project correctly.	Check port conflicts, host binding, project path, and file permissions.
Compiler Bug / HIR / LIR / WASM Generation Bug	The compiler hit an internal invariant or unsupported backend path.	Reduce the input if practical and report it. User code should receive structured errors instead of compiler bugs.

Warnings and future suggestions

Warnings are for code that can still compile but deserves attention. Current warnings include things like malformed CSS/HTML template content, large tracked assets, naming convention issues, and import alias case mismatches.

Beanstalk deliberately separates correctness from style pressure. The future suggest command is planned to become the pedantic style and cleanup pass: closer to a full Clippy-style assistant for Beanstalk code. That is where noisy suggestions such as unused variables, unused imports, unused declarations, and more specific style improvements should live.

The intended workflow will be:


    bean check .
    bean suggest .
    bean fmt .

For now, use check and the compiler's normal warnings as the practical baseline.

Planned bean extensions

bean is expected to become the main Beanstalk project tool, not just a thin compiler launcher.

Planned additions include:

a package manager for Beanstalk libraries and project dependencies
a formatter for stable project-wide formatting
suggest, a pedantic style and cleanup command to use alongside check
richer new project options, including more complete config templates
stronger project maintenance commands as the build system matures

The short-term rule is simple: dev for fast browser feedback, check for correctness, and build when you want output files.