Configuration

Customize ClaudeKit CLI behavior with config files, environment variables, and project-specific settings.

Configuration Files

ClaudeKit CLI uses multiple configuration files at different levels.

Global CLI Config

Location: ~/.claudekit/config.json

Purpose: Store CLI defaults and authentication

Structure:

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

Auto-created: Yes, on first run

Fields:

Project Config

Location (Local): .claude/.ck.json Location (Global): ~/.claude/.ck.json

Purpose: Store project-specific folder configuration

Structure:

{
  "folders": {
    "docs": "documentation",
    "plans": "planning"
  }
}

Auto-created: When using custom folder names

Fields:

ClaudeKit Metadata

Location (Local): .claude/metadata.json Location (Global): ~/.claude/metadata.json

Purpose: Track installation version and ownership

Structure (Single Kit):

{
  "name": "ClaudeKit Engineer",
  "version": "1.17.0",
  "installedAt": "2025-01-15T10:30:00.000Z",
  "mode": "local",
  "files": [
    {
      "path": "agents/planner/agent.json",
      "hash": "sha256-abc123...",
      "ownership": "ck",
      "installedVersion": "1.17.0"
    }
  ]
}

Structure (Multi-Kit):

{
  "version": "1.17.0",
  "installedAt": "2025-01-15T10:30:00.000Z",
  "mode": "local",
  "kits": {
    "engineer": {
      "name": "ClaudeKit Engineer",
      "version": "1.17.0",
      "installedAt": "2025-01-15T10:30:00.000Z",
      "files": [ /* file tracking */ ]
    },
    "marketing": {
      "name": "ClaudeKit Marketing",
      "version": "1.5.0",
      "installedAt": "2025-01-16T14:20:00.000Z",
      "files": [ /* file tracking */ ]
    }
  }
}

Auto-created: Yes, by ck new or ck init

Fields:

Environment Variables

Configure CLI behavior via environment variables.

Authentication

GITHUB_TOKEN

Purpose: GitHub personal access token for API authentication

Fallback order:

1. GitHub CLI (gh auth token)
2. GITHUB_TOKEN environment variable
3. Config file (~/.claudekit/config.json)
4. OS keychain
5. User prompt

Usage:

export GITHUB_TOKEN=ghp_abc123...
ck new

Note: GitHub CLI (gh auth login) is recommended over PAT.

Behavior

CI

Purpose: Detect CI/CD environment, enable non-interactive mode

Values: "true" or "false"

Usage:

CI=true ck init --release v1.16.0

Effect:

• Disables interactive prompts
• Requires explicit --release flag for version selection
• Skips confirmation prompts

NON_INTERACTIVE

Purpose: Force non-interactive mode

Values: "true" or "false"

Usage:

NON_INTERACTIVE=true ck new --kit engineer --dir ./project

Effect: Same as CI=true

NO_UPDATE_NOTIFIER

Purpose: Disable update notifications

Values: "1" or any truthy value

Usage:

export NO_UPDATE_NOTIFIER=1
ck --version  # No update notification shown

Permanent:

# Add to ~/.bashrc or ~/.zshrc
echo 'export NO_UPDATE_NOTIFIER=1' >> ~/.bashrc

CLAUDEKIT_VERBOSE

Purpose: Enable verbose logging globally

Values: "1" or "true"

Usage:

CLAUDEKIT_VERBOSE=1 ck new

Effect: Same as --verbose flag on all commands

Caching

CK_CACHE_TTL

Purpose: Set cache time-to-live in seconds

Default: 3600 (1 hour)

Usage:

# Cache for 2 hours
CK_CACHE_TTL=7200 ck versions

# Disable caching (always fetch fresh)
CK_CACHE_TTL=0 ck versions

# Cache for 30 minutes (permanent)
export CK_CACHE_TTL=1800

What’s cached:

• GitHub release data
• Version check results

Cache locations:

• Releases: ~/.claudekit/cache/releases/
• Version checks: ~/.claudekit/cache/version-check.json

Command-Line Defaults

Set defaults to avoid repetitive flags.

Kit Default

Set default kit for ck new and ck init:

Via config file:

Edit ~/.claudekit/config.json:

{
  "defaults": {
    "kit": "engineer"
  }
}

Via command:

# First run with --kit flag
ck new --kit engineer

# Saves to config, future runs use it
ck new  # Uses engineer by default

Directory Default

Set default target directory:

Via config file:

{
  "defaults": {
    "dir": "~/projects"
  }
}

Effect:

ck new  # Creates project in ~/projects instead of current dir

Custom Folder Names

Use custom names for docs/ and plans/ directories.

Per-Project Configuration

Set during creation:

ck new --docs-dir documentation --plans-dir planning

Set during update:

ck init --docs-dir documentation --plans-dir planning

What happens:

1. Folder names changed in file system
2. All references updated in workflow files
3. Configuration saved to .claude/.ck.json
4. Future updates preserve custom names

Configuration File

Location: .claude/.ck.json

Structure:

{
  "folders": {
    "docs": "documentation",
    "plans": "planning"
  }
}

Read by: ck init during updates

Protected File Patterns

Files matching these patterns are never overwritten during updates.

Environment Files

• .env
• .env.local
• .env.*.local (e.g., .env.production.local)

Credential Files

• *.key (private keys)
• *.pem (certificates)
• *.p12, *.pfx (PKCS12 files)

User Configuration

• settings.json
• settings.local.json
• CLAUDE.md (global mode only)

Build Artifacts

• node_modules/**
• .git/**
• dist/**
• build/**

Custom Exclude Patterns

Add your own patterns:

ck new --exclude "*.log" --exclude "temp/**"
ck init --exclude "secrets/**"

Platform-Specific Paths

Configuration locations vary by platform.

macOS/Linux

Windows

Configuration Examples

Minimal Setup

Basic configuration for quick start:

{
  "defaults": {
    "kit": "engineer"
  }
}

Team Configuration

Shared settings for team projects:

{
  "defaults": {
    "kit": "engineer",
    "dir": "."
  }
}

Team workflow:

1. Team lead sets defaults
2. Team members use same config
3. Consistent project structure

CI/CD Configuration

Optimized for automation:

# .github/workflows/setup.yml
env:
  CI: true
  NO_UPDATE_NOTIFIER: 1
  CK_CACHE_TTL: 0

steps:
  - name: Install ClaudeKit
    run: ck init --yes --release v1.16.0 --skip-setup

Development vs Production

Development:

# Use beta versions
ck new --beta --install-skills

Production:

# Pin stable version
ck new --release v1.16.0

Debugging Configuration

View Current Config

# View global config
cat ~/.claudekit/config.json

# View project config
cat .claude/.ck.json

# View metadata
cat .claude/metadata.json

Validate Configuration

# Run health check
ck doctor

# Verbose mode for details
ck doctor --verbose

Reset Configuration

Reset CLI config:

rm ~/.claudekit/config.json
ck new  # Will recreate with prompts

Reset project config:

rm .claude/.ck.json
ck init  # Will use defaults

Best Practices

Version Pinning

For production projects:

# Pin to specific stable version
ck new --release v1.16.0

# Document in README
echo "ClaudeKit Version: 1.16.0" >> README.md

Team Synchronization

Keep team on same CLI version:

# In team docs
npm install -g claudekit-cli@3.10.1

# Or package.json (local install)
{
  "devDependencies": {
    "claudekit-cli": "3.10.1"
  }
}

Credentials Security

Never commit credentials:

# Add to .gitignore
echo ".env" >> .gitignore
echo ".env.local" >> .gitignore
echo "*.key" >> .gitignore

# Use environment variables in CI
# Set GITHUB_TOKEN in CI secrets

Cache Management

Clear cache periodically:

# Clear release cache
rm -rf ~/.claudekit/cache/releases/

# Clear version check cache
rm -rf ~/.claudekit/cache/version-check.json

# Or set lower TTL
export CK_CACHE_TTL=1800  # 30 minutes

Troubleshooting Configuration

”Config file not found”

Normal behavior - Config is created on first run.

To pre-create:

mkdir -p ~/.claudekit
echo '{"defaults":{"kit":"engineer"}}' > ~/.claudekit/config.json

“Invalid JSON in config file”

Fix:

# Validate JSON
cat ~/.claudekit/config.json | jq .

# If invalid, recreate
rm ~/.claudekit/config.json
ck new  # Recreates with valid JSON

“Permission denied” on config file

Linux/macOS:

chmod 600 ~/.claudekit/config.json

Windows:

Run as administrator or check file permissions in Properties.

Next Steps

After configuring:

1. Test configuration:

ck doctor

2. Create a project:

ck new

3. Verify settings:

cat .claude/metadata.json

Related Commands

• ck doctor - Validate configuration
• ck new - Create project with config
• ck init - Update project preserving config
• Installation - Initial setup