ck new

Create a new ClaudeKit project from scratch with interactive prompts and automatic setup.

Quick Start

# Interactive mode (recommended for beginners)
ck new

# Specify kit and directory
ck new --kit engineer --dir my-project

# With beta versions and skill dependencies
ck new --beta --install-skills

What It Does

The ck new command:

1. Prompts you to select a ClaudeKit kit (Engineer or Marketing)
2. Let you choose a target directory for the project
3. Fetches the latest (or selected) release from GitHub
4. Downloads and extracts project files
5. Optionally installs skill dependencies
6. Creates a ready-to-use ClaudeKit project

Syntax

ck new [OPTIONS]

Options

Examples

Basic Project Creation

Create a new Engineer kit project in the current directory:

ck new --kit engineer

Expected output:

🚀 ClaudeKit - Create New Project

Selected kit: ClaudeKit Engineer
Target directory: /Users/you/my-project
✓ Repository access verified
✓ Found: v1.16.0

Downloading
████████████████████████████████████████ 100% | 2.5 MB

Installing
✓ Files merged successfully

✨ Project created successfully at /Users/you/my-project

Specific Directory

Create project in a custom directory:

ck new --kit engineer --dir ~/projects/my-awesome-app

Include Beta Versions

Show and select from beta/prerelease versions:

ck new --beta

This includes versions tagged as prereleases in the version selection menu.

Install with Dependencies

Create project and auto-install all skill dependencies:

ck new --kit engineer --install-skills

This installs:

• Python packages (defined in skill requirements.txt files)
• System tools (FFmpeg, ImageMagick via package managers)
• Node.js packages (skill dependencies)

Non-Interactive Mode

For CI/CD or scripting (requires all necessary flags):

ck new --kit engineer --dir ./my-project --release v1.16.0 --force

Note: Without --release, non-interactive mode will fail. Interactive version selection requires a TTY.

Exclude Files

Skip specific files or patterns during installation:

ck new --exclude "*.log" --exclude "temp/**" --exclude "node_modules/**"

Glob patterns supported:

• * - Any characters
• ** - Recursive directories
• ? - Single character
• [abc] - Character set
• {a,b} - Alternatives

Command Prefix

Move ClaudeKit commands to /ck: namespace to avoid conflicts:

ck new --prefix

This transforms:

• /plan → /ck:plan
• /review → /ck:review
• /debug → /ck:debug

Useful when you have custom commands that conflict with ClaudeKit defaults.

Custom Folder Names

Use custom names for docs and plans directories:

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

This creates:

• documentation/ instead of docs/
• planning/ instead of plans/

And updates all references in workflow files automatically.

Common Patterns

Full-Featured Setup

Create a complete project with all features:

ck new \
  --kit engineer \
  --dir ~/projects/new-app \
  --install-skills \
  --gemini \
  --prefix

Beta Testing

Try the latest prerelease features:

ck new --beta --kit engineer

Quick Prototype

Minimal setup for quick testing:

ck new --kit engineer --dir ./test-project

Production Setup

Stable version with skill dependencies for production:

ck new \
  --kit engineer \
  --release v1.16.0 \
  --install-skills \
  --dir ~/production-app

Troubleshooting

”Directory is not empty”

Problem: Target directory contains files.

Solution:

Use --force to overwrite (interactive mode will prompt):

ck new --force --dir ./existing-project

Or choose a different directory:

ck new --dir ./new-project

“Access denied to repository”

Problem: GitHub authentication failed or repository access not granted.

Solution:

1. Run health check:

ck doctor

2. Re-authenticate:

gh auth login

Select “Login with a web browser” option.

3. Accept repository invitation (check email)
4. Wait 2-5 minutes for permissions to propagate

”Interactive version selection unavailable in non-interactive mode”

Problem: Running in CI/CD without TTY and no --release flag.

Solution:

Specify version explicitly:

ck new --kit engineer --release v1.16.0

Or set CI=false to enable interactive mode (if TTY available).

Platform-Specific Issues

Windows:

• Use PowerShell or Windows Terminal
• Paths with spaces: Use quotes --dir "C:\My Projects\app"
• Some antivirus software may flag downloads (whitelist ck command)

macOS:

• Requires Xcode Command Line Tools for git
• Use Homebrew for system dependencies: brew install gh

Linux:

• Package manager varies by distro (apt, yum, pacman)
• May need sudo for global npm installs
• WSL fully supported

What Gets Created

After ck new completes successfully, your project structure looks like:

my-project/
├── .claude/
│   ├── agents/           # AI agent definitions
│   ├── commands/         # Slash commands
│   ├── skills/           # Reusable skills
│   ├── workflows/        # Workflow definitions
│   ├── hooks/            # Lifecycle hooks
│   ├── settings.json     # Project settings
│   └── metadata.json     # Installation metadata
├── docs/                 # Documentation
├── plans/                # Planning directory
├── CLAUDE.md             # Claude Code instructions
├── .env.example          # Environment variables template
└── README.md             # Project readme

Next Steps

After creating a project:

1. Navigate to project:

cd my-project

2. Review configuration:

cat .claude/settings.json

3. Set up environment variables:

cp .env.example .env
# Edit .env with your API keys

4. Start coding with Claude Code - Open project in Claude Code and start using commands

5. Update later:

ck init  # Update to latest version

Related Commands

• ck init - Update existing project
• ck versions - Browse available versions
• ck doctor - Troubleshoot issues
• Configuration - Customize defaults