ck new

Create a new ClaudeKit project by downloading the latest or specific version from private GitHub releases.

Synopsis

ck new [options]

Description

The ck new command downloads a ClaudeKit starter kit from private GitHub releases and sets it up in your local directory. This command:

Downloads the specified ClaudeKit release (latest by default)
Extracts files to your target directory
Preserves your existing files (if updating)
Installs dependencies (npm install)
Ready to use immediately

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

Options

—dir

Target directory for the new project.

ck new --dir my-project

Default: Current directory (.)

Examples:

ck new --dir ./my-app
ck new --dir ../projects/new-app
ck new --dir ~/projects/my-app

—kit

Specify which ClaudeKit to download.

ck new --kit engineer

Available kits:

engineer - ClaudeKit Engineer (14 specialized agents)
marketing - ClaudeKit Marketing [Coming Soon]

Default: Interactive prompt if not specified

—version

Download a specific version instead of latest.

ck new --kit engineer --version v1.0.0

Version format: v1.0.0 or 1.0.0

Examples:

ck new --kit engineer --version v1.2.0
ck new --kit engineer --version 1.2.0  # Also works

To see available versions, run:

ck versions --kit engineer

—exclude

Exclude files/directories using glob patterns during project setup.

ck new --exclude "*.log"

Pattern format: Supports standard glob patterns

Examples:

# Single pattern
ck new --exclude "*.log"

# Multiple patterns
ck new --exclude "*.log" --exclude "temp/**" --exclude "cache/**"

# Exclude local config files
ck new --exclude "*.local" --exclude ".env.*"

# Exclude specific directories
ck new --exclude "logs/**" --exclude "coverage/**"

Use cases:

Skip temporary or cache files
Exclude environment-specific configurations
Prevent overwriting custom local files
Reduce download size by excluding unnecessary files

Note: Excluded patterns are applied during file extraction and copying.

—verbose, -v

Enable verbose logging for debugging.

ck new --verbose
ck new -v

Output includes:

HTTP request/response details (tokens sanitized)
File operations (downloads, extractions, copies)
Command execution steps and timing
Error stack traces with full context
Authentication flow details

—log-file

Write logs to a file for sharing or debugging.

ck new --verbose --log-file debug.log

Note: All sensitive data (tokens, credentials) is automatically sanitized in logs.

Interactive Mode

When you run ck new without options, you’ll be prompted:

ck new

Prompts:

? Select a ClaudeKit to download:
❯ engineer - ClaudeKit Engineer (14 specialized agents)
  marketing - ClaudeKit Marketing [Coming Soon]

? Enter target directory (default: current directory):
> my-project

? Select version:
❯ latest (v1.2.1)
  v1.2.0
  v1.1.9
  [... more versions]

Downloading ClaudeKit Engineer v1.2.1...
✓ Downloaded (5.2 MB)
✓ Extracted to my-project
✓ Installing dependencies...
✓ Complete!

Next steps:
  cd my-project
  claude  # Start Claude Code

What Gets Downloaded

When you run ck new, the CLI downloads and extracts:

ClaudeKit Configuration

.claude/
├── config.json           # Project configuration
├── commands/             # 38+ slash commands
│   ├── plan.md
│   ├── cook.md
│   ├── fix-fast.md
│   └── ... (35 more)
├── skills/              # Custom skills
└── workflows/           # Agent workflows
    ├── development-rules.md
    ├── documentation-management.md
    ├── orchestration-protocol.md
    └── primary-workflow.md

Documentation Structure

docs/
├── project-overview-pdr.md
├── code-standards.md
├── codebase-summary.md
├── system-architecture.md
└── deployment-guide.md

Plans Directory

plans/
└── README.md           # Planning documentation

Project Files

.gitignore             # Sensible defaults
README.md              # Getting started guide
package.json           # (if applicable)

Examples

Create in Current Directory

ck new --kit engineer

Downloads ClaudeKit Engineer to current directory.

Create in New Directory

ck new --dir my-app --kit engineer

Creates my-app/ directory and downloads ClaudeKit Engineer.

Download Specific Version

ck new --kit engineer --version v1.0.0

Downloads version 1.0.0 instead of latest.

Check Available Versions First

# List all versions
ck versions --kit engineer

# Then download specific version
ck new --kit engineer --version v1.1.9

Debug Download Issues

ck new --kit engineer --verbose --log-file debug.log

Creates detailed log file for troubleshooting.

Exclude Specific Files

# Exclude log files
ck new --kit engineer --exclude "*.log"

# Exclude multiple patterns
ck new --kit engineer --exclude "*.log" --exclude "temp/**" --exclude "cache/**"

# Combine with other options
ck new --dir my-app --kit engineer --exclude "local-config/**" --exclude "*.local"

Useful for excluding temporary files, caches, or environment-specific files.

After Installation

Once the download completes:

1. Navigate to Project

cd my-project

2. Start Claude Code

claude

This starts Claude Code with full ClaudeKit capabilities.

3. Explore Commands

/help      # List all commands
/plan      # Plan a feature
/cook      # Implement code
/test      # Run tests
/docs:init # Generate documentation

4. Read Documentation

cat README.md
cat docs/project-overview-pdr.md

Common Workflows

Quick Start

# Download and start
ck new --kit engineer --dir my-app
cd my-app
claude

# Inside Claude Code
/docs:init  # Generate initial docs
/plan [your first feature]
/cook [implement feature]

Specific Version

# Check available versions
ck versions --kit engineer

# Download specific version
ck new --kit engineer --version v1.1.0 --dir my-app
cd my-app
claude

Debug Mode

# Download with verbose logging
ck new --kit engineer --verbose --log-file setup.log

# Check log if issues occur
cat setup.log

File Conflicts

If the target directory already has files:

Safe files (never overwritten):

.env, .env.local, .env.*.local
*.key, *.pem, *.p12
node_modules/**
.git/**
dist/**, build/**

ClaudeKit files (updated):

.claude/config.json
.claude/commands/*.md (standard commands)
.claude/workflows/*.md

Custom .claude files (preserved):

.claude/commands/my-custom.md
Any custom commands or configurations you created

Example:

Before:
  .claude/
    ├── commands/plan.md       (v1.0.0)
    └── commands/my-custom.md  (yours)

After ck new:
  .claude/
    ├── commands/plan.md       (v1.2.1 - updated)
    └── commands/my-custom.md  (yours - preserved)

Protected Files

These files are never overwritten during ck new or ck update:

Environment & Secrets:

.env, .env.local, .env.*.local
*.key, *.pem, *.p12
credentials.json

Dependencies:

node_modules/**
package-lock.json (if you have custom dependencies)

Version Control:

.git/**

Build Outputs:

dist/**, build/**, out/**

Troubleshooting

Authentication Error

Problem:

Error: Authentication failed
Unable to access repository

Solutions:

Check GitHub authentication:
```
gh auth status
```
Set environment variable:
```
export GITHUB_TOKEN=ghp_your_token
```
Verify repository access (requires ClaudeKit purchase)

See Authentication Guide

Directory Already Exists

Problem:

Error: Directory 'my-project' already exists

Solutions:

Use different directory:
```
ck new --dir my-project-v2
```
Update existing project instead:
```
cd my-project
ck update
```

Remove and recreate (careful!):

rm -rf my-project
ck new --dir my-project

Download Failed

Problem:

Error: Failed to download release

Solutions:

Check internet connection
Verify authentication:
```
gh auth status
```
Try with verbose logging:
```
ck new --kit engineer --verbose
```
Check GitHub status:
- Visit githubstatus.com

Version Not Found

Problem:

Error: Version 'v1.5.0' not found

Solutions:

List available versions:
```
ck versions --kit engineer
```

Use latest version:

ck new --kit engineer  # No --version flag

Permission Denied

Problem:

Error: EACCES: permission denied

Solutions:

Create in home directory:
```
cd ~
ck new --dir my-app
```
Check directory permissions:
```
ls -la
# Use directory you own
```

Best Practices

Directory naming:

Use lowercase with hyphens: my-project-name
Be descriptive: task-manager-api not project1
Match repository name for clarity

Version management:

Use ck versions to check available versions
Specify version for reproducibility in teams
Document which version you’re using in README

After download:

Review README.md
Read docs/project-overview-pdr.md
Explore .claude/commands/
Run /docs:init for codebase docs

Team setup:

Document version in package.json or README
Share authentication setup instructions
Use same version across team for consistency

ck update - Update existing project to latest version
ck versions - List available ClaudeKit releases
/docs:init - Generate project documentation

Next Steps

After creating your project:

Explore the kit - Review .claude/commands/ and workflows
Generate docs - Run /docs:init to document your codebase
Plan a feature - Use /plan [description] to create implementation plans
Start coding - Use /cook [task] to implement features

Ready to create? Run ck new --kit engineer to get started.