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

# Installation

> Install KafkaCode on your system

## System Requirements

<CardGroup cols={2}>
  <Card title="Node.js" icon="node">
    Version 14.0.0 or higher
  </Card>

  <Card title="npm" icon="npm">
    Comes with Node.js
  </Card>

  <Card title="Operating System" icon="computer">
    Windows, macOS, or Linux
  </Card>

  <Card title="Disk Space" icon="hard-drive">
    \~50MB for installation
  </Card>
</CardGroup>

## Installation Methods

<Tabs>
  <Tab title="npm (Global)">
    Install KafkaCode globally to use it anywhere on your system:

    ```bash theme={null}
    npm install -g kafkacode
    ```

    Verify the installation:

    ```bash theme={null}
    kafkacode --version
    ```

    <Tip>
      Global installation is recommended if you plan to use KafkaCode across multiple projects.
    </Tip>
  </Tab>

  <Tab title="npx (No Install)">
    Use KafkaCode without installing it globally:

    ```bash theme={null}
    npx kafkacode scan /path/to/project
    ```

    <Info>
      npx downloads and runs the latest version each time. Great for trying it out or occasional use.
    </Info>
  </Tab>

  <Tab title="Project Dependency">
    Add KafkaCode as a dev dependency to your project:

    ```bash theme={null}
    npm install --save-dev kafkacode
    ```

    Then add a script to your `package.json`:

    ```json package.json theme={null}
    {
      "scripts": {
        "scan": "kafkacode scan ./src",
        "scan:verbose": "kafkacode scan ./src --verbose"
      }
    }
    ```

    Run with:

    ```bash theme={null}
    npm run scan
    ```
  </Tab>

  <Tab title="Yarn">
    Install with Yarn package manager:

    ```bash theme={null}
    # Global installation
    yarn global add kafkacode

    # Or as a dev dependency
    yarn add -D kafkacode
    ```

    Verify installation:

    ```bash theme={null}
    kafkacode --version
    ```
  </Tab>
</Tabs>

## Platform-Specific Instructions

<AccordionGroup>
  <Accordion icon="apple" title="macOS">
    ### Using Homebrew (Recommended)

    First, ensure Node.js is installed:

    ```bash theme={null}
    brew install node
    ```

    Then install KafkaCode:

    ```bash theme={null}
    npm install -g kafkacode
    ```

    ### Permissions Issues?

    If you encounter permission errors, use one of these solutions:

    **Option 1**: Use a version manager like nvm (recommended)

    ```bash theme={null}
    # Install nvm
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

    # Install Node.js
    nvm install node

    # Now install KafkaCode
    npm install -g kafkacode
    ```

    **Option 2**: Configure npm to use a different directory

    ```bash theme={null}
    mkdir ~/.npm-global
    npm config set prefix '~/.npm-global'
    echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
    source ~/.zshrc
    npm install -g kafkacode
    ```
  </Accordion>

  <Accordion icon="linux" title="Linux">
    ### Ubuntu/Debian

    ```bash theme={null}
    # Install Node.js and npm
    curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
    sudo apt-get install -y nodejs

    # Install KafkaCode
    sudo npm install -g kafkacode
    ```

    ### Fedora/RHEL/CentOS

    ```bash theme={null}
    # Install Node.js and npm
    curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
    sudo yum install -y nodejs

    # Install KafkaCode
    sudo npm install -g kafkacode
    ```

    ### Using nvm (Recommended for Linux)

    ```bash theme={null}
    # Install nvm
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

    # Restart your terminal or run:
    source ~/.bashrc

    # Install Node.js
    nvm install node

    # Install KafkaCode (no sudo needed)
    npm install -g kafkacode
    ```
  </Accordion>

  <Accordion icon="windows" title="Windows">
    ### Using Node.js Installer (Recommended)

    1. Download Node.js from [nodejs.org](https://nodejs.org/)
    2. Run the installer (.msi file)
    3. Open Command Prompt or PowerShell
    4. Install KafkaCode:

    ```powershell theme={null}
    npm install -g kafkacode
    ```

    ### Using Windows Package Manager (winget)

    ```powershell theme={null}
    # Install Node.js
    winget install OpenJS.NodeJS

    # Install KafkaCode
    npm install -g kafkacode
    ```

    ### Using Chocolatey

    ```powershell theme={null}
    # Install Node.js
    choco install nodejs

    # Install KafkaCode
    npm install -g kafkacode
    ```

    <Warning>
      On Windows, you may need to run your terminal as Administrator for global installations.
    </Warning>
  </Accordion>
</AccordionGroup>

## Verifying Installation

After installation, verify that KafkaCode is working correctly:

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

    Should output: `1.2.0` (or your installed version)
  </Step>

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

    Should display the help menu with available commands
  </Step>

  <Step title="Run Test Scan">
    ```bash theme={null}
    mkdir test-project
    echo "const apiKey = 'AKIAIOSFODNN7EXAMPLE';" > test-project/test.js
    kafkacode scan test-project
    ```

    Should detect the AWS key and display a report
  </Step>
</Steps>

## Updating KafkaCode

Keep KafkaCode up to date to get the latest features and security improvements:

<CodeGroup>
  ```bash npm (Global) theme={null}
  npm update -g kafkacode
  ```

  ```bash npm (Project) theme={null}
  npm update kafkacode
  ```

  ```bash yarn (Global) theme={null}
  yarn global upgrade kafkacode
  ```

  ```bash yarn (Project) theme={null}
  yarn upgrade kafkacode
  ```
</CodeGroup>

## Uninstallation

If you need to remove KafkaCode:

<CodeGroup>
  ```bash npm (Global) theme={null}
  npm uninstall -g kafkacode
  ```

  ```bash npm (Project) theme={null}
  npm uninstall kafkacode
  ```

  ```bash yarn (Global) theme={null}
  yarn global remove kafkacode
  ```

  ```bash yarn (Project) theme={null}
  yarn remove kafkacode
  ```
</CodeGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion icon="triangle-exclamation" title="Command not found">
    If you get `command not found: kafkacode` after installation:

    1. Check your PATH includes npm's global bin directory:
       ```bash theme={null}
       npm config get prefix
       ```

    2. Add npm's bin directory to your PATH:
       ```bash theme={null}
       # For bash
       echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
       source ~/.bashrc

       # For zsh
       echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
       source ~/.zshrc
       ```

    3. Alternatively, use npx:
       ```bash theme={null}
       npx kafkacode scan ./
       ```
  </Accordion>

  <Accordion icon="lock" title="Permission Errors">
    If you encounter EACCES permission errors:

    1. **Never use sudo with npm** - This can cause permission issues

    2. Use nvm (Node Version Manager) instead:
       ```bash theme={null}
       curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
       nvm install node
       npm install -g kafkacode
       ```

    3. Or configure npm to use a different directory (see platform-specific instructions)
  </Accordion>

  <Accordion icon="network-wired" title="Network/Proxy Issues">
    If installation fails due to network issues:

    1. Configure npm proxy:
       ```bash theme={null}
       npm config set proxy http://proxy.company.com:8080
       npm config set https-proxy http://proxy.company.com:8080
       ```

    2. Or disable SSL verification (not recommended for production):
       ```bash theme={null}
       npm config set strict-ssl false
       ```

    3. Clear npm cache:
       ```bash theme={null}
       npm cache clean --force
       npm install -g kafkacode
       ```
  </Accordion>

  <Accordion icon="code" title="Node.js Version Issues">
    If you're running an old version of Node.js:

    1. Check your current version:
       ```bash theme={null}
       node --version
       ```

    2. KafkaCode requires Node.js 14.0.0 or higher

    3. Update Node.js:
       * Using nvm: `nvm install node`
       * Using package manager: Reinstall from [nodejs.org](https://nodejs.org/)
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart Guide" icon="rocket" href="/quickstart">
    Run your first scan in 5 minutes
  </Card>

  <Card title="CLI Options" icon="terminal" href="/usage/cli-options">
    Learn about all available options
  </Card>

  <Card title="CI/CD Integration" icon="code-branch" href="/usage/ci-cd-integration">
    Integrate into your pipeline
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/advanced/troubleshooting">
    Solve common issues
  </Card>
</CardGroup>