This document describes the rich set of commands available in the cg CLI (Code-Grove), details their options, and shows usage examples. It highlights recent improvements such as forced operations, dry-run previews, target branch specification, and better automation and guidance, especially regarding Pull Request workflows.
- Overview
- Command Summary Table
- Command Details
- New Features and Improvements
- Usage Patterns and Examples
Code-Grove (cg) is a CLI tool for managing Git worktrees with AI-powered support and modernized workflows. It facilitates fast, reliable, and automated parallel development, and tightly integrates with GitHub for automated Pull Request (PR) creation, merging, and streamlined branch management.
The CLI includes both classical and improved ("new architecture") forms of key commands for gradual migration and backward compatibility.
| Command | Description |
|---|---|
cg merge <branch> |
Merge a feature branch into the main branch, local or remote PR |
cg finish [branch] |
Finalize a worktree (push/merge, clean up, guide or create PR) |
cg create <branch> |
Create a new worktree for a branch |
cg remove <branch> |
Remove a worktree without pushing changes |
cg prune |
Remove stale worktree metadata |
cg list |
List all existing worktrees |
cg ai <input...> |
Use natural language to execute worktree operations |
cg init |
Initialize Code-Grove configuration |
cg help [command] |
Show help on a command |
cg version / cg ver |
Show detailed version and environment info |
Additional "new-" prefixed commands provide improved or alternate architectures with similar semantics (e.g. new-create), see details in usage below.
Purpose: Merge a feature branch into the main branch. Supports local and remote (PR-based) merging, with comprehensive checks, automation, and cleanup.
Usage:
cg merge <branch-name> [options]
Options:
--local- Perform a local merge (directly into the main branch) without PR.-f, --force- Force merge and cleanup without confirmation or full checks.--dry-run- Preview the merge steps and consequences; nothing is executed.--target <branch>- Specify the target branch to merge into (default: main/auto-detect).
Features:
- Dry-run mode shows step-by-step preview of what will happen (locally or remoting via PR).
- Force disables interactive confirmations, skips blocking issues.
- Target branch can be specified for both local and remote merges.
- Full automation for PR detection, status checking (CI, mergeability, etc.), and clean post-merge branch/worktree deletion.
Example:
cg merge feature-new-api
cg merge feature-login --local --target develop
cg merge bugfix-trailing-slash --force --dry-run
Purpose: Finalize and clean up a worktree (branch), supporting both traditional (push/PR) and local merge/cleanup flows. Offers improved guidance and optional PR auto-creation.
Usage:
cg finish [branch-name] [options]
Options:
-f, --force- Ignore uncommitted changes and force removal.--dry-run- Preview finalization steps, nothing is executed.-y, --yes- Automatically confirm prompts for removal/cleanup.--pr- Automatically create a GitHub Pull Request after finish.--pr-title <title>- Title for the Pull Request.--pr-body <body>- Body/description for the Pull Request.--pr-draft- Create the PR as a draft.--local- Perform local merge only (do not push to remote).--target <branch>- Target branch for local merge (default: main).
Features:
- Dry-run mode previews actions.
- Step-by-step automated guidance after push (e.g. links to create PR on GitHub, or direct creation).
- Advanced options for creating PRs in one command, with full custom title/body/draft handling.
Example:
cg finish feature-payment
cg finish --pr --pr-title "Implement payment flow" --pr-draft
cg finish hotfix --force --local --target develop
Purpose: Create a new worktree for a specified branch, with options for path, force, base, IDE launching, and preview.
Usage:
cg create <branch-name> [options]
Options:
-b, --base-branch <branch>- Base branch to create from (default: current branch).-p, --path <path>- Custom worktree path (default: .worktrees/).-f, --force- Overwrite if the path already exists.-c, --cursor- Launch Cursor IDE after creating worktree.--no-gitignore- Skip updating .gitignore.--dry-run- Preview what would be done without executing.
Features:
- Dry-run mode previews all steps and directory changes.
- Can forcefully create/overwrite existing directories.
- Integrates with Cursor IDE.
Example:
cg create feature-ui-redesign --base-branch develop --cursor
cg create data-migration -p ./custom-path --force --dry-run
(Note: new-create provides a version with new architecture.)
Purpose: Remove a worktree, regardless of the status of the associated branch (no push/PR actions involved). Use when a branch/worktree should be deleted locally.
Usage:
cg remove <branch-name> [options]
Options:
-f, --force- Force removal even if worktree has uncommitted changes.--dry-run- Show what would be done without actual deletion.
Features:
- Always previews actions if dry-run is set.
- Use force to ignore local changes.
Example:
cg remove experimental-ui --force
cg remove temp-feature --dry-run
Purpose: Remove worktree administrative/metadata files for worktrees that no longer exist ("prune" zombie/stale entries from .git/worktrees etc).
Usage:
cg prune [options]
Options:
--dry-run- Preview what would be pruned without actual operation.
Features:
- Essential for keeping metadata clean, especially with manual worktree modifications.
- Use periodically.
Example:
cg prune
cg prune --dry-run
Purpose: List all defined worktrees, with details distinguishing between bare/regular types, branch references, and directory paths.
Usage:
cg list
cg ls # alias
Options: None.
Example:
cg list
cg ls
Purpose: Use natural language commands to drive worktree operations (via OpenAI supported models). "AI Command" enables conversational branch, worktree, and git operations.
Usage:
cg ai <input...> [options]
Options:
--api-key <key>- Use a specific OpenAI API key (overrides env var).--model <model>- Set AI model to use (default: gpt-4o-mini).--auto-threshold <N>- Auto-execute threshold between 0-1 (default: 0.8).--confirm-threshold <N>- Confirmation threshold (default: 0.5).--dry-run- Preview what would be done, don't execute.--non-interactive- Disable interactive prompts.-v, --verbose- Show AI's detailed reasoning/results.
Features:
- Accepts free-form natural language: e.g., "create a worktree for bugfix-login on develop".
- Supports both English/Chinese.
- Supports both interactive and non-interactive modes.
- Prompts for missing configuration (OpenAI key/model).
Examples:
cg ai "create a new feature branch for user-authentication"
cg ai "delete the old-feature branch worktree"
cg ai "list all worktrees"
cg ai "clean up invalid worktrees"
| Command | Description |
|---|---|
cg init |
Initialize Code-Grove configuration. Use with --force to re-init. |
cg help |
Show top-level or specific command help. |
cg version |
Show CLI and environment version information. |
Examples:
cg init --force
cg help merge
cg version
- Forced Operations (
--force): Nearly all destructive commands accept--forceto ignore warnings, confirmation prompts, or errors due to uncommitted changes or collisions. This enables more automated use and scripting. - Dry-Run Previews (
--dry-run): Easily see what would be executed before running an actual operation, for safe trial runs, especially useful before potentially destructive actions. - Target Branch Specification: Many merge/finish commands allow
--target <branch>to direct merges into branches other than the auto-detected main, improving flexibility for release workflows or hotfix patterns. - PR Creation and Automation: The CLI now deeply integrates with GitHub, offering:
- Automatic PR creation directly after finish, with custom title/body/draft settings.
- Status analyzing and merging directly from the CLI with descriptive guidance and blocking issue warnings.
- Contextual links and guidance for next steps when manual/remote actions are required.
- Improved Guidance and Error Handling: Enhanced user feedback, progress messages, and error explanations across commands.
- AI-Powered Operations: The
cg aicommand brings advanced, free-form workflow possibilities and can be configured separately from regular commands.
Here are concrete, typical usage patterns that leverage the new improvements:
Create a feature worktree, finish, and merge via PR:
cg create cool-feature --base-branch develop
cd .worktrees/cool-feature
# ... code, commit, push ...
cg finish --pr --pr-title "Cool Feature Implementation" --pr-body "See details in ticket X"
cg merge cool-feature
Perform a safe dry-run before deleting a stale worktree:
cg remove feature-old --dry-run
# Review output, then:
cg remove feature-old --force
Local-only hotfix merge:
cg finish hotfix-production --local --target production
cg merge hotfix-production --local --target production --force
Batch prune and validate:
cg prune --dry-run
cg prune
Run an AI workflow:
cg ai "create a new worktree for release-fix on staging branch"
For any detailed option or command differences, see the per-command sections above or run cg help <command> for up-to-date help.