JBCT CLI

Command-line tools for Java Backend Coding Technology - formatting, linting, and project management.

Overview

JBCT CLI provides:

Installation

Quick Install (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/siy/jbct-cli/main/install.sh | sh

The installer:

• Verifies Java is installed (JDK 25+ required)
• Downloads latest release from GitHub
• Installs to ~/.jbct/lib/jbct.jar
• Creates wrapper script at ~/.jbct/bin/jbct
• Adds ~/.jbct/bin to PATH in your shell RC file

Custom install location:

JBCT_HOME=/custom/path sh install.sh

Manual Installation

Download jbct.jar from releases and run:

java -jar jbct.jar --help

Build from Source

git clone https://github.com/siy/jbct-cli.git
cd jbct-cli
mvn package -DskipTests
# JAR: jbct-cli/target/jbct.jar

Verify Installation

jbct --version

Commands

format

Format Java source files in-place to JBCT style.

jbct format src/main/java

Options:

Examples:

# Format all Java files
jbct format src/main/java

# Check formatting without modifying (for CI)
jbct format --check src/main/java

# Preview changes without writing
jbct format --dry-run src/main/java

# Format with verbose output
jbct format --verbose src/main/java

Exit codes:

• 0 - All files formatted or already compliant
• 1 - Files need formatting (with --check)

lint

Check code for JBCT compliance using 37 lint rules.

jbct lint src/main/java

Options:

Examples:

# Lint with text output
jbct lint src/main/java

# Lint with JSON output (for tooling)
jbct lint --format json src/main/java

# Lint with SARIF output (for GitHub Code Scanning)
jbct lint --format sarif src/main/java

# Fail on any warning
jbct lint --fail-on-warning src/main/java

Exit codes:

• 0 - All checks passed
• 1 - Lint issues found
• 2 - Internal error (parse failure, etc.)

check

Combined format check and lint (recommended for CI).

jbct check src/main/java

Options:

Examples:

# Full check (format + lint)
jbct check src/main/java

# Strict mode (warnings are errors)
jbct check --fail-on-warning src/main/java

Exit codes:

• 0 - All checks passed
• 1 - Format or lint issues found
• 2 - Internal error

init

Create a new JBCT-compliant project.

jbct init my-project

Options:

Examples:

# Create new project in directory
jbct init my-project

# Initialize current directory
jbct init .

# With custom group ID
jbct init --group-id com.example my-project

# Create Aether slice project
jbct init --slice my-slice

What it creates:

Standard project:

• JBCT-compliant pom.xml
• jbct.toml configuration
• AI tools installed to ~/.claude/

Slice project (--slice):

• @Slice annotated interface with factory method
• Implementation class
• Sample request/response records
• Unit test

update

Update AI tools from coding-technology repository.

jbct update

Options:

Examples:

# Update if new version available
jbct update

# Force update
jbct update --force

# Check for updates only
jbct update --check

upgrade

Self-update JBCT CLI to the latest version.

jbct upgrade

Options:

Examples:

# Check and install latest
jbct upgrade

# Check only
jbct upgrade --check

# Force reinstall
jbct upgrade --force

verify-slice

Validate Aether slice project configuration.

jbct verify-slice

Options:

Examples:

# Validate current directory
jbct verify-slice

# Validate specific directory
jbct verify-slice my-slice

# Strict mode
jbct verify-slice --strict

What it checks:

• Missing pom.xml or slice.class property
• Missing slice-api.properties (annotation processor not run)
• Missing manifest entries

Lint Rules (37 total)

Return Kinds (5 rules)

Value Objects (2 rules)

Exceptions (2 rules)

Naming (2 rules)

Lambda/Composition (4 rules)

Patterns (3 rules)

Style (6 rules)

Logging (2 rules)

Architecture (1 rule)

Static Imports (1 rule)

Utilities (2 rules)

Nesting (1 rule)

Zones (3 rules)

Acronyms (1 rule)

Sealed Types (1 rule)

Slice Architecture (1 rule)

Note: JBCT-SLICE-01 requires slicePackages configuration:

[lint]
slicePackages = ["**.usecase.**"]

Formatter Style

The JBCT formatter enforces consistent style:

Method Chain Alignment

Continuation aligned to receiver:

return ValidRequest.validRequest(request)
                   .async()
                   .flatMap(checkEmail::apply)
                   .flatMap(saveUser::apply);

Argument Alignment

Multi-line arguments aligned to opening paren:

return Result.all(Email.email(raw.email()),
                  Password.password(raw.password()),
                  ReferralCode.referralCode(raw.referral()))
             .map(ValidRequest::new);

Import Grouping

// 1. org.pragmatica.*
import org.pragmatica.lang.Result;
import org.pragmatica.lang.Option;

// 2. java/javax
import java.util.List;

// 3. Third-party
import com.fasterxml.jackson.annotation.JsonProperty;

// 4. Project
import com.example.domain.Email;

// (blank line)

// 5. Static imports (same grouping order)
import static org.pragmatica.lang.Result.all;

Other Rules

• Indentation: 4 spaces, no tabs
• Line length: 120 characters max
• Blank lines: One between methods, none after opening brace

Configuration

JBCT uses jbct.toml for configuration:

[format]
maxLineLength = 120
indentSize = 4
alignChainedCalls = true

[lint]
failOnWarning = false
businessPackages = ["**.usecase.**", "**.domain.**"]
slicePackages = ["**.usecase.**"]  # Required for JBCT-SLICE-01

[lint.rules]
JBCT-RET-01 = "error"
JBCT-STY-01 = "warning"
JBCT-LOG-01 = "off"

Priority Chain

1. CLI arguments (highest)
2. ./jbct.toml (project)
3. ~/.jbct/config.toml (user)
4. Built-in defaults (lowest)

Rule Severity Levels

Suppressing Rules with @SuppressWarnings

Use standard Java @SuppressWarnings annotation to suppress JBCT rules:

// Suppress single rule
@SuppressWarnings("JBCT-RET-01")
public void legacyMethod() {
    // This method won't trigger JBCT-RET-01
}

// Suppress multiple rules
@SuppressWarnings({"JBCT-RET-01", "JBCT-LAM-02"})
public void anotherMethod() {
    // Won't trigger either rule
}

// Suppress all JBCT rules
@SuppressWarnings("all")
public class LegacyAdapter {
    // No JBCT rules checked in this class
}

Scope: Suppression applies to the annotated element and its children:

• On class → suppresses for entire class (all methods)
• On method → suppresses for that method only

CI Integration

GitHub Actions

name: JBCT Check

on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-java@v4
        with:
          java-version: '25'
          distribution: 'temurin'

      - name: Install JBCT CLI
        run: curl -fsSL https://raw.githubusercontent.com/siy/jbct-cli/main/install.sh | sh

      - name: Run JBCT Check
        run: jbct check src/main/java

With Maven Plugin

If using the Maven plugin, CI is simpler:

- uses: actions/setup-java@v4
  with:
    java-version: '25'
    distribution: 'temurin'
    cache: maven

- run: mvn verify -B

With plugin bound to verify phase, mvn verify runs all checks.

Requirements

• Java 25+
• Linux, macOS, or Windows (WSL)

Resources

• AI Tools - Claude Code integration
• Maven Plugin - Build integration
• JBCT Coding Guide - Complete technical reference
• GitHub Repository

Support

If you find this useful, consider sponsoring.

License

Apache 2.0