mirror of
https://github.com/cline/cline.git
synced 2026-09-24 23:20:16 +08:00
Cli 2.0 docs (#9060)
* docs: restructure CLI reference to web-friendly format Replace embedded man page format with structured markdown sections for better readability. Simplify description, reorganize commands and options into clear categories, and update Next Steps navigation cards. * Add ACP editor integrations documentation (#9036) * Add ACP editor integrations documentation with JetBrains and Neovim video demos * Add Model Orchestration documentation with --config and --thinking flags - Document --config and --thinking flags in CLI reference - Create new model-orchestration.mdx sample page - Add patterns for CI/CD review, task phase optimization, and multi-model consensus - Link to production GitHub Actions workflow - Update samples overview with new card - Update docs navigation * Add Worktree Workflows documentation with --cwd flag - Document --cwd flag in CLI reference - Create comprehensive worktree-workflows.mdx sample page - Add patterns for parallel execution and cross-worktree piping - Include real-world examples and best practices - Add CLI section to features/worktrees.mdx for discoverability - Update samples overview and navigation - Cross-link between CLI and VS Code worktree docs * Remove broken image references from worktrees documentation - Remove worktrees-overview.png Frame (image not available) - Remove worktrees-merge.png Frame (image not available) - Documentation remains fully functional with comprehensive text explanations * Remove accidentally committed local test file - Delete src/test/verify-platformio-mcp.ts which was causing CI failures - File contained TypeScript errors and hardcoded local paths - Was meant for local testing only, should not have been committed * Add native JetBrains plugin recommendation to ACP docs - Add prominent Note recommending native JetBrains plugin - Link directly to JetBrains installation section - Position ACP setup as an alternative approach - Keep all existing ACP content and video * docs: refine CLI reference formatting and ACP title Improve CLI reference readability with clearer headings and descriptions, and clarify the ACP editor integration page title for better discovery.docs: refine CLI reference formatting and ACP title Improve CLI reference readability with clearer headings and descriptions, and clarify the ACP editor integration page title for better discovery. * Fix CLI 2.0 syntax in model-orchestration.mdx - Updated issue analysis pipeline to use shell variables for passing context - Added explanatory note about why direct piping doesn't work - Corrected example to complete each phase before starting the next - All examples now use proper CLI 2.0 syntax * Completely rewrite cli-reference.mdx with accurate CLI 2.0 information - Removed all outdated CLI 1.0 content (instance management, Cline Core architecture, gRPC references) - Added accurate CLI 2.0 commands: task, history, config, auth, update, version, dev - Corrected all command flags and options based on actual man page - Added proper examples for all commands - Included environment variables documentation (CLINE_DIR, CLINE_COMMAND_PERMISSIONS) - Added shell completion instructions - Removed incorrect three-layer architecture description - All content now matches cli/man/cline.1.md source of truth Fixes outdated documentation issue mentioned in PR#9036 * Fix MDX syntax error in cli-reference.mdx - Replace angle bracket URLs with proper markdown links - MDX parser was interpreting <https://...> as invalid HTML tags - Now uses [url](url) format which is proper MDX syntax Fixes deployment validation error --------- Co-authored-by: Renee Huang <renee@cline.bot> * docs: enhance interactive mode documentation with structured settings overview * docs: restructure and improve CLI reference documentation - Reorganize command structure with clearer global options section - Add mode behavior table explaining interactive vs plain text modes - Improve option descriptions with consistent formatting - Add horizontal rules between sections for better readability - Document timeout option and environment variables more clearly - Add Tips & Tricks section for common usage patterns - Update frontmatter description to reflect content changes * docs: improve ACP editor integrations page with editor descriptions - Update page title to be more concise ("ACP: Editor Integrations") - Remove redundant H1 header that duplicated the title - Add introductory descriptions for JetBrains, Neovim, and Zed sections - Rename "Zed Editor" section to just "Zed" for consistency * docs: expand CLI reference with modes of operation and agent behavior * Update docs/cline-cli/cli-reference-deprecated.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Tony Loehr <turingxo@gmail.com> Co-authored-by: Renee Huang <renee@cline.bot> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
Juan Pablo Flores
co-authored by
Copilot
Tony Loehr
Renee Huang
Copilot
Tony Loehr
Renee Huang
parent
11da3ee89e
commit
b57aefb5a1
@@ -100,21 +100,14 @@ jobs:
|
||||
# Install the Cline CLI
|
||||
sudo npm install -g cline
|
||||
|
||||
- name: Create Cline Instance
|
||||
- name: Configure Cline CLI
|
||||
if: steps.detect.outputs.hit == 'true'
|
||||
env:
|
||||
OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
|
||||
CLINE_DIR: ${{ runner.temp }}/cline
|
||||
run: |
|
||||
# Create instance and capture output
|
||||
INSTANCE_OUTPUT=$(cline instance new 2>&1)
|
||||
|
||||
# Parse address from output (format: " Address: 127.0.0.1:36733")
|
||||
CLINE_ADDRESS=$(echo "$INSTANCE_OUTPUT" | grep "Address:" | grep -oE '([0-9]{1,3}\.){3}[0-9]{1,3}:[0-9]+')
|
||||
echo "CLINE_ADDRESS=$CLINE_ADDRESS" >> $GITHUB_ENV
|
||||
|
||||
# Configure API key
|
||||
cline config set open-router-api-key=$OPENROUTER_API_KEY --address $CLINE_ADDRESS -v
|
||||
cline config set open-router-api-key=$OPENROUTER_API_KEY -v
|
||||
|
||||
- name: Download analyze script
|
||||
if: steps.detect.outputs.hit == 'true'
|
||||
@@ -135,7 +128,7 @@ jobs:
|
||||
run: |
|
||||
set -euo pipefail
|
||||
|
||||
RESULT=$(./analyze-issue.sh "${ISSUE_URL}" "Analyze this issue. The user asked: ${COMMENT}" "$CLINE_ADDRESS")
|
||||
RESULT=$(./analyze-issue.sh "${ISSUE_URL}" "Analyze this issue. The user asked: ${COMMENT}")
|
||||
|
||||
{
|
||||
echo 'result<<EOF'
|
||||
@@ -180,8 +173,7 @@ This tells the workflow where to download the analysis script from your reposito
|
||||
</Warning>
|
||||
|
||||
The workflow will look for new or updated issues, check for `@cline` mentions, and then
|
||||
start up an instance of the Cline CLI to dig into the issue, providing feedback
|
||||
as a reply to the issue.
|
||||
start up the Cline CLI to dig into the issue, providing feedback as a reply to the issue.
|
||||
|
||||
### 2. Configure API Keys
|
||||
|
||||
@@ -246,19 +238,16 @@ if [ -z "$1" ]; then
|
||||
echo "Usage: $0 <github-issue-url> [prompt] [address]"
|
||||
echo "Example: $0 https://github.com/owner/repo/issues/123"
|
||||
echo "Example: $0 https://github.com/owner/repo/issues/123 'What is the root cause of this issue?'"
|
||||
echo "Example: $0 https://github.com/owner/repo/issues/123 'What is the root cause of this issue?' 127.0.0.1:46529"
|
||||
echo "Example: $0 https://github.com/owner/repo/issues/123 'What is the root cause of this issue?'"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Gather the args
|
||||
ISSUE_URL="$1"
|
||||
PROMPT="${2:-What is the root cause of this issue?}"
|
||||
if [ -n "$3" ]; then
|
||||
ADDRESS="--address $3"
|
||||
fi
|
||||
|
||||
# Ask Cline for its analysis, showing only the summary
|
||||
cline -y "$PROMPT: $ISSUE_URL" --mode act $ADDRESS -F json | \
|
||||
cline -y "$PROMPT: $ISSUE_URL" --mode act -F json | \
|
||||
sed -n '/^{/,$p' | \
|
||||
jq -r 'select(.say == "completion_result") | .text' | \
|
||||
sed 's/\\n/\n/g'
|
||||
@@ -311,12 +300,10 @@ The workflow (`cline-responder.yml`):
|
||||
1. **Triggers** on issue comments (created or edited)
|
||||
2. **Detects** `@cline` mentions (case-insensitive)
|
||||
3. **Installs** Cline CLI globally using npm
|
||||
4. **Creates** a Cline instance using `cline instance new`
|
||||
5. **Configures** authentication using `cline config set open-router-api-key=...
|
||||
--address ...`
|
||||
4. **Configures** authentication using `cline config set open-router-api-key=...`
|
||||
6. **Downloads** the reusable `analyze-issue.sh` script from the
|
||||
`github-issue-rca` sample
|
||||
7. **Runs** analysis with the instance address
|
||||
7. **Runs** analysis in Cline CLI
|
||||
8. **Posts** the analysis result as a comment
|
||||
|
||||
## Related Samples
|
||||
|
||||
@@ -0,0 +1,227 @@
|
||||
---
|
||||
title: "Model Orchestration"
|
||||
description: "Use multiple AI models strategically: optimize costs, reduce bias, and leverage model-specific strengths in your workflows"
|
||||
---
|
||||
|
||||
# Model Orchestration
|
||||
|
||||
Cline CLI's `--config` and `--thinking` flags enable sophisticated multi-model workflows. Instead of using a single model for all tasks, you can route different work to different models based on cost, capability, and specialization.
|
||||
|
||||
## Why Orchestrate Multiple Models?
|
||||
|
||||
**Cost Optimization**
|
||||
- Use fast, cheap models (Haiku, Gemini Flash) for simple tasks like summarization
|
||||
- Reserve expensive models (Opus, O1) for complex reasoning and planning
|
||||
- Reduce API costs by 10-100x on routine operations
|
||||
|
||||
**Bias Reduction**
|
||||
- Different models catch different issues in code reviews
|
||||
- Cross-validate solutions with multiple AI perspectives
|
||||
- Reduce blind spots from single-model thinking
|
||||
|
||||
**Specialization**
|
||||
- Some models excel at code (Codex, DeepSeek)
|
||||
- Others are better at documentation (GPT-4, Claude)
|
||||
- Security analysis benefits from multiple viewpoints
|
||||
|
||||
## Pattern 1: CI/CD Code Review
|
||||
|
||||
See our production GitHub Actions workflow that uses Cline CLI for automated PR reviews: [cline-pr-review.yml](https://github.com/cline/cline/blob/main/.github/workflows/cline-pr-review.yml)
|
||||
|
||||
**Key capabilities demonstrated:**
|
||||
- **Automated inline suggestions**: Creates GitHub suggestion blocks that authors can commit with one click
|
||||
- **SME identification**: Analyzes git history to find subject matter experts for each file
|
||||
- **Related issue discovery**: Searches for context from past issues and PRs
|
||||
- **Security-first permissions**: Read-only codebase access, can only post reviews
|
||||
- **Deep code analysis**: Understands intent, compares approaches, identifies edge cases
|
||||
|
||||
The workflow runs on every PR and provides maintainers with comprehensive context to make faster, more informed decisions.
|
||||
|
||||
## Pattern 2: Task Phase Optimization
|
||||
|
||||
Use different models for different phases of work. Route simple tasks to cheap models, complex reasoning to premium models.
|
||||
|
||||
### Example: Issue Analysis Pipeline
|
||||
|
||||
```bash
|
||||
# Get latest issue content
|
||||
ISSUE_CONTENT=$(gh issue view $(gh issue list -L 1 | awk '{print $1}'))
|
||||
|
||||
# Phase 1: Quick summary with cheap model
|
||||
SUMMARY=$(echo "$ISSUE_CONTENT" | cline -y --config ~/.cline-haiku \
|
||||
"summarize this issue in 2-3 sentences")
|
||||
|
||||
# Phase 2: Detailed plan with expensive model + thinking
|
||||
PLAN=$(echo "$SUMMARY" | cline -y --thinking --config ~/.cline-opus \
|
||||
"create detailed implementation plan with edge cases")
|
||||
|
||||
# Phase 3: Execute with mid-tier model
|
||||
echo "$PLAN" | cline -y --config ~/.cline-sonnet \
|
||||
"implement the plan from above"
|
||||
```
|
||||
|
||||
<Note>
|
||||
Each cline invocation needs to complete before passing output to the next phase. Use shell variables to store intermediate results rather than piping cline commands directly.
|
||||
</Note>
|
||||
|
||||
**Cost impact:**
|
||||
- Haiku: $0.80 per million input tokens
|
||||
- Opus: $15 per million input tokens
|
||||
- Sonnet: $3 per million input tokens
|
||||
|
||||
This pattern uses Opus only when needed for complex reasoning, saving ~10x on API costs compared to using Opus for everything.
|
||||
|
||||
### Setting Up Model Configs
|
||||
|
||||
Create separate configuration directories for each model:
|
||||
|
||||
```bash
|
||||
# Create config directories
|
||||
mkdir -p ~/.cline-haiku ~/.cline-sonnet ~/.cline-opus
|
||||
|
||||
# Configure each with different models
|
||||
cline --config ~/.cline-haiku auth anthropic --modelid claude-haiku-4-20250514
|
||||
cline --config ~/.cline-sonnet auth anthropic --modelid claude-sonnet-4-20250514
|
||||
cline --config ~/.cline-opus auth anthropic --modelid claude-opus-4-5-20251101
|
||||
|
||||
# Or use different providers entirely
|
||||
cline --config ~/.cline-gemini auth gemini --modelid gemini-2.0-flash-exp
|
||||
cline --config ~/.cline-codex auth openai-codex --modelid gpt-5-latest
|
||||
```
|
||||
|
||||
Now you can switch models per-task with `--config`:
|
||||
|
||||
```bash
|
||||
cline --config ~/.cline-haiku "quick task"
|
||||
cline --config ~/.cline-opus "complex reasoning task"
|
||||
```
|
||||
|
||||
## Pattern 3: Multi-Model Review & Consensus
|
||||
|
||||
Get multiple AI perspectives on the same change, then synthesize their feedback.
|
||||
|
||||
### Example: Diff Review Pipeline
|
||||
|
||||
```bash
|
||||
# Get the latest commit
|
||||
DIFF=$(git show)
|
||||
|
||||
# Review 1: Gemini's perspective
|
||||
echo "$DIFF" | cline -y --config ~/.cline-gemini \
|
||||
"review this diff and write your analysis to gemini-review.md"
|
||||
|
||||
# Review 2: Codex's perspective
|
||||
echo "$DIFF" | cline -y --config ~/.cline-codex \
|
||||
"review this diff and write your analysis to codex-review.md"
|
||||
|
||||
# Review 3: Opus's perspective
|
||||
echo "$DIFF" | cline -y --config ~/.cline-opus \
|
||||
"review this diff and write your analysis to opus-review.md"
|
||||
|
||||
# Synthesize all reviews into a consensus
|
||||
cat gemini-review.md codex-review.md opus-review.md | cline -y \
|
||||
"summarize these 3 reviews and identify: 1) issues all models agree on, 2) issues only one model caught, 3) your final recommendation"
|
||||
```
|
||||
|
||||
**Why this works:**
|
||||
- **Redundancy**: Issues caught by all 3 models are high-confidence
|
||||
- **Coverage**: Each model has blind spots; together they cover more ground
|
||||
- **Prioritization**: Consensus issues should be fixed first
|
||||
- **Learning**: See which model types catch which issue types
|
||||
|
||||
### Advanced: Parallel Reviews
|
||||
|
||||
Run reviews in parallel for faster feedback:
|
||||
|
||||
```bash
|
||||
# Run all reviews simultaneously
|
||||
git show | cline -y --config ~/.cline-gemini "review and save to gemini-review.md" &
|
||||
git show | cline -y --config ~/.cline-codex "review and save to codex-review.md" &
|
||||
git show | cline -y --config ~/.cline-opus "review and save to opus-review.md" &
|
||||
|
||||
# Wait for all to complete
|
||||
wait
|
||||
|
||||
# Synthesize
|
||||
cat *-review.md | cline -y "create consensus review"
|
||||
```
|
||||
|
||||
<Note>
|
||||
Parallel execution requires managing multiple Cline instances. See [Multi-instance workflows](/cline-cli/three-core-flows#3-multi-instance-run-parallel-agents) for details.
|
||||
</Note>
|
||||
|
||||
## Extended Thinking for Complex Tasks
|
||||
|
||||
Use the `--thinking` flag when Cline needs to analyze multiple approaches:
|
||||
|
||||
```bash
|
||||
# Without thinking: Fast but may miss nuances
|
||||
cline -y "refactor this codebase"
|
||||
|
||||
# With thinking: Slower but more thorough
|
||||
cline -y --thinking \
|
||||
"refactor this codebase - consider: performance, maintainability, backward compatibility"
|
||||
```
|
||||
|
||||
The `--thinking` flag allocates 1024 tokens for internal reasoning before Cline responds. Best for:
|
||||
- Architectural decisions
|
||||
- Security analysis
|
||||
- Complex refactoring
|
||||
- Multi-step planning
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Profile your workload**: Track which tasks are simple vs. complex
|
||||
2. **Match models to tasks**: Use fast models for summaries, powerful models for reasoning
|
||||
3. **Automate switching**: Script model selection based on task type
|
||||
4. **Monitor costs**: Different models have 10-100x price differences
|
||||
5. **Validate important decisions**: Use multi-model consensus for critical changes
|
||||
|
||||
## Production Examples
|
||||
|
||||
### Cost-Optimized PR Review
|
||||
|
||||
```bash
|
||||
# Haiku: Quick summary and issue identification
|
||||
gh pr view $PR | cline -y --config ~/.cline-haiku \
|
||||
"list all issues to fix, output as JSON"
|
||||
|
||||
# Opus with thinking: Deep analysis only if issues found
|
||||
if [ -s issues.json ]; then
|
||||
cline -y --thinking --config ~/.cline-opus \
|
||||
"analyze these issues and recommend fixes"
|
||||
fi
|
||||
```
|
||||
|
||||
### Security-Focused Multi-Model Scan
|
||||
|
||||
```bash
|
||||
# Different models have different security perspectives
|
||||
git diff main | cline -y --config ~/.cline-gemini "security review" > gemini-sec.md &
|
||||
git diff main | cline -y --config ~/.cline-opus "security review" > opus-sec.md &
|
||||
git diff main | cline -y --config ~/.cline-codex "security review" > codex-sec.md &
|
||||
wait
|
||||
|
||||
# High-priority: Issues all 3 models found
|
||||
cat *-sec.md | cline -y "find security issues all 3 reviews mentioned"
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
<Columns cols={2}>
|
||||
<Card title="CLI Reference" icon="terminal" href="/cline-cli/cli-reference">
|
||||
Complete documentation for --config and --thinking flags
|
||||
</Card>
|
||||
|
||||
<Card title="Three Core Flows" icon="route" href="/cline-cli/three-core-flows">
|
||||
Learn about interactive mode, headless automation, and multi-instance workflows
|
||||
</Card>
|
||||
|
||||
<Card title="Model Selection Guide" icon="brain" href="/core-features/model-selection-guide">
|
||||
Compare models and choose the right one for your needs
|
||||
</Card>
|
||||
|
||||
<Card title="CI/CD Integration" icon="github" href="/cline-cli/samples/github-integration">
|
||||
Automate GitHub workflows with Cline CLI
|
||||
</Card>
|
||||
</Columns>
|
||||
@@ -8,6 +8,22 @@ This section provides sample implementations that demonstrate various Cline CLI
|
||||
## Available Samples
|
||||
|
||||
<CardGroup cols={1}>
|
||||
<Card
|
||||
title="Model Orchestration"
|
||||
icon="layer-group"
|
||||
href="/cline-cli/samples/model-orchestration"
|
||||
>
|
||||
Use multiple AI models strategically with --config and --thinking flags. Optimize costs by routing simple tasks to cheap models and complex reasoning to premium models. Includes patterns for CI/CD code review, task phase optimization, and multi-model consensus.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="Worktree Workflows"
|
||||
icon="code-branch"
|
||||
href="/cline-cli/samples/worktree-workflows"
|
||||
>
|
||||
Use Git worktrees with the --cwd flag to run parallel tasks, test different approaches, and pipe context between isolated environments. Includes patterns for parallel execution, cross-worktree piping, and combining with model orchestration.
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="GitHub Root Cause Analysis"
|
||||
icon="magnifying-glass-chart"
|
||||
|
||||
@@ -0,0 +1,275 @@
|
||||
---
|
||||
title: "Worktree Workflows"
|
||||
description: "Use Git worktrees with Cline CLI to run parallel tasks, test different approaches, and pipe context between isolated environments"
|
||||
---
|
||||
|
||||
# Worktree Workflows
|
||||
|
||||
Git worktrees let you have multiple branches checked out simultaneously in different folders. Combined with Cline CLI's `--cwd` flag, this enables powerful parallel development workflows and isolated experimentation.
|
||||
|
||||
<Tip>
|
||||
New to Git worktrees? See our comprehensive [Worktrees guide](/features/worktrees) for the full concept explanation, VS Code integration, and best practices.
|
||||
</Tip>
|
||||
|
||||
## Quick Worktree Setup
|
||||
|
||||
If you haven't used Git worktrees before, here's the essentials:
|
||||
|
||||
```bash
|
||||
# Create a new worktree in ~/worktree-a on branch feature-a
|
||||
git worktree add ~/worktree-a -b feature-a
|
||||
|
||||
# Create another worktree for a different feature
|
||||
git worktree add ~/worktree-b -b feature-b
|
||||
|
||||
# List all worktrees
|
||||
git worktree list
|
||||
|
||||
# Remove a worktree when done
|
||||
git worktree remove ~/worktree-a
|
||||
```
|
||||
|
||||
Each worktree is a separate folder with its own branch checked out. They all share the same Git history and `.git` directory, but have independent working directories.
|
||||
|
||||
## The `--cwd` Flag
|
||||
|
||||
The `-c, --cwd <path>` flag tells Cline to run in a specific directory without changing your current location:
|
||||
|
||||
```bash
|
||||
# Run Cline in a different directory
|
||||
cline --cwd ~/worktree-a -y "refactor the authentication code"
|
||||
|
||||
# Short form
|
||||
cline -c ~/worktree-b -y "add unit tests"
|
||||
```
|
||||
|
||||
This is the key to worktree workflows—you can run multiple Cline instances in different worktrees simultaneously from a single terminal.
|
||||
|
||||
## Pattern 1: Parallel Task Execution
|
||||
|
||||
Run different tasks in parallel across multiple worktrees. Each task works on a separate branch in complete isolation.
|
||||
|
||||
### Example: Parallel Feature Development
|
||||
|
||||
```bash
|
||||
# Terminal 1: Update docs in worktree-a
|
||||
cline --cwd ~/worktree-a -y "read the last 10 changes using git show and update our README with them" &
|
||||
|
||||
# Terminal 2: TypeScript migration in worktree-b
|
||||
cline --cwd ~/worktree-b -y "update the index.js to use typescript" &
|
||||
|
||||
# Terminal 3: Refactoring in worktree-c
|
||||
cline --cwd ~/worktree-c -y "refactor the cli/ folder to be more modular" &
|
||||
|
||||
# Wait for all to complete
|
||||
wait
|
||||
```
|
||||
|
||||
The `&` runs each command in the background, allowing all three to execute simultaneously.
|
||||
|
||||
### When to Use Parallel Execution
|
||||
|
||||
**Perfect for:**
|
||||
- Multiple independent features
|
||||
- Bulk refactoring across different modules
|
||||
- Running tests in one worktree while developing in another
|
||||
- Trying multiple approaches to the same problem
|
||||
|
||||
**Not ideal for:**
|
||||
- Tasks that modify the same files (merge conflicts likely)
|
||||
- Tasks that depend on each other's results
|
||||
- When you need to monitor progress closely
|
||||
|
||||
## Pattern 2: Cross-Worktree Context Piping
|
||||
|
||||
Pipe output from one worktree as input to another. Use when a task in one worktree needs context from attempts in another worktree.
|
||||
|
||||
### Example: Learning from Failures
|
||||
|
||||
```bash
|
||||
# Try approach A in worktree-a, capture only the failure summary
|
||||
cline --cwd ~/worktree-a -y \
|
||||
"edit the index.ts to be better and then npm run. if it fails, output ONLY the failure summary. nothing else but the failure summary" \
|
||||
| cline --cwd ~/worktree-b -y \
|
||||
"i've tried to edit the index.ts in a different worktree but it failed. use a different approach for this work tree"
|
||||
```
|
||||
|
||||
**How it works:**
|
||||
1. First Cline instance runs in `worktree-a`, attempts a change, tests it
|
||||
2. If it fails, outputs just the failure summary
|
||||
3. That summary is piped to a second Cline instance in `worktree-b`
|
||||
4. Second instance sees the failure and tries a different approach
|
||||
|
||||
### When to Use Context Piping
|
||||
|
||||
**Perfect for:**
|
||||
- A/B testing different solutions
|
||||
- Learning from failed attempts
|
||||
- Iterative refinement (try → analyze → try differently)
|
||||
- Comparing outputs across approaches
|
||||
|
||||
**Not ideal for:**
|
||||
- Simple tasks that don't need cross-context
|
||||
- When both worktrees would succeed independently
|
||||
- Real-time collaboration (use parallel execution instead)
|
||||
|
||||
## Combining with Other CLI Features
|
||||
|
||||
### Different Models Per Worktree
|
||||
|
||||
Use `--config` to run different models in different worktrees:
|
||||
|
||||
```bash
|
||||
# Cheap model for simple docs update
|
||||
cline --cwd ~/worktree-docs --config ~/.cline-haiku -y \
|
||||
"update README with latest changes"
|
||||
|
||||
# Expensive model for complex refactoring
|
||||
cline --cwd ~/worktree-refactor --config ~/.cline-opus --thinking -y \
|
||||
"refactor authentication system for better security"
|
||||
```
|
||||
|
||||
This optimizes costs while maintaining quality where it matters.
|
||||
|
||||
### Task Isolation
|
||||
|
||||
Keep long-running worktree sessions isolated by running each task against a different worktree path:
|
||||
|
||||
```bash
|
||||
# Run tasks in dedicated worktrees
|
||||
cline --cwd ~/worktree-a -y "long-running task"
|
||||
cline --cwd ~/worktree-b -y "another task"
|
||||
```
|
||||
|
||||
Each worktree has its own Git branch and working directory, so task history and changes stay separated without needing instance management.
|
||||
|
||||
### With YOLO Mode
|
||||
|
||||
The `-y` (YOLO) flag is essential for worktree workflows:
|
||||
|
||||
```bash
|
||||
# Without -y: Opens interactive chat (blocks other tasks)
|
||||
cline --cwd ~/worktree-a "refactor code"
|
||||
|
||||
# With -y: Runs autonomously (doesn't block)
|
||||
cline --cwd ~/worktree-a -y "refactor code" &
|
||||
```
|
||||
|
||||
For parallel execution, always use `-y` to avoid blocking on user approval.
|
||||
|
||||
## Real-World Workflow Example
|
||||
|
||||
Here's a complete workflow showing how these patterns work together:
|
||||
|
||||
```bash
|
||||
# Setup: Create three worktrees
|
||||
git worktree add ~/cline-worktrees/feature-auth -b feature/authentication
|
||||
git worktree add ~/cline-worktrees/feature-api -b feature/api-endpoints
|
||||
git worktree add ~/cline-worktrees/fix-tests -b fix/failing-tests
|
||||
|
||||
# Pattern 1: Run parallel independent tasks
|
||||
cline -c ~/cline-worktrees/feature-auth -y --config ~/.cline-sonnet \
|
||||
"implement JWT authentication" &
|
||||
|
||||
cline -c ~/cline-worktrees/feature-api -y --config ~/.cline-sonnet \
|
||||
"create REST API endpoints for user management" &
|
||||
|
||||
cline -c ~/cline-worktrees/fix-tests -y --config ~/.cline-haiku \
|
||||
"fix all failing unit tests" &
|
||||
|
||||
wait
|
||||
echo "All parallel tasks complete!"
|
||||
|
||||
# Pattern 2: Use piping for iterative refinement
|
||||
cline -c ~/cline-worktrees/feature-auth -y \
|
||||
"test the authentication with curl. output only errors if any" \
|
||||
| cline -c ~/cline-worktrees/feature-auth -y \
|
||||
"fix the authentication issues described in the input"
|
||||
|
||||
# Merge successful changes back
|
||||
cd ~/cline-worktrees/feature-auth
|
||||
git checkout main
|
||||
git merge feature/authentication
|
||||
|
||||
# Cleanup
|
||||
git worktree remove ~/cline-worktrees/feature-auth
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Worktree Organization">
|
||||
- **Use a dedicated folder**: Create `~/cline-worktrees/` for all worktrees
|
||||
- **Meaningful branch names**: Use `feature/`, `fix/`, `refactor/` prefixes
|
||||
- **Clean up regularly**: Remove worktrees after merging branches
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Task Isolation">
|
||||
- **Independent features only**: Don't parallelize tasks that touch the same files
|
||||
- **Test in isolation**: Each worktree should have its own test run
|
||||
- **Separate configs**: Use `.worktreeinclude` to copy `node_modules` and build artifacts
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Resource Management">
|
||||
- **Monitor disk space**: Each worktree is a full checkout
|
||||
- **Limit parallel tasks**: Running too many simultaneously can slow your system
|
||||
- **Use background jobs wisely**: Track with `jobs` command, kill with `kill %1`, etc.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Error Handling">
|
||||
- **Check exit codes**: Use `|| echo "Task failed"` to catch errors
|
||||
- **Log outputs**: Redirect to files for debugging: `> worktree-a.log 2>&1`
|
||||
- **Graceful cleanup**: Always remove worktrees after tasks complete
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title=""Branch already checked out" error">
|
||||
Git doesn't allow the same branch in multiple worktrees. Solutions:
|
||||
- Use different branch names for each worktree
|
||||
- Remove the existing worktree first: `git worktree remove <path>`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Tasks not running in parallel">
|
||||
Make sure you're using:
|
||||
- `&` at the end of each command to background it
|
||||
- `-y` flag so Cline doesn't wait for approval
|
||||
- Different worktrees (not the same path)
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Pipe not working as expected">
|
||||
Verify:
|
||||
- First command outputs to stdout (not stderr)
|
||||
- Second command reads from stdin (use `--` separator if needed)
|
||||
- Both commands use correct `--cwd` paths
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Changes not appearing in worktree">
|
||||
Check:
|
||||
- You're in the right worktree: `git worktree list`
|
||||
- Files aren't gitignored
|
||||
- You committed/staged changes if needed
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Related Documentation
|
||||
|
||||
<Columns cols={2}>
|
||||
<Card title="Worktrees Overview" icon="code-branch" href="/features/worktrees">
|
||||
Complete guide to Git worktrees, VS Code integration, and .worktreeinclude
|
||||
</Card>
|
||||
|
||||
<Card title="Model Orchestration" icon="layer-group" href="/cline-cli/samples/model-orchestration">
|
||||
Use different models strategically with --config and --thinking flags
|
||||
</Card>
|
||||
|
||||
<Card title="CLI Reference" icon="terminal" href="/cline-cli/cli-reference">
|
||||
Complete documentation for --cwd and all other CLI flags
|
||||
</Card>
|
||||
|
||||
<Card title="Three Core Flows" icon="route" href="/cline-cli/three-core-flows">
|
||||
Learn about interactive mode, task mode, and plain text workflows
|
||||
</Card>
|
||||
</Columns>
|
||||
Reference in New Issue
Block a user