CLI Commands

Detailed documentation for each gb command.

---

Status

gb status

Shows git status --porcelain output grouped by service. Each service is color-coded with file counts.

Example output:

backend (3 files)
  M  src/auth/auth.controller.ts
  M  src/images/images.service.ts
  ??  src/images/transformer.ts

frontend (2 files)
  M  lib/api.ts
  M  components/layout/app-sidebar.tsx

---

Affected

gb affected [--base=main]

Lists which services have changes compared to a base branch. Useful for CI pipelines and selective builds.

Options:

Flag	Default	Description
--base	main	Base branch to compare against

Outputs a space-separated list of affected service names (e.g., backend frontend).

---

Branch

gb branch [service] [name]
gb branch [service] [name] --type=feat
gb branch --custom "my branch name"

Creates a new branch scoped to a service.

Options:

Flag	Description
--type=<type>	Optional type prefix (e.g., feat, fix). Produces type(service)/name format
--custom	Skip service and type selection, create a branch with a freeform name

Interactive mode (no arguments):

1. Prompted to select a service (or "custom" for freeform)
2. If a service is selected, prompted to select a type (or "skip")
3. Prompted for a branch name
4. Branch is created and checked out

Branch name formats:

Inputs	Result
Service: frontend, Type: feat, Name: add auth	feat(frontend)/add-auth
Service: frontend, Type: skip, Name: add auth	frontend(add-auth)
Custom, Name: best branch ever	best-branch-ever

Protected branch warning: If the current branch is not protected (main/master/staging), a confirmation prompt is shown before creating.

---

Commit

gb commit [service]
gb commit [service] --topic "topic" --type=feat
gb commit [service] --topic "topic" -m "message" --type=fix

Interactive commit flow scoped to a single service, with support for multi-service commits in a single session.

Options:

Flag	Default	Description
--topic "..."	prompted	Commit subject (required, max 10 words)
-m "..."	prompted	Optional extended commit body
--type=<type>	feat	Commit type prefix

Single commit flow

1. Service selection — if not provided as an argument, an interactive arrow-key selector is shown
2. Topic — if --topic is not provided, you're prompted with a live word counter (limit: 10 words). If you exceed the limit, the topic is trimmed automatically
3. Message — optional extended commit body
4. Protected branch check — if on main/master/staging, a new branch is auto-created (e.g., feat(frontend)/add-auth) before committing
5. Stage & commit — all changed files for the selected service are staged and committed

Multi-service commit loop

After each commit:

1. Checks for remaining uncommitted changes
2. Shows a summary of remaining changes grouped by service:

   Remaining changes:
     backend (2 files)
     docs (1 file)
   
   Commit another service? (yes / no)

3. If yes — prompts for a new service, topic, and message (each commit is independent)
4. If no — exits
5. If there are no more changes — exits automatically with "No more changes to commit"

Key behaviors:

• The protected branch check only runs once (first commit)
• If a selected service has no changes, a warning is shown and the loop continues
• Each subsequent commit defaults to feat type
• CLI flags (--topic, -m, --type) only apply to the first commit

Commit message format

type(service): topic

message (optional)

Examples:

• feat(frontend): add avatar upload
• fix(backend): handle null avatar url\n\ncheck for missing profile before download
• docs: update cli documentation (root service omits parentheses)

---

Diff

gb diff [service]

Shows the git diff, optionally scoped to a service.

Usage	Behavior
gb diff	git diff --stat (summary of all changes)
gb diff backend	Full diff for backend/ only
gb diff root	Full diff for root-level files (excludes all service directories)

---

Push

gb push [--force]

Pushes the current branch to origin.

Options:

Flag	Description
--force	Force push with --force-with-lease (safe force push)

On first push (no upstream set), automatically runs git push -u origin <branch>.

---

Run

gb run <service> <script>

Runs a package.json script in a service directory using Bun.

Examples:

gb run backend test         # runs "bun run test" in backend/
gb run frontend lint        # runs "bun run lint" in frontend/

Inherits stdin/stdout/stderr, so interactive scripts work. The exit code from the script is propagated.

---

Help

gb help
gb --help
gb -h

Displays help text loaded from command/help.json. Shows all commands, their options, available services, and usage examples.