Skip to main content

​
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

Comprehensive Analysis

Deep analysis of project structure, dependencies, and code quality with intelligent insights

Safe Modifications

AST-based operations that preserve code integrity during refactoring and modifications

AI Integration

Structured JSON output perfect for AI assistants and automated operations

Multi-Language Support

Works with JavaScript, TypeScript, Python, and more with framework detection

​
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: 
npm install -g initrepo-cli
Installs the CLI globally on your system for easy access from any directory.

​
Method 2: Docker Installation

# 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

# docker-compose.yml
version: '3.8'
services:
  initrepo:
    image: initrepo/cli:latest
    volumes:
      - .:/workspace
      - ~/.initrepo:/root/.initrepo
    working_dir: /workspace
    command: analyze

# 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'
      "

​
Method 3: Package Managers

# 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

​
Initial Setup & Configuration

After installation, set up your InitRepo CLI environment:

​
Step 1: Verify Installation

1

Check Version

initrepo-cli --version
This should display the CLI version and confirm successful installation.
2

View Help

initrepo-cli --help
Shows all available commands and options.
3

Test Basic Functionality

# Create a test directory
mkdir test-project && cd test-project

# Basic analysis (works without configuration)
initrepo-cli --help

​
Step 2: Initial Configuration

# Initialize default configuration
initrepo-cli --init

# This creates .initrepoignore file for customizing analysis scope
cat .initrepoignore
Create a custom .initrepoignore file:
# Exclude common directories
node_modules/
.git/
dist/
build/

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

# Exclude specific files
.env
.env.local

​
Step 3: Environment Variables (Optional)

Configure environment variables for advanced usage: 
# 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

# 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

# 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

# Complexity analysis
initrepo-cli analyze-complexity --threshold=10

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

# Dependencies analysis
initrepo-cli deps --format=markdown

​
Troubleshooting Installation

​
Common Issues

# 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

# 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

# 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

# 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

# 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

# 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

​
Getting Help

Built-in Help

# General help
initrepo-cli --help

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

# Version information
initrepo-cli --version

Debug Information

# Enable verbose logging
export DEBUG=initrepo:*

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

# Test basic functionality
initrepo-cli --help

​
Updating InitRepo CLI

Keep your CLI up to date with the latest features and improvements: 
# Update global installation
npm update -g initrepo-cli

# Check installed version
npm list -g initrepo-cli

# Verify update
initrepo-cli --version

​
Next Steps

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

Commands Reference

Learn about all available CLI commands and their usage options

Advanced Features

Explore CI/CD integration, team workflows, and automation scripts

Quick Start

Get started with your first codebase analysis in 3 minutes

Complete InitRepo Ecosystem

Learn how CLI Tool integrates with Web Platform and MCP Server for complete AI-first development