CLI Installation

Install ClaudeKit CLI (ck) to download and manage ClaudeKit starter kits from private GitHub repository releases.

Prerequisites

Before installing, ensure you have:

Verify installations:

node --version  # Should be v18.0.0+
npm --version   # Should be 9.0.0+
git --version   # Any recent version

Install CLI

npm install -g claudekit-cli

This installs the ck command globally, available from any directory.

Verify Installation

ck --version

Expected output:

1.2.1

View help:

ck --help

Output:

ClaudeKit CLI v1.2.1

Usage:
  ck <command> [options]

Commands:
  new       Create new project from latest ClaudeKit release
  update    Update existing project to latest version
  versions  List available ClaudeKit releases

Options:
  --version, -v   Show version number
  --help, -h      Show help

Examples:
  ck new --kit engineer
  ck update
  ck versions --kit engineer

For more info: https://docs.claudekit.cc

GitHub Authentication

ClaudeKit CLI requires GitHub authentication to download from private repositories.

Authentication Methods

The CLI uses multi-tier authentication with automatic fallback:

  1. GitHub CLI - gh auth token (if authenticated)
  2. Environment Variable - GITHUB_TOKEN or GH_TOKEN
  3. OS Keychain - Stored token
  4. User Prompt - Interactive prompt (with secure storage option)

Install and authenticate with GitHub CLI:

macOS:

brew install gh

Windows:

winget install GitHub.cli

Linux (Ubuntu/Debian):

curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install gh

Authenticate:

gh auth login

Follow prompts:

  1. Select “GitHub.com”
  2. Select “HTTPS”
  3. Choose “Login with web browser”
  4. Copy one-time code
  5. Complete authentication in browser

Verify:

gh auth status

Option 2: Environment Variable

Create a GitHub Personal Access Token (PAT):

  1. Go to GitHub Settings → Developer settings → Personal access tokens
  2. Click “Generate new token (classic)”
  3. Give it a name: “ClaudeKit CLI”
  4. Select scopes: repo (Full control of private repositories)
  5. Click “Generate token”
  6. Copy the token (starts with ghp_)

Set environment variable:

macOS/Linux (Bash/Zsh):

echo 'export GITHUB_TOKEN=ghp_your_token_here' >> ~/.bashrc
# or ~/.zshrc for Zsh
source ~/.bashrc

Windows (PowerShell):

[System.Environment]::SetEnvironmentVariable('GITHUB_TOKEN', 'ghp_your_token_here', 'User')

Verify:

echo $GITHUB_TOKEN  # Should show your token

Option 3: Interactive Prompt

If no authentication is found, the CLI will prompt you:

GitHub authentication required.

Please enter your GitHub Personal Access Token (PAT):
> ghp_your_token_here

Would you like to store this token securely in your OS keychain? (y/n)
> y

✓ Token stored securely

The token is encrypted and stored in your OS keychain:

  • macOS: Keychain Access
  • Windows: Windows Credential Manager
  • Linux: libsecret

Verify Access

After authentication, verify you can access ClaudeKit repositories:

# List available versions
ck versions --kit engineer

If authentication is successful, you’ll see available releases. If not, you’ll see an error about repository access.

Repository Access

Important: You must purchase a ClaudeKit starter kit from ClaudeKit.cc to access the private repositories.

After purchase:

  1. You’ll be added to the GitHub repository
  2. Your GitHub account gets access to releases
  3. The CLI can download using your authenticated account

Without purchase, you’ll see:

Error: Repository not found or access denied
Please purchase a ClaudeKit kit at https://claudekit.cc

Configuration

ClaudeKit CLI stores configuration in ~/.claudekit/config.json:

{
  "github": {
    "token": "stored_in_keychain"
  },
  "defaults": {
    "kit": "engineer",
    "dir": "."
  }
}

Note: The actual token is stored in your OS keychain, not in the config file.

Update CLI

Keep the CLI updated for latest features:

npm update -g claudekit-cli

Check installed version:

ck --version

Uninstall

Remove ClaudeKit CLI:

npm uninstall -g claudekit-cli

Remove configuration (optional):

rm -rf ~/.claudekit

Troubleshooting

Command not found: ck

Problem: Terminal doesn’t recognize ck command

Solutions:

  1. Restart terminal - Sometimes PATH needs refresh

  2. Check installation:

    npm list -g claudekit-cli

  3. Verify npm global bin in PATH:

    npm config get prefix

    Add to PATH if needed:

    export PATH="$PATH:$(npm config get prefix)/bin"

  4. Reinstall:

    npm uninstall -g claudekit-cli
npm install -g claudekit-cli

Authentication failed

Problem: “Authentication failed” or “Repository not found”

Solutions:

  1. Check GitHub authentication:

    gh auth status

    If not authenticated:

    gh auth login

  2. Verify token has repo scope:

  3. Try environment variable:

    export GITHUB_TOKEN=ghp_your_token
ck versions

  4. Verify repository access:

    • Ensure you purchased a ClaudeKit kit
    • Check you can access the repository on GitHub

Permission denied

Problem: Cannot install globally

Solutions:

  1. Use npx (no installation needed):

    npx claudekit-cli new --kit engineer

  2. Fix npm permissions:

    mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
npm install -g claudekit-cli

  3. Use sudo (not recommended):

    sudo npm install -g claudekit-cli

Download fails

Problem: “Failed to download release”

Solutions:

  1. Check internet connection

  2. Verify authentication:

    gh auth status

  3. Try with verbose logging:

    ck new --kit engineer --verbose

  4. Check GitHub status:

Next Steps

Now that the CLI is installed:

  1. Create a new project - ck new command
  2. Browse available versions - Run ck versions
  3. Start developing - Follow Getting Started

Need Help?

Ready to start? Run ck new --kit engineer to create your first project.