installation.md

📥 Installation Guide

Get up and running with Codebase Interface CLI in minutes!

This guide covers all the ways to install the CLI, from one-line installers to building from source.

🚀 Recommended Installation

One-Line Installation

Linux/macOS:

curl -sSL https://raw.githubusercontent.com/codebase-interface/cli/main/install.sh | bash

Windows (PowerShell):

Invoke-WebRequest -Uri "https://github.com/codebase-interface/cli/releases/latest/download/codebase-interface-windows-amd64.exe" -OutFile "codebase-interface.exe"
# Add to PATH or move to a directory in your PATH

✅ Verify Installation

# Check if installed correctly
codebase-interface version
# Or use the short alias
cbi version

You should see output like:

Codebase Interface CLI v1.0.0

📦 Package Managers

Homebrew (macOS/Linux)

# Add the tap
brew tap codebase-interface/cli

# Install the CLI
brew install codebase-interface

# Verify installation
cbi version

Benefits:

✅ Automatic updates with brew upgrade
✅ Easy uninstall with brew uninstall codebase-interface
✅ Manages dependencies automatically

Chocolatey (Windows)

# Install the CLI
choco install codebase-interface

# Verify installation
cbi version

Benefits:

✅ Windows-native package management
✅ Automatic PATH configuration
✅ Easy updates with choco upgrade codebase-interface

Go Install

If you have Go installed:

go install github.com/codebase-interface/cli/cmd/codebase-interface@latest

# Verify installation (ensure $GOPATH/bin is in your PATH)
cbi version

Benefits:

✅ Always gets the latest version
✅ Works on any platform with Go
✅ Minimal dependencies

🐳 Container Usage

Docker

One-time validation:

# Validate current directory
docker run --rm -v $(pwd):/workspace ghcr.io/codebase-interface/cli:latest validate

# Create configuration file
docker run --rm -v $(pwd):/workspace ghcr.io/codebase-interface/cli:latest init-config basic

Interactive session:

# Launch interactive shell with CLI available
docker run --rm -it -v $(pwd):/workspace ghcr.io/codebase-interface/cli:latest bash

# Inside container, use CLI normally
cbi validate
cbi init-config open-source

CI/CD Integration:

# GitHub Actions example
- name: Validate Codebase
  run: |
    docker run --rm -v ${{ github.workspace }}:/workspace \
      ghcr.io/codebase-interface/cli:latest validate --output json

Benefits:

✅ No local installation required
✅ Consistent environment across teams
✅ Perfect for CI/CD pipelines
✅ Isolated from host system

💾 Pre-built Binaries

Download directly from GitHub Releases:

Download Commands

Linux (x64):

curl -L https://github.com/codebase-interface/cli/releases/latest/download/codebase-interface-linux-amd64 -o codebase-interface
chmod +x codebase-interface
sudo mv codebase-interface /usr/local/bin/

macOS (Intel):

curl -L https://github.com/codebase-interface/cli/releases/latest/download/codebase-interface-darwin-amd64 -o codebase-interface
chmod +x codebase-interface
sudo mv codebase-interface /usr/local/bin/

macOS (Apple Silicon):

curl -L https://github.com/codebase-interface/cli/releases/latest/download/codebase-interface-darwin-arm64 -o codebase-interface
chmod +x codebase-interface
sudo mv codebase-interface /usr/local/bin/

Windows:

Download codebase-interface-windows-amd64.exe
Rename to codebase-interface.exe
Add to your PATH or place in a directory that's already in PATH

Create Short Alias

# Linux/macOS - Add to ~/.bashrc or ~/.zshrc
echo 'alias cbi="codebase-interface"' >> ~/.bashrc
source ~/.bashrc

# Or create a symlink
sudo ln -sf /usr/local/bin/codebase-interface /usr/local/bin/cbi

🛠️ Build from Source

Prerequisites

Go 1.21+ - Install Go
Git - For cloning the repository
Task (optional) - Install Task for easier building

Build Steps

# Clone the repository
git clone https://github.com/codebase-interface/cli.git
cd cli

# Option 1: Using Task (recommended)
task build

# Option 2: Using Go directly
go build -o bin/codebase-interface ./cmd/codebase-interface

# Option 3: Install globally
task install
# Or: go install ./cmd/codebase-interface

Development Build

# Build for development with debug info
task build

# Run tests
task test

# Build for all platforms
task build:all

# Package for distribution
task package

🔧 Post-Installation Setup

1. Verify Installation

# Check version and available commands
cbi --help
cbi version

2. Create Your First Configuration

# Navigate to your project
cd /path/to/your/project

# Create a basic configuration
cbi init-config basic

# Validate the configuration
cbi validate-config

# Run your first validation
cbi validate

3. Customize for Your Project

# Try different presets
cbi init-config open-source  # For open source projects
cbi init-config go-project   # For Go projects
cbi init-config strict       # For production codebases

# Edit the configuration file
nano .codebase-validation.yml

🚨 Troubleshooting

Command Not Found

Issue: cbi: command not found

Solutions:

Check PATH: Ensure the installation directory is in your PATH
```
echo $PATH
which cbi
```

Reinstall using package manager:

# Homebrew
brew reinstall codebase-interface

# Or try the installation script again
curl -sSL https://raw.githubusercontent.com/codebase-interface/cli/main/install.sh | bash

Manual PATH addition:

# Add to ~/.bashrc or ~/.zshrc
export PATH="/usr/local/bin:$PATH"
source ~/.bashrc

Permission Denied

Issue: Permission denied when running installation

Solution:

# Use sudo for system-wide installation
sudo curl -sSL https://raw.githubusercontent.com/codebase-interface/cli/main/install.sh | bash

# Or install to user directory
curl -sSL https://raw.githubusercontent.com/codebase-interface/cli/main/install.sh | bash -s -- ~/bin

Docker Issues

Issue: Docker permission errors

Solution:

# Add user to docker group (Linux)
sudo usermod -aG docker $USER
# Then log out and back in

# Or use sudo
sudo docker run --rm -v $(pwd):/workspace ghcr.io/codebase-interface/cli:latest validate

🔄 CI/CD Integration

GitHub Actions

Add validation to your GitHub workflow:

name: Validate Codebase

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  validate:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout code
      uses: actions/checkout@v4
      
    - name: Validate codebase structure
      run: |
        docker run --rm -v ${{ github.workspace }}:/workspace \
          ghcr.io/codebase-interface/cli:latest validate --output json

GitLab CI

Add to your .gitlab-ci.yml:

validate_codebase:
  image: ghcr.io/codebase-interface/cli:latest
  stage: test
  script:
    - codebase-interface validate --output json
  rules:
    - if: $CI_PIPELINE_SOURCE == "push"
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Jenkins Pipeline

pipeline {
    agent any
    
    stages {
        stage('Validate Codebase') {
            steps {
                script {
                    docker.image('ghcr.io/codebase-interface/cli:latest').inside('-v ${WORKSPACE}:/workspace') {
                        sh 'codebase-interface validate --output json'
                    }
                }
            }
        }
    }
}

Azure Pipelines

trigger:
- main
- develop

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: Docker@2
  displayName: 'Validate Codebase'
  inputs:
    command: 'run'
    arguments: '--rm -v $(Build.SourcesDirectory):/workspace ghcr.io/codebase-interface/cli:latest validate --output json'

📱 Platform-Specific Notes

macOS

Gatekeeper: First run might require going to Security & Privacy settings to allow the binary
Homebrew recommended for easiest installation and updates
Apple Silicon users should use the ARM64 binary for better performance

Windows

PowerShell recommended for best experience
Windows Defender might flag the binary initially - this is normal for new binaries
Chocolatey provides the smoothest Windows experience
WSL users can use the Linux installation methods

Linux

Package managers vary - the installation script auto-detects your system
Snap package coming soon for Ubuntu users
AppImage available for distribution-agnostic installation

🎯 Next Steps

After installation, check out:

Usage Guide - Learn the core commands and workflows
Configuration Guide - Customize validation rules
Examples - Copy-paste configurations for your project type

💡 Tip: Bookmark this page! Installation is just the beginning of your journey toward better codebase organization.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

📥 Installation Guide

🚀 Recommended Installation

One-Line Installation

✅ Verify Installation

📦 Package Managers

Homebrew (macOS/Linux)

Chocolatey (Windows)

Go Install

🐳 Container Usage

Docker

💾 Pre-built Binaries

Download Commands

Create Short Alias

🛠️ Build from Source

Prerequisites

Build Steps

Development Build

🔧 Post-Installation Setup

1. Verify Installation

2. Create Your First Configuration

3. Customize for Your Project

🚨 Troubleshooting

Command Not Found

Permission Denied

Docker Issues

🔄 CI/CD Integration

GitHub Actions

GitLab CI

Jenkins Pipeline

Azure Pipelines

📱 Platform-Specific Notes

macOS

Windows

Linux

🎯 Next Steps

FilesExpand file tree

installation.md

Latest commit

History

installation.md

File metadata and controls

📥 Installation Guide

🚀 Recommended Installation

One-Line Installation

✅ Verify Installation

📦 Package Managers

Homebrew (macOS/Linux)

Chocolatey (Windows)

Go Install

🐳 Container Usage

Docker

💾 Pre-built Binaries

Download Commands

Create Short Alias

🛠️ Build from Source

Prerequisites

Build Steps

Development Build

🔧 Post-Installation Setup

1. Verify Installation

2. Create Your First Configuration

3. Customize for Your Project

🚨 Troubleshooting

Command Not Found

Permission Denied

Docker Issues

🔄 CI/CD Integration

GitHub Actions

GitLab CI

Jenkins Pipeline

Azure Pipelines

📱 Platform-Specific Notes

macOS

Windows

Linux

🎯 Next Steps