> ## Documentation Index
> Fetch the complete documentation index at: https://docs.initrepo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Tool Installation & Setup

> Complete installation guide for the InitRepo CLI - a powerful command-line tool for codebase analysis and AI integration

## Introduction to InitRepo CLI

The InitRepo CLI is a comprehensive command-line tool that combines codebase analysis, AI-enhanced operations, and safe code modifications. Whether you're an individual developer, part of a development team, or integrating with CI/CD pipelines, the CLI provides the tools you need to work efficiently with codebases of any size.

### What Makes InitRepo CLI Different

<CardGroup cols={2}>
  <Card title="Comprehensive Analysis" icon="chart-line">
    Deep analysis of project structure, dependencies, and code quality with intelligent insights
  </Card>

  <Card title="Safe Modifications" icon="shield-check">
    AST-based operations that preserve code integrity during refactoring and modifications
  </Card>

  <Card title="AI Integration" icon="brain">
    Structured JSON output perfect for AI assistants and automated operations
  </Card>

  <Card title="Multi-Language Support" icon="code">
    Works with JavaScript, TypeScript, Python, and more with framework detection
  </Card>
</CardGroup>

## System Requirements

Before installing, ensure your system meets these requirements:

* **Node.js**: Version 18.0.0 or higher
* **Operating System**: Windows, macOS, or Linux
* **Memory**: Minimum 512MB RAM (1GB recommended for large projects)
* **Storage**: Minimal requirements (output typically \< 10MB per project)

## Installation Methods

Choose the installation method that best fits your environment:

### Method 1: Global Installation (Recommended)

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install -g initrepo-cli
    ```

    Installs the CLI globally on your system for easy access from any directory.
  </Tab>

  <Tab title="npx (No Installation)">
    ```bash theme={null}
    npx initrepo-cli --help
    ```

    Use InitRepo without installation - perfect for testing or occasional use.
  </Tab>

  <Tab title="From Source">
    ```bash theme={null}
    git clone https://github.com/initrepo/cli.git
    cd cli
    npm install
    npm run start -- --help
    ```

    Build from source for development and customization.
  </Tab>
</Tabs>

### Method 2: Docker Installation

<AccordionGroup>
  <Accordion title="Basic Docker Usage">
    ```bash theme={null}
    # Pull the latest version
    docker pull initrepo/cli:latest

    # Run commands using Docker
    docker run --rm -v $(pwd):/workspace initrepo/cli analyze

    # Create an alias for easier usage
    echo "alias initrepo-cli='docker run --rm -v \$(pwd):/workspace initrepo/cli'" >> ~/.bashrc

    # For Windows PowerShell
    echo "function initrepo-cli { docker run --rm -v \${PWD}:/workspace initrepo/cli \$args }" >> $PROFILE
    ```
  </Accordion>

  <Accordion title="Docker Compose Setup">
    ```yaml theme={null}
    # docker-compose.yml
    version: '3.8'
    services:
      initrepo:
        image: initrepo/cli:latest
        volumes:
          - .:/workspace
          - ~/.initrepo:/root/.initrepo
        working_dir: /workspace
        command: analyze
    ```
  </Accordion>

  <Accordion title="Advanced Docker Configuration">
    ```yaml theme={null}
    # docker-compose.yml with custom configuration
    version: '3.8'
    services:
      initrepo:
        image: initrepo/cli:latest
        volumes:
          - .:/workspace
          - ~/.initrepo:/root/.initrepo
          - ./reports:/workspace/reports
        working_dir: /workspace
        environment:
          - NODE_OPTIONS=--max-old-space-size=4096
          - INITREPO_FORMAT=json
        command: >
          sh -c "
            initrepo-cli validate-structure --format=json > reports/structure.json &&
            initrepo-cli analyze-complexity --format=json > reports/complexity.json &&
            initrepo-cli analyze-imports --format=json > reports/imports.json &&
            echo 'Analysis complete - check reports/ directory'
          "
    ```
  </Accordion>
</AccordionGroup>

### Method 3: Package Managers

<Tabs>
  <Tab title="Homebrew (macOS)">
    ```bash theme={null}
    # Add InitRepo tap
    brew tap initrepo/cli

    # Install CLI
    brew install initrepo-cli

    # Update to latest version
    brew upgrade initrepo-cli

    # Verify installation
    initrepo-cli --version
    ```
  </Tab>

  <Tab title="Chocolatey (Windows)">
    ```bash theme={null}
    # Install InitRepo CLI
    choco install initrepo-cli

    # Update to latest version
    choco upgrade initrepo-cli

    # Verify installation
    initrepo-cli --version
    ```
  </Tab>

  <Tab title="Snap (Linux)">
    ```bash theme={null}
    # Install InitRepo CLI
    sudo snap install initrepo-cli --classic

    # Update to latest version
    sudo snap refresh initrepo-cli

    # Verify installation
    initrepo-cli --version
    ```
  </Tab>
</Tabs>

## Initial Setup & Configuration

After installation, set up your InitRepo CLI environment:

### Step 1: Verify Installation

<Steps>
  <Step title="Check Version">
    ```bash theme={null}
    initrepo-cli --version
    ```

    This should display the CLI version and confirm successful installation.
  </Step>

  <Step title="View Help">
    ```bash theme={null}
    initrepo-cli --help
    ```

    Shows all available commands and options.
  </Step>

  <Step title="Test Basic Functionality">
    ```bash theme={null}
    # Create a test directory
    mkdir test-project && cd test-project

    # Basic analysis (works without configuration)
    initrepo-cli --help
    ```
  </Step>
</Steps>

### Step 2: Initial Configuration

<AccordionGroup>
  <Accordion title="Create Configuration File">
    ```bash theme={null}
    # Initialize default configuration
    initrepo-cli --init

    # This creates .initrepoignore file for customizing analysis scope
    cat .initrepoignore
    ```
  </Accordion>

  <Accordion title="Custom Configuration">
    Create a custom `.initrepoignore` file:

    ```bash theme={null}
    # Exclude common directories
    node_modules/
    .git/
    dist/
    build/

    # Exclude specific file types
    *.log
    *.tmp
    .cache/

    # Exclude specific files
    .env
    .env.local
    ```
  </Accordion>
</AccordionGroup>

### Step 3: Environment Variables (Optional)

Configure environment variables for advanced usage:

```bash theme={null}
# Default output format
export INITREPO_FORMAT=json

# Complexity threshold
export INITREPO_COMPLEXITY_THRESHOLD=20

# Custom output directory
export INITREPO_OUTPUT_DIR=./analysis-results

# Disable colors for CI/CD
export NO_COLOR=1

# Memory optimization for large projects
export NODE_OPTIONS="--max-old-space-size=4096"

# Enable caching
export INITREPO_CACHE_ENABLED=true
export INITREPO_CACHE_DIR=~/.initrepo/cache
```

## First Commands

Get started with basic commands to explore InitRepo CLI capabilities:

### Basic Analysis

<AccordionGroup>
  <Accordion title="Quick Project Analysis">
    ```bash theme={null}
    # Navigate to your project
    cd /path/to/your/project

    # Run basic analysis (creates .initrepo/ directory)
    initrepo-cli

    # View generated analysis
    ls -la .initrepo/
    cat .initrepo/project-structure.md
    ```
  </Accordion>

  <Accordion title="Structure Documentation">
    ```bash theme={null}
    # Generate tree view (human-readable)
    initrepo-cli generate-structure --format=tree

    # Generate JSON format (programmatic)
    initrepo-cli generate-structure --format=json

    # Limited depth analysis
    initrepo-cli generate-structure --max-depth=3
    ```
  </Accordion>

  <Accordion title="Code Quality Analysis">
    ```bash theme={null}
    # Complexity analysis
    initrepo-cli analyze-complexity --threshold=10

    # Import analysis
    initrepo-cli analyze-imports --unused-only

    # Dependencies analysis
    initrepo-cli deps --format=markdown
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting Installation

### Common Issues

<AccordionGroup>
  <Accordion title="Permission Denied Errors">
    ```bash theme={null}
    # For global npm installation issues
    sudo npm install -g initrepo-cli

    # Or fix npm permissions
    sudo chown -R $(whoami) ~/.npm

    # Alternative: Use npx instead
    npx initrepo-cli --version

    # For Windows
    npm install -g initrepo-cli --unsafe-perm=true
    ```
  </Accordion>

  <Accordion title="Node.js Version Issues">
    ```bash theme={null}
    # Check Node.js version
    node --version

    # Update Node.js if needed
    # Using nvm (recommended)
    nvm install 18
    nvm use 18

    # Using fnm (alternative)
    fnm install 18
    fnm use 18

    # Verify compatibility
    initrepo-cli --version
    ```
  </Accordion>

  <Accordion title="Network and Cache Issues">
    ```bash theme={null}
    # Clear npm cache
    npm cache clean --force

    # Try with different registry
    npm install -g initrepo-cli --registry https://registry.npmjs.org/

    # Test connection
    curl -I https://registry.npmjs.org/initrepo-cli

    # Use different npm mirror
    npm config set registry https://registry.npmmirror.com
    ```
  </Accordion>

  <Accordion title="Memory Issues with Large Projects">
    ```bash theme={null}
    # Increase Node.js memory limit
    export NODE_OPTIONS="--max-old-space-size=4096"

    # Process large projects in chunks
    initrepo-cli analyze-complexity --chunk-size=100

    # Use specific file patterns
    initrepo-cli analyze --include "src/**/*.js"

    # Limit analysis depth
    initrepo-cli generate-structure --max-depth=3
    ```
  </Accordion>

  <Accordion title="Docker Installation Issues">
    ```bash theme={null}
    # Check Docker version
    docker --version

    # Pull latest image
    docker pull initrepo/cli:latest

    # Test Docker installation
    docker run --rm initrepo/cli --version

    # Check volume mounting
    docker run --rm -v $(pwd):/workspace initrepo/cli --help
    ```
  </Accordion>

  <Accordion title="PATH Issues">
    ```bash theme={null}
    # Check if CLI is in PATH
    which initrepo-cli

    # Add npm global bin to PATH
    export PATH="$(npm config get prefix)/bin:$PATH"

    # For Windows
    echo $PATH
    # Should include: %APPDATA%\npm

    # Restart terminal/command prompt
    ```
  </Accordion>
</AccordionGroup>

### Getting Help

<CardGroup cols={2}>
  <Card title="Built-in Help" icon="question-mark">
    ```bash theme={null}
    # General help
    initrepo-cli --help

    # Command-specific help
    initrepo-cli analyze --help

    # Version information
    initrepo-cli --version
    ```
  </Card>

  <Card title="Debug Information" icon="bug">
    ```bash theme={null}
    # Enable verbose logging
    export DEBUG=initrepo:*

    # Run with debug output
    initrepo-cli analyze --verbose

    # Test basic functionality
    initrepo-cli --help
    ```
  </Card>
</CardGroup>

## Updating InitRepo CLI

Keep your CLI up to date with the latest features and improvements:

<Tabs>
  <Tab title="npm Update">
    ```bash theme={null}
    # Update global installation
    npm update -g initrepo-cli

    # Check installed version
    npm list -g initrepo-cli

    # Verify update
    initrepo-cli --version
    ```
  </Tab>

  <Tab title="Docker Update">
    ```bash theme={null}
    # Pull latest image
    docker pull initrepo/cli:latest

    # Or use specific version tags
    docker pull initrepo/cli:v1.2.3

    # Verify update
    docker run --rm initrepo/cli:latest --version
    ```
  </Tab>
</Tabs>

## Next Steps

Now that you have InitRepo CLI installed, explore its powerful capabilities:

<CardGroup cols={3}>
  <Card title="Commands Reference" icon="terminal" href="/cli/commands">
    Learn about all available CLI commands and their usage options
  </Card>

  <Card title="Advanced Features" icon="rocket" href="/cli/advanced">
    Explore CI/CD integration, team workflows, and automation scripts
  </Card>

  <Card title="Quick Start" icon="play" href="/quickstart#cli-tool-quickstart">
    Get started with your first codebase analysis in 3 minutes
  </Card>
</CardGroup>

<Card title="Complete InitRepo Ecosystem" icon="globe" href="/platform/overview">
  Learn how CLI Tool integrates with Web Platform and MCP Server for complete AI-first development
</Card>