CLI
The example · Northwind's developers pull main into their Next.js repo with the CLI, and Ananya merges from the terminal.
Install
npmpnpmbun
$ npm i -g @babul/cli
Or run it without installing: npx @babul/cli <command>.
Log in
Make a token in Account settings › API tokens. It starts with trk_ and can read and write what your access level allows.
$ babul login --token trk_8f2c…
✓ Logged in as Ritesh (Northwind)
$ babul use northwind-web
✓ Using northwind-web on main
The token is saved in
~/.config/babul/config.json, readable only by you. Never commit it. In CI, set BABUL_TOKEN instead.Project file
babul init writes babul.json at your repo root. babul pull reads it, so the whole team pulls the same way.
babul.json
{
"product": "northwind-web",
"ref": "main",
"framework": "react",
"styling": "tailwind",
"tokens": { "format": "tailwind", "out": "tailwind.theme.ts" },
"icons": { "out": "src/icons" },
"components": { "out": "src/components/babul", "include": ["Button", "Input"] }
}
Commands
Account and product
| Command | What it does |
|---|---|
| babul login --token <t> | Save a token for this machine |
| babul logout | Forget it |
| babul whoami | Who you are, your company and access level |
| babul products | Products you can open |
| babul use <product> [--ref r] | The product and ref to use when none is named |
| babul status | Product, ref, your draft's changes, and whether your files are behind |
Pull the design
babul pull [--ref r]
Write tokens, icons and components as
babul.json says.$ babul pull
✓ 48 tokens → tailwind.theme.ts
✓ 27 icons → src/icons/
✓ 2 components → src/components/babul/
main v0.5.0
babul tokens [--format f] [--out file]
The product's styles as one file.
| --format | css · tailwind · scss · w3c · style-dictionary · figma |
| --out | File to write; prints if left out |
$ babul tokens --format css --out tokens.css
babul icons --out dir
Every icon and logo as an SVG file.
$ babul icons --out src/icons
babul components
Components with their variants and how often each is used.
$ babul components
Button Solid, Outline, Ghost 41 uses
Input Default, Error 18 uses
babul code <component> [options]
One component's code, written from its spec.
| --framework | html · react · vue · angular · svelte · web-component |
| --styling | css · css-modules · tailwind · inline |
| --variant | Only this variant; all by default |
| --js | JavaScript instead of TypeScript |
| --out | Folder to write to |
$ babul code Button --framework react --styling tailwind --out src/components
✓ src/components/Button.tsx
babul spec <component> [--variant v]
The component's spec as JSON, for any other target.
$ babul spec Button > button.json
Branches and versions
| Command | What it does |
|---|---|
| babul branches | Open branches, with commits ahead, conflicts and Verify score |
| babul branch <name> | Make a branch from main |
| babul switch <ref> | Use a branch or a version for the next commands |
| babul log [--ref r] | Commits, newest first |
| babul diff [<a>] [<b>] | What changed between two refs; your draft against its branch if none |
| babul commit -m <msg> [--branch b] | Commit your draft to the branch; a new name makes a new branch |
| babul merge <branch> --bump <b> | Merge to main as patch, minor or major. Needs Can merge |
| babul versions | Versions of main |
$ babul diff main new-checkout
~ Button/Solid fill ink → brand/500
+ Checkout PromoCodeField
~ Checkout Pay button width auto → fill
$ babul merge new-checkout --bump minor
✓ Merged new-checkout → main v0.5.0
Global options
| Option | Meaning |
|---|---|
| --product <p> | Use this product |
| --ref <r> | main, a branch or a version like v0.5.0 |
| --json | Machine-readable output |
| --url <u> | Your Babul address, for a self-hosted or staging Babul |
| -h, --help | Help for any command |
Environment
| Variable | Use |
|---|---|
| BABUL_TOKEN | Token; wins over the saved one |
| BABUL_PRODUCT | Default product |
| BABUL_REF | Default ref |
| BABUL_URL | Babul's address |
Exit codes
| Code | Meaning |
|---|---|
| 0 | Done |
| 1 | Failed; the reason is printed |
| 2 | Not signed in, or the token cannot do this |
| 3 | Merge blocked by conflicts |
| 4 | Your files are behind (babul status --check) |
In CI
GitHub Actions
- run: npx @babul/cli status --check
env:
BABUL_TOKEN: ${{ secrets.BABUL_TOKEN }}
Fails the build when main has moved since your last babul pull.
Was this page helpful?
Yes
No
Updated Oct 22, 2026