ba-kit-cli

CLI tool for scaffolding BA-Kit into your projects.

Installation

npm install -g ba-kit-cli

Quick Start

Create New Project with BA-Kit

# Create new project directory and initialize BA-Kit
ba-kit new my-project

Initialize Existing Project

# Initialize in current directory
ba-kit init

# Initialize in specific directory
ba-kit init ./my-project

# Force overwrite existing installation
ba-kit init --force

# Use specific branch
ba-kit init --branch develop

Commands

ba-kit new

Create new project directory with BA-Kit initialized.

ba-kit new my-project          # Create and initialize project
ba-kit new my-project --force  # Overwrite existing directory
ba-kit new my-project --branch develop  # Use specific branch

Options:

• -f, --force - Overwrite existing directory
• -b, --branch <branch> - Branch to use (default: main)

ba-kit init [path]

Initialize BA-Kit in current or specified directory.

ba-kit init                 # Initialize in current directory
ba-kit init ./my-project    # Initialize in specific directory
ba-kit init --force         # Overwrite existing .agent/ folder
ba-kit init --branch develop  # Use develop branch
ba-kit init --local /path/to/ba-kit  # Use local source

Options:

• -f, --force - Overwrite existing .agent/ folder
• -b, --branch <branch> - Branch to use (default: main)
• -l, --local <path> - Use local ba-kit source instead of GitHub

ba-kit status

Show BA-Kit installation status and check for modifications.

ba-kit status         # Show installation status
ba-kit status --remote  # Check against remote for updates

Options:

• --remote - Check against remote for updates

ba-kit update

Update BA-Kit to latest version with conflict resolution.

ba-kit update              # Interactive update with conflict resolution
ba-kit update --yes        # Auto-accept non-conflicting updates
ba-kit update --dry-run    # Preview changes without applying
ba-kit update --local /path/to/ba-kit  # Use local source

Options:

• -y, --yes - Auto-accept non-conflicting updates
• --dry-run - Show changes without applying
• -l, --local <path> - Use local ba-kit source

ba-kit restore [file]

Restore modified files to original version.

ba-kit restore                        # Interactive file selection
ba-kit restore skills/core/planning.md  # Restore specific file
ba-kit restore --all                  # Restore all modified files
ba-kit restore --all --yes            # Restore all without confirmation
ba-kit restore --local /path/to/ba-kit  # Use local source

Options:

• -a, --all - Restore all modified files
• -y, --yes - Skip confirmation prompt
• -l, --local <path> - Use local ba-kit source

ba-kit cache

Manage download cache for BA-Kit archives.

ba-kit cache          # Show cache information
ba-kit cache --clear  # Clear the download cache

Options:

• --clear - Clear the download cache

ba-kit completion

Generate shell completion script for bash, zsh, or fish.

# Bash
ba-kit completion bash >> ~/.bashrc

# Zsh
ba-kit completion zsh > ~/.zsh/completions/_ba-kit

# Fish
ba-kit completion fish > ~/.config/fish/completions/ba-kit.fish

Supported shells: bash, zsh, fish

Global Options

These options work with all commands:

ba-kit -V           # Display version
ba-kit --version    # Display version
ba-kit -h           # Display help
ba-kit --help       # Display help
ba-kit -v           # Enable verbose output
ba-kit --verbose    # Enable verbose output
ba-kit -q           # Suppress non-essential output
ba-kit --quiet      # Suppress non-essential output
ba-kit --json       # Output in JSON format (for scripting)

| Option | Description | |--------|-------------| | -V, --version | Display version | | -h, --help | Display help | | -v, --verbose | Enable verbose output | | -q, --quiet | Suppress non-essential output | | --json | Output in JSON format (for scripting) |

How It Works

BA-Kit CLI uses a manifest-based approach to track files:

1. Init: Downloads BA-Kit from GitHub, copies files to .agent/, creates manifest with SHA-256 hashes
2. Status: Compares current file hashes against manifest to detect modifications
3. Update: Downloads latest version, detects conflicts between local changes and upstream updates
4. Restore: Downloads original files and restores modified files with automatic backups

Manifest

The manifest file (.agent/.ba-kit-manifest.json) tracks:

• Installed version
• Branch used
• File hashes (original and current)
• Installation/update timestamps

Conflict Resolution

When both local and upstream files have changed, the update command offers:

• Keep local: Preserve your modifications
• Overwrite: Accept upstream changes
• View diff: Compare changes side-by-side
• Backup & overwrite: Save local copy before updating

Development

# Clone the repo
git clone https://github.com/anthropics/ba-kit-cli.git
cd ba-kit-cli

# Install dependencies
npm install

# Link for local development
npm link

# Test with local ba-kit source
ba-kit init --local /path/to/ba-kit

License

MIT