GitHub
Docs
Installation

Installation

How to install CommitStudio and set up your credentials

Prerequisites

Before installing CommitStudio, make sure you have:

  1. Node.js: Version 18.0.0 or higher installed on your system
  2. Git: Installed and configured on your system
  3. GitHub Repository: A repository on GitHub that you want to analyze
  4. API Credentials:
    • A GitHub personal access token with 'repo' scope
    • An OpenAI API key

Installation Methods

Global Installation (Recommended)

Installing CommitStudio globally allows you to run it from any directory:

Terminal
# Install globally with npm
npm install -g commitstudio

# OR install globally with pnpm
pnpm add -g commitstudio

# OR install globally with yarn
yarn global add commitstudio

After installation, verify it's working:

Terminal
commitstudio --version

Using Without Installation

You can run CommitStudio directly without installing it using npx:

Terminal
npx commitstudio

This approach will download and execute CommitStudio on demand, ensuring you always use the latest version.

Setting Up Credentials

CommitStudio requires authentication with both GitHub and OpenAI. You have several options to provide these credentials:

Environment Variables (Recommended)

Set up environment variables to avoid entering credentials every time:

Terminal
# GitHub personal access token
export GITHUB_TOKEN=your_github_token

# OpenAI API key
export OPENAI_API_KEY=your_openai_api_key

For permanent setup, add these to your shell profile file (.bashrc, .zshrc, etc.).

Interactive Prompt

If credentials aren't found in environment variables, CommitStudio will prompt you to enter them interactively during the first run.

Optional: GitHub OAuth Setup

For a browser-based authentication flow instead of using a personal access token:

  1. Create a GitHub OAuth App at: https://github.com/settings/developers
  2. Set the Authorization callback URL to: https://github.com/devices
  3. Set the Client ID as an environment variable:
Terminal
export GITHUB_CLIENT_ID=your_client_id

GitHub Access Token

CommitStudio requires a GitHub personal access token to:

  • Access repository information
  • Fetch commit details
  • Post comments to commits

Creating a GitHub Token

  1. Go to GitHub Settings > Developer settings > Personal access tokens
  2. Click "Generate new token" (classic)
  3. Give it a descriptive name like "CommitStudio"
  4. Select the repo scope (this grants access to your repositories)
  5. Click "Generate token"
  6. Copy the generated token (you'll only see it once!)

OpenAI API Key

CommitStudio uses OpenAI's API to analyze code. You need an API key with sufficient quota.

Getting an OpenAI API Key

  1. Create an account or sign in at OpenAI's platform
  2. Go to API Keys
  3. Create a new secret key
  4. Give it a name like "CommitStudio"
  5. Copy your API key (you'll only see it once!)

Verifying Your Installation

After installation, verify everything is working correctly:

Terminal
# Check the installed version
commitstudio --version

# View available commands and options
commitstudio --help

Troubleshooting Installation Issues

Node.js Version Error

If you see an error about Node.js version, upgrade Node.js:

Terminal
# Using nvm (Node Version Manager)
nvm install 18
nvm use 18

# OR download the latest version from nodejs.org

Permission Errors

If you encounter permission errors during global installation:

Terminal
# Install with sudo (not recommended)
sudo npm install -g commitstudio

# OR fix npm permissions (recommended)
# https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally

Connection Issues

If CommitStudio can't connect to GitHub or OpenAI:

  1. Verify your internet connection
  2. Check that your API keys are correct
  3. Ensure you don't have a proxy or firewall blocking connections

Next Steps

Now that CommitStudio is installed, you can: