CLI reference
Ten command groups, five global flags, six exit codes. Every command is safe to run twice; the only command that writes outside the working tree is cache gc.
Usage
bep [global flags] <command> [command flags]
bep --help
bep <command> --help| Global flag | Effect |
|---|---|
--config PATH | Use this file instead of ./bep.toml. |
--profile NAME | Select a profile from the config. |
--log-level LEVEL | error, warn, info, debug. |
--json | Machine-readable output on stdout; progress goes to stderr. |
--no-color | Plain text, no escape sequences. |
Commands
| Command | What it does | Writes |
|---|---|---|
init <dir> | Create a series with a starter config and two catalogue patches. | new directory |
fetch | Fetch the pinned revision and link it into the working directory. | cache, bep.lock |
apply | Apply the series in manifest order. --dry-run, --3way, --reject, --patch ID, --from-scratch, --continue. | sources, lock |
build | Configure and build the target. --target, --jobs, --clean, --check. | out/ |
verify | Compare the applied tree with the manifest. --manifest prints per-file lines. | nothing |
doctor | Report tools, cache and disk. --json recommended for tickets. | nothing |
patch add, list, drop | Manage entries in the series manifest. | series.toml |
series lint and series order | Check headers and dependency order without applying. | nothing |
config show and config check | Print resolved values, or validate the file. | nothing |
cache path and cache gc | Print the cache root, or remove old entries. --all removes everything. | cache |
Exit codes
| Code | Meaning | Typical cause |
|---|---|---|
| 0 | Success | Everything asked for happened. |
| 1 | Usage error | Unknown flag, missing argument, unreadable config. |
| 2 | Patch conflict | A hunk failed, a dependency is missing or a cycle exists. |
| 3 | Build failed | Compiler error, OOM killer, missing tool during configure. |
| 4 | Verification mismatch | The tree does not match the manifest. |
| 5 | Environment not ready | doctor found a failure; run it first. |
Codes are stable within a major version. Scripts should branch on the code and read human text from stderr only for logs.
Examples
Apply one patch while debugging
$ bep apply --patch debug-hooks --dry-run
would apply 0100-build-flags (required by debug-hooks)
would apply 0200-debug-hooks 3 files clean
2 patches, 0 conflictsJSON in CI
$ bep apply --json
{"applied": 2, "skipped": 0, "conflicts": 0, "lock": "bep.lock", "duration_ms": 2411}Rebuild after editing a patch
$ bep apply --from-scratch --patch debug-hooks
restored 0100-build-flags (unchanged)
applied 0200-debug-hooks 3 files
$ bep build --jobs 12--from-scratch discards the applied tree and re-applies the whole series, which is the honest way to test an edit that removes lines. Without it, apply works on the current tree and an edit that only deletes a hunk can appear to succeed while leaving the old line behind; the tool warns when a patch shrinks.
Output conventions
- Human output aligns on a 12-character first column, one line per event, no spinners when stdout is not a terminal.
- Warnings go to stderr and start with
warning; errors start witherror. --jsonprints exactly one object per command to stdout. Progress lines still go to stderr.- Nothing is truncated in a log file; the terminal view shortens long paths in the middle.
Environment
See the configuration page for BEP_CACHE, BEP_JOBS, BEP_PROFILE and the rest. bep --version prints the version, the short commit and the build date; include that line in every bug report.