Skip to main content

Basic usage

Once you have a build, from Your first project, or imported from Maven or sbt, bleep is a small set of verbs. This page is the cheat-sheet.

Every command that takes project names accepts project globs: names like myapp, myapp@jvm213, jvm3, kotlin, or path prefixes like services/api. With no arguments most commands default to everything.

Compile​

bleep compile                  # everything
bleep compile myapp            # one project
bleep compile myapp@jvm3       # one cross variant
bleep compile jvm3             # everything on the jvm3 cross
bleep compile services/api     # everything under that path prefix
bleep compile --watch          # rebuild on file change (alias: -w)
bleep compile --diff-watch     # watch mode with terse per-project diffs

Test​

bleep test                     # every test project (isTestProject: true)
bleep test myapp-test          # one
bleep test --watch             # auto-rerun on file changes
bleep list-tests               # list test names without running them

bleep test --diff-watch works the same as compile --diff-watch, showing only the suites whose pass/fail status flipped between cycles.

Run history and diffs​

Every compile and test run is recorded into the workspace (.bleep/builds/normal/history/, per worktree, the last 32 kept) — summaries end with a History: #N line pointing at the transcript.

bleep history                  # list recorded compile/test runs
bleep history show 7           # full transcript of run #7, as JSON
bleep history diff 6 7         # what logically changed between two runs
bleep history diff 6 7 --timing # what got slower/faster, jitter suppressed
bleep test --diff              # run tests, print only what changed vs the previous run
bleep compile --diff           # same, for diagnostics

--diff=<id> pins a fixed baseline (say, the last green run) instead of the previous run. The run history & diffs guide tells the whole story, with a demo video; bleep history is the reference.

Run​

bleep run myapp                # invokes platform.mainClass
bleep run myapp -- arg1 arg2   # arguments after `--` go to the program
bleep run myscript             # named scripts live alongside projects

Find what's there​

bleep projects                 # list every project in the build
bleep projects jvm3            # what does this glob expand to?
bleep projects services/api    # what's under this path prefix?
bleep projects-test            # list every test project
bleep build show short         # bleep.yaml as written, normalised
bleep build show effective     # full project config after templates apply

When you cd into a subfolder of your build, bleep projects (and every other command) automatically scopes to projects whose folder sits under your CWD. See Selecting projects via subfolders.

Format your code​

bleep fmt                      # scalafmt / ktfmt / google-java-format,
                               # depending on what the project compiles

Clean​

bleep clean                    # remove compile output

IDE setup​

Bleep speaks BSP, so any BSP-aware editor talks to it directly:

bleep setup-ide                # generate ./bsp/bleep.json

Then open the build root in IntelliJ / VS Code (with Metals) / your editor of choice; it imports in about a second.

Reshaping the build​

Because bleep.yaml is data, the build tool can edit it for you. The bleep build subcommand has a small library of mutating operations , update-deps, project-rename, project-merge-into, templates-reapply, normalize, and friends.

bleep build update-deps        # bump every dependency to latest
bleep build project-rename a b # rename a project; references update
bleep build diff effective     # diff against any git revision

Where to go next​

  • Project globs: the full vocabulary for naming projects and groups, plus how cd interacts with command scope.
  • Scripts: custom build logic as regular Java, Kotlin, or Scala programs you can debug.
  • Tab completions: install shell completion so globs surface as you type.