mirror of
https://github.com/cline/cline.git
synced 2026-10-13 17:16:30 +08:00
docs: match the CLI automation pages to the CLI (#14930)
* docs: match the CLI automation pages to the CLI The scheduling, teams, subagents, connector and sample pages told readers to run commands and flags the CLI doesn't have, and the samples downloaded files that are gone. - Scheduling: `executions` is `history`; `--workspace` is required; provider and model are separate flags; the other create options, subcommands and cron names are listed. Routing results now names the chat with `--delivery-thread` or `/schedule create` in the chat. A schedule with only `--delivery-bot` never posts anything. - Teams: start with `/team` and resume with `cline --id`, not the hidden `--team-name`; there is no `--no-teams`; state is in teams.db. The SDK teams guide gets the same CLI fix. - Subagents: the page described the old read-only research tool. `spawn_agent` subagents can edit files and run commands without further approval, run in the CLI and Desktop only, and are turned off with the `spawn_agent` tool. - Connectors: gchat, WhatsApp and Linear flag names; Discord tools are on by default. - Samples: inline the scripts whose download links 404; filter `run_result` for the final answer; `cline auth` needs `--modelid`; current model ids and prices; the issue responder runs Cline with a read-only token and posts from a second job, like the PR reviewer. Part of #14853. Co-authored-by: Harshil Mistry <125483347+harshil-mistry@users.noreply.github.com> * docs: check commenter permission, fail scripts on failed runs The @cline issue responder admitted any OWNER, MEMBER or COLLABORATOR, and organization members or collaborators with read access pass that check. A secret-free authorize job now looks up the comment author's repository permission and lets the analyze job run only for write or admin. It checks the comment's author rather than the actor, so editing someone else's comment doesn't start Cline on their text. The analyze job also stops setting CLINE_DIR from runner.temp, which isn't available at job level. Plan mode removes the editing tools and refuses common file-changing commands, but python -c and node -e still write files. The scheduling and subagent pages now say so instead of promising that Plan runs can't edit files. When a run fails, the CLI exits 1 but run_result still carries the error text, so jq prints it and the pipeline succeeds. The orchestration scripts now use set -euo pipefail, wait on each background review by PID, remove output files from earlier runs and name their inputs instead of globbing. analyze-issue.sh sets pipefail. The PR review pattern names the pull requests the sample skips. * docs: wait on saved review PIDs, list the current team tools The parallel review samples waited on $(jobs -p). Bash 3.2, the macOS /bin/bash, leaves finished jobs out of that list, so a review that failed fast was never waited on and the next model read an empty review. Save $! after each background pipeline and wait on those PIDs. The SDK teams guide listed team_delegate_task, team_check_status and team_get_result, which no longer exist, and a JSON layout under ~/.cline/data/teams/. List the tools in TEAM_TOOL_NAMES and say that team state is in ~/.cline/data/db/teams.db, keyed by session and restored when the session resumes. --------- Co-authored-by: Dominic Cooney <55120+dominiccooney@users.noreply.github.com> Co-authored-by: Harshil Mistry <125483347+harshil-mistry@users.noreply.github.com>
This commit is contained in:
Dominic Cooney
co-authored by
Dominic Cooney
Harshil Mistry
Dominic Cooney
Harshil Mistry
parent
3453880297
commit
db0be4c3fa
+11
-23
@@ -12,46 +12,34 @@ Agent teams let you break complex work across multiple agents that coordinate th
|
||||
|
||||
## Starting a Team
|
||||
|
||||
Start your prompt with `/team`, in an interactive session or on the command line:
|
||||
|
||||
```bash
|
||||
cline --team-name auth-sprint "Plan and implement user authentication with tests"
|
||||
cline "/team Plan and implement user authentication with tests"
|
||||
```
|
||||
|
||||
The `--team-name` flag enables team mode. The coordinator agent gets additional tools for spawning teammates and delegating tasks.
|
||||
The coordinator gets tools to add teammates, hand them tasks and collect their results. Without `/team`, Cline can still form a team when it decides a task needs one.
|
||||
|
||||
## Resuming Team Work
|
||||
|
||||
Team state persists across sessions. Resume where you left off:
|
||||
The team belongs to the session. To pick up where it left off, find the session's ID with `cline history`, then resume the session:
|
||||
|
||||
```bash
|
||||
cline --team-name auth-sprint "Continue with incomplete tasks"
|
||||
cline --id <session-id>
|
||||
```
|
||||
|
||||
## Interactive Mode
|
||||
|
||||
In interactive mode, use the `/team` slash command:
|
||||
|
||||
```
|
||||
/team Plan and implement a REST API with tests
|
||||
```
|
||||
The session opens with its team, and you can tell the coordinator what to do next.
|
||||
|
||||
## Team State
|
||||
|
||||
Team state is stored at `~/.cline/data/teams/[team-name]/` and includes:
|
||||
Each team has a task board, a mailbox for messages between agents, and a mission log. Cline keeps them in `~/.cline/data/db/teams.db`.
|
||||
|
||||
- Task board with current tasks and status
|
||||
- Inter-agent mailbox
|
||||
- Mission log with activity history
|
||||
## Turning Teams Off
|
||||
|
||||
## Disabling Teams
|
||||
|
||||
Teams are enabled by default. Disable them with:
|
||||
|
||||
```bash
|
||||
cline --no-teams "your prompt"
|
||||
```
|
||||
Teams are available in Act and Plan modes, and not with `--yolo`. To turn them off, run `cline`, type `/settings`, and turn off the `teams` tool on the **Tools** tab. Turn off `spawn_agent` there to stop [sub-agents](/features/subagents) too.
|
||||
|
||||
## Sub-Agents
|
||||
|
||||
For simpler delegation within a single session (no persistent state), use [sub-agents](/features/subagents). Sub-agents run in parallel for read-only research and return focused reports to the main agent.
|
||||
For simpler delegation within a single session (no persistent state), use [sub-agents](/features/subagents). Sub-agents run in parallel and return focused reports to the main agent.
|
||||
|
||||
See the [SDK Multi-Agent Teams guide](/sdk/guides/multi-agent-teams) for the programmatic API.
|
||||
|
||||
@@ -141,15 +141,14 @@ also starts a Discord gateway listener for mentions, replies, reactions, and DMs
|
||||
--public-key <KEY> \
|
||||
--base-url <URL> \
|
||||
--port 8788 \
|
||||
--cwd /path/to/repo \
|
||||
--enable-tools
|
||||
--cwd /path/to/repo
|
||||
```
|
||||
|
||||
`--app-id` is an alias for `--application-id`, and `--token` is an alias for
|
||||
`--bot-token`.
|
||||
|
||||
`--enable-tools` allows the agent to inspect files, run commands, edit code,
|
||||
and prepare PRs from Discord. Omit it if the bot should only chat.
|
||||
The agent can inspect files, run commands, edit code, and prepare PRs from
|
||||
Discord. Add `--no-tools` if the bot should only chat.
|
||||
</Step>
|
||||
|
||||
<Step title="Configure the Discord interactions endpoint">
|
||||
@@ -224,7 +223,7 @@ cline connect discord \
|
||||
Requires a service account credentials JSON file and public base URL.
|
||||
|
||||
```bash
|
||||
cline connect gchat --credentials <JSON> --base-url <URL>
|
||||
cline connect gchat --credentials-json <JSON> --base-url <URL>
|
||||
```
|
||||
|
||||
## WhatsApp
|
||||
@@ -232,7 +231,7 @@ cline connect gchat --credentials <JSON> --base-url <URL>
|
||||
Requires a phone number ID, access token, app secret, webhook verify token, and public base URL.
|
||||
|
||||
```bash
|
||||
cline connect whatsapp --phone-id <ID> --token <TOKEN> --app-secret <SECRET> --base-url <URL>
|
||||
cline connect whatsapp --phone-number-id <ID> --access-token <TOKEN> --app-secret <SECRET> --verify-token <VERIFY_TOKEN> --base-url <URL>
|
||||
```
|
||||
|
||||
## Linear
|
||||
@@ -240,7 +239,7 @@ cline connect whatsapp --phone-id <ID> --token <TOKEN> --app-secret <SECRET> --b
|
||||
Requires an API key, webhook signing secret, and public base URL.
|
||||
|
||||
```bash
|
||||
cline connect linear --api-key <KEY> --signing-secret <SECRET> --base-url <URL>
|
||||
cline connect linear --api-key <KEY> --webhook-secret <SECRET> --base-url <URL>
|
||||
```
|
||||
|
||||
## Managing Connectors
|
||||
|
||||
@@ -43,15 +43,7 @@ Before you begin, you'll need:
|
||||
|
||||
|
||||
|
||||
Copy the workflow file from this sample to your repository. The workflow file must be placed in the `.github/workflows/` directory in your repository root for GitHub Actions to detect and run it. In this case, we'll name it `cline-responder.yml`.
|
||||
|
||||
```bash
|
||||
# In your repository root
|
||||
mkdir -p .github/workflows
|
||||
curl -o .github/workflows/cline-responder.yml https://raw.githubusercontent.com/cline/cline/main/src/samples/cli/github-integration/cline-responder.yml
|
||||
```
|
||||
|
||||
Alternatively, you can copy the full workflow file directly into `.github/workflows/cline-responder.yml`:
|
||||
GitHub Actions runs workflow files in the `.github/workflows/` directory of your repository. Copy this workflow into `.github/workflows/cline-responder.yml`:
|
||||
|
||||
<Accordion title="Click to view the complete cline-responder.yml workflow">
|
||||
```yaml
|
||||
@@ -61,114 +53,120 @@ on:
|
||||
issue_comment:
|
||||
types: [created, edited]
|
||||
|
||||
permissions:
|
||||
issues: write
|
||||
# No permissions by default; each job asks for what it needs.
|
||||
permissions: {}
|
||||
|
||||
jobs:
|
||||
respond:
|
||||
authorize:
|
||||
# Runs for @cline mentions on issues, not pull requests.
|
||||
if: |
|
||||
contains(github.event.comment.body, '@cline') &&
|
||||
!github.event.issue.pull_request
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 5
|
||||
|
||||
# Read-only, and uses no secrets.
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
outputs:
|
||||
allowed: ${{ steps.check.outputs.allowed }}
|
||||
|
||||
steps:
|
||||
# Checks the comment's author, not whoever edited it last, so that
|
||||
# editing someone else's comment doesn't start Cline on their text.
|
||||
- name: Check that the comment's author can write to the repository
|
||||
id: check
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
AUTHOR: ${{ github.event.comment.user.login }}
|
||||
run: |
|
||||
PERMISSION=$(gh api "repos/$GITHUB_REPOSITORY/collaborators/$AUTHOR/permission" --jq .permission)
|
||||
echo "$AUTHOR has $PERMISSION permission"
|
||||
if [ "$PERMISSION" = admin ] || [ "$PERMISSION" = write ]; then
|
||||
echo "allowed=true" >> "$GITHUB_OUTPUT"
|
||||
fi
|
||||
|
||||
analyze:
|
||||
needs: authorize
|
||||
if: needs.authorize.outputs.allowed == 'true'
|
||||
runs-on: ubuntu-latest
|
||||
environment: cline-actions
|
||||
timeout-minutes: 30
|
||||
|
||||
# Read-only: Cline runs in this job.
|
||||
permissions:
|
||||
contents: read
|
||||
issues: read
|
||||
|
||||
steps:
|
||||
- name: Check for @cline mention
|
||||
id: detect
|
||||
uses: actions/github-script@v7
|
||||
with:
|
||||
script: |
|
||||
const body = context.payload.comment?.body || "";
|
||||
const isPR = !!context.payload.issue?.pull_request;
|
||||
const hit = body.toLowerCase().includes("@cline");
|
||||
core.setOutput("hit", (!isPR && hit) ? "true" : "false");
|
||||
core.setOutput("issue_number", String(context.payload.issue?.number || ""));
|
||||
core.setOutput("issue_url", context.payload.issue?.html_url || "");
|
||||
core.setOutput("comment_body", body);
|
||||
|
||||
- name: Checkout repository
|
||||
if: steps.detect.outputs.hit == 'true'
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
persist-credentials: false
|
||||
|
||||
# Node v20+ is needed for Cline CLI on GitHub Actions Linux
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '22'
|
||||
cache: 'npm'
|
||||
node-version: 22
|
||||
|
||||
- name: Install Cline CLI
|
||||
if: steps.detect.outputs.hit == 'true'
|
||||
run: npm install -g cline
|
||||
|
||||
- name: Configure Cline Authentication
|
||||
if: steps.detect.outputs.hit == 'true'
|
||||
env:
|
||||
CLINE_DIR: ${{ runner.temp }}/cline
|
||||
OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
|
||||
run: |
|
||||
# Configure API key using the auth command
|
||||
cline auth --provider openrouter --apikey "${{ secrets.OPENROUTER_API_KEY }}"
|
||||
|
||||
- name: Download analyze script
|
||||
if: steps.detect.outputs.hit == 'true'
|
||||
run: |
|
||||
export GITORG="YOUR-GITHUB-ORG"
|
||||
export GITREPO="YOUR-GITHUB-REPO"
|
||||
|
||||
curl -L https://raw.githubusercontent.com/${GITORG}/${GITREPO}/refs/heads/main/git-scripts/analyze-issue.sh -o analyze-issue.sh
|
||||
chmod +x analyze-issue.sh
|
||||
cline auth --provider openrouter \
|
||||
--apikey "$OPENROUTER_API_KEY" \
|
||||
--modelid anthropic/claude-sonnet-5.5
|
||||
|
||||
- name: Run analysis
|
||||
if: steps.detect.outputs.hit == 'true'
|
||||
id: analyze
|
||||
env:
|
||||
ISSUE_URL: ${{ steps.detect.outputs.issue_url }}
|
||||
COMMENT: ${{ steps.detect.outputs.comment_body }}
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
ISSUE_URL: ${{ github.event.issue.html_url }}
|
||||
COMMENT: ${{ github.event.comment.body }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
|
||||
RESULT=$(./analyze-issue.sh "${ISSUE_URL}" "Analyze this issue. The user asked: ${COMMENT}")
|
||||
|
||||
{
|
||||
echo 'result<<EOF'
|
||||
printf "%s\n" "$RESULT"
|
||||
echo 'EOF'
|
||||
} >> "$GITHUB_OUTPUT"
|
||||
bash git-scripts/analyze-issue.sh "$ISSUE_URL" "Analyze this issue. The user asked: $COMMENT" > response.md
|
||||
|
||||
- name: Post response
|
||||
if: steps.detect.outputs.hit == 'true'
|
||||
uses: actions/github-script@v7
|
||||
env:
|
||||
ISSUE_NUMBER: ${{ steps.detect.outputs.issue_number }}
|
||||
RESULT: ${{ steps.analyze.outputs.result }}
|
||||
- name: Save the response
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
script: |
|
||||
await github.rest.issues.createComment({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
issue_number: Number(process.env.ISSUE_NUMBER),
|
||||
body: process.env.RESULT || "(no output)"
|
||||
});
|
||||
name: response
|
||||
path: response.md
|
||||
if-no-files-found: error
|
||||
|
||||
post:
|
||||
needs: analyze
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 5
|
||||
|
||||
# Can write issues, but runs no code from the repository or from Cline.
|
||||
permissions:
|
||||
issues: write
|
||||
|
||||
steps:
|
||||
- name: Download the response
|
||||
uses: actions/download-artifact@v4
|
||||
with:
|
||||
name: response
|
||||
path: ${{ runner.temp }}/response
|
||||
|
||||
- name: Post the response
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
GH_REPO: ${{ github.repository }}
|
||||
ISSUE_NUMBER: ${{ github.event.issue.number }}
|
||||
run: gh issue comment "$ISSUE_NUMBER" --body-file "$RUNNER_TEMP/response/response.md"
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Warning>
|
||||
**You MUST edit the workflow file before committing!**
|
||||
The workflow has three jobs, so that only people who can write to the repository can start Cline, and the job that runs Cline can't change your repository or your issues:
|
||||
|
||||
Open `.github/workflows/cline-responder.yml` and update the "Download analyze script" step within the workflow to specify your GitHub organization and repository where the analysis script is stored:
|
||||
|
||||
```yaml
|
||||
export GITORG="YOUR-GITHUB-ORG" # Change this!
|
||||
export GITREPO="YOUR-GITHUB-REPO" # Change this!
|
||||
```
|
||||
|
||||
**Example:** If your repository is `github.com/acme/myproject`, set:
|
||||
```yaml
|
||||
export GITORG="acme"
|
||||
export GITREPO="myproject"
|
||||
```
|
||||
|
||||
This tells the workflow where to download the analysis script from your repository after you commit it in step 3.
|
||||
</Warning>
|
||||
|
||||
The workflow will look for new or updated issues, check for `@cline` mentions, and then
|
||||
start up the Cline CLI to dig into the issue, providing feedback as a reply to the issue.
|
||||
1. **`authorize`** runs when someone mentions `@cline` in an issue comment. It looks up the comment author's permission on the repository, and the workflow stops unless they can write to it. GitHub reports the maintain role as write.
|
||||
2. **`analyze`** gets a read-only token, runs the analysis script from your repository, and saves Cline's answer to a file.
|
||||
3. **`post`** gets permission to write issues, but doesn't check out code or run Cline. It posts the file as a comment on the issue.
|
||||
|
||||
### 2. Configure API Keys
|
||||
|
||||
@@ -202,20 +200,7 @@ Now you're ready to supply Cline with the credentials it needs in a GitHub Actio
|
||||
|
||||
### 3. Add Analysis Script
|
||||
|
||||
Add the analysis script from the `github-issue-rca` sample to your repository. **First, you'll need to create a `git-scripts` directory in your repository root where the script will be located.** Choose one of these options:
|
||||
|
||||
**Option A: Download directly (Recommended)**
|
||||
|
||||
```bash
|
||||
# In your repository root, create the directory and download the script
|
||||
mkdir -p git-scripts
|
||||
curl -o git-scripts/analyze-issue.sh https://raw.githubusercontent.com/cline/cline/main/src/samples/cli/github-issue-rca/analyze-issue.sh
|
||||
chmod +x git-scripts/analyze-issue.sh
|
||||
```
|
||||
|
||||
**Option B: Manual copy-paste**
|
||||
|
||||
Create the directory and file manually, then paste the script content:
|
||||
Add the analysis script from the `github-issue-rca` sample to your repository, in a `git-scripts` directory at the repository root. Create the directory and file, then paste the script content:
|
||||
|
||||
```bash
|
||||
# In your repository root
|
||||
@@ -240,10 +225,12 @@ fi
|
||||
ISSUE_URL="$1"
|
||||
PROMPT="${2:-What is the root cause of this issue?}"
|
||||
|
||||
# Fail if Cline fails, not only if jq does
|
||||
set -o pipefail
|
||||
|
||||
# Ask Cline for its analysis, showing only the summary
|
||||
cline --auto-approve true --json "$PROMPT: $ISSUE_URL" | \
|
||||
jq -r 'select(.type == "agent_event" and .event.type == "done") | .event.text' | \
|
||||
sed 's/\\n/\n/g'
|
||||
jq -r 'select(.type == "run_result") | .text'
|
||||
```
|
||||
|
||||
After pasting the script content, make it executable:
|
||||
@@ -252,8 +239,8 @@ chmod +x git-scripts/analyze-issue.sh
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
This analysis script calls Cline to execute a prompt on a GitHub issue,
|
||||
summarizing the output to populate the reply to the issue.
|
||||
This analysis script calls Cline to execute a prompt on a GitHub issue and
|
||||
prints Cline's final answer, which becomes the reply to the issue.
|
||||
|
||||
### 4. Commit and Push
|
||||
|
||||
@@ -276,28 +263,23 @@ Once set up, simply mention `@cline` in any issue comment:
|
||||
@cline what are the security implications?
|
||||
```
|
||||
|
||||
GitHub Actions will:
|
||||
1. Detect the `@cline` mention
|
||||
2. Start a Cline CLI instance
|
||||
3. Download the analysis script
|
||||
4. Analyze the issue using Act mode with auto-approval enabled
|
||||
5. Post Cline's analysis as a new comment
|
||||
|
||||
**Note**: The workflow only triggers on issue comments, not pull request
|
||||
comments.
|
||||
comments, and only for comments from people with write access to the repository.
|
||||
|
||||
## How It Works
|
||||
|
||||
The workflow (`cline-responder.yml`):
|
||||
|
||||
1. **Triggers** on issue comments (created or edited)
|
||||
2. **Detects** `@cline` mentions (case-insensitive)
|
||||
1. **Triggers** on issue comments (created or edited) that mention `@cline`
|
||||
2. **Checks** that the comment's author can write to the repository
|
||||
3. **Installs** Cline CLI globally using npm
|
||||
4. **Configures** authentication using `cline auth --provider openrouter --apikey ...`
|
||||
6. **Downloads** the reusable `analyze-issue.sh` script from the
|
||||
`github-issue-rca` sample
|
||||
7. **Runs** analysis in Cline CLI
|
||||
8. **Posts** the analysis result as a comment
|
||||
4. **Configures** authentication using `cline auth --provider openrouter --apikey ... --modelid ...`
|
||||
5. **Runs** `git-scripts/analyze-issue.sh` from your repository, which runs Cline in Act mode with auto-approval
|
||||
6. **Posts** the analysis as a comment, from a separate job that doesn't run Cline
|
||||
|
||||
## What the Analysis Job Can Still Do
|
||||
|
||||
With `--auto-approve true`, Cline can run any shell command in the `analyze` job. Text in the issue or the comment could persuade Cline to do something other than analyze it. The read-only token stops Cline from changing your repository or issues, but the job can still read your code and your provider API key, and it can reach the internet. Use a provider key with a spending limit, and don't give the job any other secrets.
|
||||
|
||||
## Related Samples
|
||||
|
||||
|
||||
@@ -66,12 +66,7 @@ gh auth login
|
||||
|
||||
## Getting the Script
|
||||
|
||||
**Option 1: Download directly with curl**
|
||||
```bash
|
||||
curl -O https://raw.githubusercontent.com/cline/cline/main/src/samples/cli/github-issue-rca/analyze-issue.sh
|
||||
```
|
||||
|
||||
**Option 2: Copy the full script**
|
||||
Save this script as `analyze-issue.sh`:
|
||||
|
||||
<Accordion title="Click to view the complete analyze-issue.sh script">
|
||||
|
||||
@@ -89,16 +84,19 @@ fi
|
||||
# Gather the args
|
||||
ISSUE_URL="$1"
|
||||
PROMPT="${2:-What is the root cause of this issue?}"
|
||||
|
||||
# Fail if Cline fails, not only if jq does
|
||||
set -o pipefail
|
||||
|
||||
# Ask Cline for its analysis, showing only the summary
|
||||
cline --auto-approve true --json "$PROMPT: $ISSUE_URL" | \
|
||||
jq -r 'select(.type == "agent_event" and .event.type == "done") | .event.text' | \
|
||||
sed 's/\\n/\n/g'
|
||||
jq -r 'select(.type == "run_result") | .text'
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Note>
|
||||
**After downloading or creating the script**, make it executable by running:
|
||||
**After creating the script**, make it executable by running:
|
||||
```bash
|
||||
chmod +x analyze-issue.sh
|
||||
```
|
||||
@@ -166,19 +164,22 @@ PROMPT="${2:-What is the root cause of this issue?}"
|
||||
**Explanation:**
|
||||
- `ISSUE_URL="$1"` - First argument is always the issue URL
|
||||
- `PROMPT="${2:-...}"` - Second argument is optional, defaults to root cause analysis
|
||||
- The SDK CLI runs the task directly, so no address flag is required.
|
||||
|
||||
### The Core Analysis Pipeline
|
||||
|
||||
This is where the magic happens:
|
||||
|
||||
```bash
|
||||
# Fail if Cline fails, not only if jq does
|
||||
set -o pipefail
|
||||
|
||||
# Ask Cline for its analysis, showing only the summary
|
||||
cline --auto-approve true --json "$PROMPT: $ISSUE_URL" | \
|
||||
jq -r 'select(.type == "agent_event" and .event.type == "done") | .event.text' | \
|
||||
sed 's/\\n/\n/g'
|
||||
jq -r 'select(.type == "run_result") | .text'
|
||||
```
|
||||
|
||||
When a run fails, the `run_result` line holds the error message, so the script prints it. `set -o pipefail` makes the script exit with an error too, so that a calling script or workflow knows the analysis failed.
|
||||
|
||||
<Accordion title="Pipeline Breakdown: Understanding Each Component">
|
||||
|
||||
**1. `cline --auto-approve true --json "$PROMPT: $ISSUE_URL"`**
|
||||
@@ -188,14 +189,10 @@ cline --auto-approve true --json "$PROMPT: $ISSUE_URL" | \
|
||||
- `--json` emits newline-delimited JSON for parsing
|
||||
- Constructs prompt with issue URL
|
||||
|
||||
**2. `jq -r 'select(.type == "agent_event" and .event.type == "done") | .event.text'`**
|
||||
- Filters for the final agent `done` event
|
||||
- Extracts the final text field
|
||||
- `-r` outputs raw strings (no JSON quotes)
|
||||
|
||||
**3. `sed 's/\\n/\n/g'`**
|
||||
- Converts escaped newlines to actual newlines
|
||||
- Makes output readable
|
||||
**2. `jq -r 'select(.type == "run_result") | .text'`**
|
||||
- Keeps the `run_result` line, which the CLI prints when the run finishes
|
||||
- Prints its `text` field, Cline's final answer
|
||||
- `-r` prints the text itself, with real line breaks and no JSON quotes
|
||||
|
||||
</Accordion>
|
||||
|
||||
|
||||
@@ -94,7 +94,7 @@ jobs:
|
||||
run: |
|
||||
cline auth --provider anthropic \
|
||||
--apikey "$ANTHROPIC_API_KEY" \
|
||||
--modelid claude-opus-4-5-20251101
|
||||
--modelid claude-opus-5-5
|
||||
|
||||
- name: Review PR with Cline
|
||||
env:
|
||||
@@ -188,9 +188,9 @@ A `pull_request` run uses the workflow file from the pull request, so anyone who
|
||||
|
||||
### Authentication
|
||||
```bash
|
||||
cline auth --provider anthropic --apikey "..."
|
||||
cline auth --provider anthropic --apikey "..." --modelid claude-opus-5-5
|
||||
```
|
||||
The `auth` command configures Cline in the CI environment without interactive prompts. You can switch providers (e.g., `openai`, `openrouter`) by changing the flags.
|
||||
The `auth` command configures Cline in the CI environment without interactive prompts. It needs both `--apikey` and `--modelid`. You can switch providers (e.g., `openai-native`, `openrouter`) by changing the flags.
|
||||
|
||||
### Autonomous Mode (`--auto-approve true`)
|
||||
```bash
|
||||
|
||||
@@ -9,7 +9,7 @@ Cline CLI's `--config` and `--thinking` flags enable sophisticated multi-model w
|
||||
|
||||
**Cost Optimization**
|
||||
|
||||
By routing work to the right model for the job, you can dramatically reduce API costs. Fast, inexpensive models like Haiku and Gemini Flash handle simple tasks such as summarization, while expensive models like Opus and O1 are reserved for complex reasoning and planning. This approach can reduce costs by 10-100x on routine operations.
|
||||
By routing work to the right model for the job, you can reduce API costs. Fast, inexpensive models like Haiku and Gemini Flash handle simple tasks such as summarization, while more expensive models like Opus are reserved for complex reasoning and planning.
|
||||
|
||||
**Bias Reduction**
|
||||
|
||||
@@ -17,20 +17,11 @@ Different models catch different issues, so cross-validating solutions with mult
|
||||
|
||||
**Specialization**
|
||||
|
||||
Certain models excel in specific domains: Codex and DeepSeek are strong at code generation, while GPT-4 and Claude shine at documentation and prose. Security analysis in particular benefits from combining multiple model viewpoints, since each brings different training data and heuristics to the table.
|
||||
Models differ in what they do well. Security analysis in particular benefits from combining several models, since each brings different training data and heuristics to the table.
|
||||
|
||||
## 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.
|
||||
The [GitHub PR Review](/cli/samples/github-pr-review) sample runs Cline CLI in GitHub Actions to review pull requests, except drafts and pull requests from forks or Dependabot. Its `cline auth` step picks the model, so you can give the review job a stronger model than the rest of your automation.
|
||||
|
||||
## Pattern 2: Task Phase Optimization
|
||||
|
||||
@@ -39,16 +30,22 @@ Use different models for different phases of work. Route simple tasks to cheap m
|
||||
### Example: Issue Analysis Pipeline
|
||||
|
||||
```bash
|
||||
# Stop if any command, including a cline run, fails
|
||||
set -euo pipefail
|
||||
|
||||
# Print only Cline's final answer from --json output
|
||||
final_answer() { jq -r 'select(.type == "run_result") | .text'; }
|
||||
|
||||
# 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 --auto-approve true --config ~/.cline-haiku \
|
||||
"summarize this issue in 2-3 sentences")
|
||||
SUMMARY=$(echo "$ISSUE_CONTENT" | cline --auto-approve true --json --config ~/.cline-haiku \
|
||||
"summarize this issue in 2-3 sentences" | final_answer)
|
||||
|
||||
# Phase 2: Detailed plan with expensive model + thinking
|
||||
PLAN=$(echo "$SUMMARY" | cline --auto-approve true --thinking high --config ~/.cline-opus \
|
||||
"create detailed implementation plan with edge cases")
|
||||
PLAN=$(echo "$SUMMARY" | cline --auto-approve true --json --thinking high --config ~/.cline-opus \
|
||||
"create detailed implementation plan with edge cases" | final_answer)
|
||||
|
||||
# Phase 3: Execute with mid-tier model
|
||||
echo "$PLAN" | cline --auto-approve true --config ~/.cline-sonnet \
|
||||
@@ -56,35 +53,34 @@ echo "$PLAN" | cline --auto-approve true --config ~/.cline-sonnet \
|
||||
```
|
||||
|
||||
<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.
|
||||
Without `--json`, the CLI also prints the model's thinking, and the next phase would read it as part of its input. `--json` with `final_answer` keeps only the answer. Each `cline` command must finish before the next phase starts, so store each result in a shell variable rather than piping one `cline` command into the next.
|
||||
|
||||
When a run fails, `cline` exits with an error, but `final_answer` still prints the error message. `set -euo pipefail` stops the script there, so that the error message doesn't become the next phase's input.
|
||||
</Note>
|
||||
|
||||
**Cost impact:**
|
||||
- Haiku: $0.80 per million input tokens
|
||||
- Opus: $15 per million input tokens
|
||||
- Sonnet: $3 per million input tokens
|
||||
**Cost impact** (Anthropic list prices per million input tokens, from the model catalog Cline ships):
|
||||
- Haiku 4.5: $1
|
||||
- Sonnet 5.5: $2
|
||||
- Opus 5.5: $4
|
||||
|
||||
This pattern uses Opus only when needed for complex reasoning, saving ~10x on API costs compared to using Opus for everything.
|
||||
This pattern uses Opus only where it needs to reason hard. Check your provider's current prices before you plan around them.
|
||||
|
||||
### Setting Up Model Configs
|
||||
|
||||
Create separate configuration directories for each model:
|
||||
`--config` points Cline at a different configuration directory, and each directory keeps its own provider and model. Set up one directory per 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
|
||||
# Configure each directory with its own model
|
||||
cline --config ~/.cline-haiku auth anthropic --apikey "$ANTHROPIC_API_KEY" --modelid claude-haiku-4-5
|
||||
cline --config ~/.cline-sonnet auth anthropic --apikey "$ANTHROPIC_API_KEY" --modelid claude-sonnet-5-5
|
||||
cline --config ~/.cline-opus auth anthropic --apikey "$ANTHROPIC_API_KEY" --modelid claude-opus-5-5
|
||||
|
||||
# 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
|
||||
cline --config ~/.cline-gemini auth gemini --apikey "$GEMINI_API_KEY" --modelid gemini-3.8-flash
|
||||
cline --config ~/.cline-gpt auth openai-native --apikey "$OPENAI_API_KEY" --modelid gpt-6.1-sol
|
||||
```
|
||||
|
||||
Now you can switch models per-task with `--config`:
|
||||
Each directory also keeps its own session history. Now you can switch models per task with `--config`:
|
||||
|
||||
```bash
|
||||
cline --config ~/.cline-haiku "quick task"
|
||||
@@ -98,6 +94,11 @@ Get multiple AI perspectives on the same change, then synthesize their feedback.
|
||||
### Example: Diff Review Pipeline
|
||||
|
||||
```bash
|
||||
set -euo pipefail
|
||||
|
||||
# Remove reviews from an earlier run
|
||||
rm -f gemini-review.md gpt-review.md opus-review.md
|
||||
|
||||
# Get the latest commit
|
||||
DIFF=$(git show)
|
||||
|
||||
@@ -105,16 +106,16 @@ DIFF=$(git show)
|
||||
echo "$DIFF" | cline --auto-approve true --config ~/.cline-gemini \
|
||||
"review this diff and write your analysis to gemini-review.md"
|
||||
|
||||
# Review 2: Codex's perspective
|
||||
echo "$DIFF" | cline --auto-approve true --config ~/.cline-codex \
|
||||
"review this diff and write your analysis to codex-review.md"
|
||||
# Review 2: GPT's perspective
|
||||
echo "$DIFF" | cline --auto-approve true --config ~/.cline-gpt \
|
||||
"review this diff and write your analysis to gpt-review.md"
|
||||
|
||||
# Review 3: Opus's perspective
|
||||
echo "$DIFF" | cline --auto-approve true --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 --auto-approve true \
|
||||
cat gemini-review.md gpt-review.md opus-review.md | cline --auto-approve true \
|
||||
"summarize these 3 reviews and identify: 1) issues all models agree on, 2) issues only one model caught, 3) your final recommendation"
|
||||
```
|
||||
|
||||
@@ -129,20 +130,28 @@ cat gemini-review.md codex-review.md opus-review.md | cline --auto-approve true
|
||||
Run reviews in parallel for faster feedback:
|
||||
|
||||
```bash
|
||||
# Run all reviews simultaneously
|
||||
git show | cline --auto-approve true --config ~/.cline-gemini "review and save to gemini-review.md" &
|
||||
git show | cline --auto-approve true --config ~/.cline-codex "review and save to codex-review.md" &
|
||||
git show | cline --auto-approve true --config ~/.cline-opus "review and save to opus-review.md" &
|
||||
set -euo pipefail
|
||||
|
||||
# Wait for all to complete
|
||||
wait
|
||||
# Remove reviews from an earlier run
|
||||
rm -f gemini-review.md gpt-review.md opus-review.md
|
||||
|
||||
# Run all reviews simultaneously, and save each one's process ID
|
||||
git show | cline --auto-approve true --config ~/.cline-gemini "review and save to gemini-review.md" &
|
||||
pids=($!)
|
||||
git show | cline --auto-approve true --config ~/.cline-gpt "review and save to gpt-review.md" &
|
||||
pids+=($!)
|
||||
git show | cline --auto-approve true --config ~/.cline-opus "review and save to opus-review.md" &
|
||||
pids+=($!)
|
||||
|
||||
# Wait for each review, and stop if one failed
|
||||
for pid in "${pids[@]}"; do wait "$pid"; done
|
||||
|
||||
# Synthesize
|
||||
cat *-review.md | cline --auto-approve true "create consensus review"
|
||||
cat gemini-review.md gpt-review.md opus-review.md | cline --auto-approve true "create consensus review"
|
||||
```
|
||||
|
||||
<Note>
|
||||
Parallel execution requires managing multiple Cline instances. See [Multi-instance workflows](/usage/cli-overview#automation-patterns) for details.
|
||||
Each `cline` command runs as its own process, so the reviews run at the same time. Give each one a different output file, as above, so that they don't write over each other. `wait` on its own succeeds even when a review fails, so the script saves each review's process ID as it starts and waits for each one. Don't loop over `jobs -p` instead: in the bash 3.2 that macOS ships as `/bin/bash`, it leaves out reviews that have already finished, so a review that fails quickly would be missed.
|
||||
</Note>
|
||||
|
||||
## Extended Thinking for Complex Tasks
|
||||
@@ -177,28 +186,43 @@ The `--thinking <level>` flag sets reasoning effort. Use `--thinking high` or `-
|
||||
### Cost-Optimized PR Review
|
||||
|
||||
```bash
|
||||
set -euo pipefail
|
||||
|
||||
# Remove findings from an earlier run
|
||||
rm -f issues.md
|
||||
|
||||
# Haiku: Quick summary and issue identification
|
||||
gh pr view $PR | cline --auto-approve true --config ~/.cline-haiku \
|
||||
"list all issues to fix, output as JSON"
|
||||
gh pr diff "$PR" | cline --auto-approve true --config ~/.cline-haiku \
|
||||
"list the issues to fix in this diff and write them to issues.md. If there are none, don't create the file."
|
||||
|
||||
# Opus with thinking: Deep analysis only if issues found
|
||||
if [ -s issues.json ]; then
|
||||
if [ -s issues.md ]; then
|
||||
cline --auto-approve true --thinking high --config ~/.cline-opus \
|
||||
"analyze these issues and recommend fixes"
|
||||
"analyze the issues in issues.md and recommend fixes"
|
||||
fi
|
||||
```
|
||||
|
||||
### Security-Focused Multi-Model Scan
|
||||
|
||||
```bash
|
||||
set -euo pipefail
|
||||
|
||||
# Print only Cline's final answer from --json output
|
||||
final_answer() { jq -r 'select(.type == "run_result") | .text'; }
|
||||
|
||||
# Different models have different security perspectives
|
||||
git diff main | cline --auto-approve true --config ~/.cline-gemini "security review" > gemini-sec.md &
|
||||
git diff main | cline --auto-approve true --config ~/.cline-opus "security review" > opus-sec.md &
|
||||
git diff main | cline --auto-approve true --config ~/.cline-codex "security review" > codex-sec.md &
|
||||
wait
|
||||
git diff main | cline --auto-approve true --json --config ~/.cline-gemini "security review" | final_answer > gemini-sec.md &
|
||||
pids=($!)
|
||||
git diff main | cline --auto-approve true --json --config ~/.cline-opus "security review" | final_answer > opus-sec.md &
|
||||
pids+=($!)
|
||||
git diff main | cline --auto-approve true --json --config ~/.cline-gpt "security review" | final_answer > gpt-sec.md &
|
||||
pids+=($!)
|
||||
|
||||
# Wait for each review, and stop if one failed
|
||||
for pid in "${pids[@]}"; do wait "$pid"; done
|
||||
|
||||
# High-priority: Issues all 3 models found
|
||||
cat *-sec.md | cline --auto-approve true "find security issues all 3 reviews mentioned"
|
||||
cat gemini-sec.md opus-sec.md gpt-sec.md | cline --auto-approve true "find security issues all 3 reviews mentioned"
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
@@ -120,7 +120,7 @@ Scan profiles control where Bumblebee looks. `baseline` checks standard global t
|
||||
cline connect telegram -k "<BOT-TOKEN>" --cwd ~/tools/bumblebee
|
||||
```
|
||||
|
||||
Leave this process running. It polls Telegram and delivers scheduled results, so it must stay alive.
|
||||
The connector starts in the background and keeps running after the command returns. It polls Telegram and delivers scheduled results.
|
||||
</Step>
|
||||
|
||||
<Step title="Open the chat">
|
||||
@@ -155,14 +155,14 @@ The bot replies with the new schedule, including its id.
|
||||
|
||||
### Option B: From your terminal
|
||||
|
||||
Create the schedule with the Cline CLI on the same machine and pass the delivery method explicitly. The running Telegram connector delivers the result to its chat:
|
||||
First send `/whereami` to your bot. It replies with the chat's `deliveryThread`, such as `telegram:123456789`. Then create the schedule on the same machine and pass that thread. The running Telegram connector delivers the result to that chat:
|
||||
|
||||
```bash
|
||||
cline schedule create "supply-chain-watch" \
|
||||
--cron "0 8 * * *" \
|
||||
--workspace ~/tools/bumblebee \
|
||||
--delivery-adapter telegram \
|
||||
--delivery-bot <bot-username> \
|
||||
--delivery-thread <deliveryThread> \
|
||||
--prompt "Pull the latest Bumblebee catalogs and scan this machine for compromised packages. Run: git pull --quiet && go build -o bumblebee ./cmd/bumblebee && ./bumblebee scan --profile deep --root \$HOME --exposure-catalog ./threat_intel/ --findings-only. Read the NDJSON output. If any line has record_type set to finding, reply starting with '🚨 COMPROMISE DETECTED' and list each package name, version, ecosystem, and source_file. If there are no findings, reply with exactly '✅ Clean: no compromised packages found.'"
|
||||
```
|
||||
|
||||
@@ -197,8 +197,9 @@ To see a real alert, add a package and version that matches a catalog entry to a
|
||||
|
||||
## Keep it running
|
||||
|
||||
- The connector process (`cline connect telegram`) must stay running for delivery to work. Run it under a process manager (systemd, launchd, `pm2`, or a `tmux`/`screen` session) so it survives reboots.
|
||||
- The connector must be running for delivery to work. It runs in the background, and the hub starts it again whenever the hub itself starts. Neither starts when the computer boots: after a reboot, run `cline hub start`, which brings the connector back.
|
||||
- The hub runs the schedule and starts automatically when you create one. If it is not running, start it with `cline hub start`.
|
||||
- `cline connect --stop telegram` stops the connector and keeps the hub from starting it again.
|
||||
- Manage schedules anytime with `cline schedule list`, `cline schedule pause <id>`, `cline schedule resume <id>`, and `cline schedule delete <id>`.
|
||||
|
||||
## Customize
|
||||
|
||||
+45
-9
@@ -37,21 +37,42 @@ The wizard provides:
|
||||
cline schedule create "PR summary" \
|
||||
--cron "0 9 * * MON-FRI" \
|
||||
--prompt "List all open PRs and their review status" \
|
||||
--workspace /path/to/repo \
|
||||
--model anthropic/claude-sonnet-4-6
|
||||
--workspace /path/to/repo
|
||||
```
|
||||
|
||||
`--cron`, `--prompt` and `--workspace` are required. Other options:
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--provider <id>` and `--model <id>` | Provider and model for the runs. Without them, the schedule uses the provider and model you last used. |
|
||||
| `--mode <act\|plan\|yolo>` | Default `yolo`. `plan` runs have no tools for editing files, and Cline refuses shell commands that usually change files, such as `rm` and `git commit`. Other commands still run, and some of them, such as `python -c`, can write files. In every mode, a scheduled run approves its own tool calls, because nobody is there to approve them. |
|
||||
| `--timeout <seconds>` | Stop a run that takes longer than this |
|
||||
| `--max-parallel <n>` | How many runs of this schedule can run at once (default 1). Runs that come due while it is busy wait their turn. |
|
||||
| `--system-prompt <text>` | Replace the system prompt |
|
||||
| `--tags <list>` | Comma-separated tags. Filter with `cline schedule list --tags`. |
|
||||
| `--disabled` | Create the schedule paused |
|
||||
| `--json` | Print the new schedule as JSON |
|
||||
|
||||
Run `cline schedule create --help` for the full list. The delivery options are under [Routing Results](#routing-results).
|
||||
|
||||
## Managing Schedules
|
||||
|
||||
```bash
|
||||
cline schedule list
|
||||
cline schedule get <schedule-id>
|
||||
cline schedule upcoming
|
||||
cline schedule active
|
||||
cline schedule trigger <schedule-id>
|
||||
cline schedule pause <schedule-id>
|
||||
cline schedule resume <schedule-id>
|
||||
cline schedule update <schedule-id> --cron "0 10 * * *"
|
||||
cline schedule history <schedule-id>
|
||||
cline schedule stats <schedule-id>
|
||||
cline schedule delete <schedule-id>
|
||||
cline schedule executions <schedule-id>
|
||||
```
|
||||
|
||||
`cline schedule export <schedule-id> --to <file>` and `cline schedule import <file>` copy a schedule between machines.
|
||||
|
||||
## Cron Expression Reference
|
||||
|
||||
| Expression | Schedule |
|
||||
@@ -66,6 +87,8 @@ cline schedule executions <schedule-id>
|
||||
| `0 9 * * 1` | Every Monday at 9am |
|
||||
| `0 0 1 * *` | First of every month |
|
||||
|
||||
Days and months can also be names: `0 9 * * MON-FRI` is the same as `0 9 * * 1-5`. Times are in the computer's local time zone.
|
||||
|
||||
## Examples
|
||||
|
||||
### Daily Standup Summary
|
||||
@@ -97,14 +120,27 @@ cline schedule create "Code health" \
|
||||
|
||||
## Routing Results
|
||||
|
||||
Combine schedules with [connectors](/cli/connectors) to send results to messaging platforms:
|
||||
A [connector](/cli/connectors) can post each run's final reply to a chat. The connector must be running when the run finishes, and the schedule must name the chat.
|
||||
|
||||
```bash
|
||||
cline connect telegram -k $BOT_TOKEN
|
||||
The simplest way is to create the schedule from the chat itself. Send this to your bot:
|
||||
|
||||
cline schedule create "Morning briefing" \
|
||||
--cron "0 8 * * *" \
|
||||
--prompt "Summarize overnight activity in the repo"
|
||||
```text
|
||||
/schedule create "Morning briefing" --cron "0 8 * * *" --prompt "Summarize overnight activity in the repo"
|
||||
```
|
||||
|
||||
The schedule runs in the connector's working directory and posts to that chat.
|
||||
|
||||
To create the schedule from a terminal instead, send `/whereami` in the chat first. It replies with the chat's `deliveryAdapter` and `deliveryThread`. Pass them to `cline schedule create`:
|
||||
|
||||
```bash
|
||||
cline schedule create "Morning briefing" \
|
||||
--cron "0 8 * * *" \
|
||||
--prompt "Summarize overnight activity in the repo" \
|
||||
--workspace /path/to/repo \
|
||||
--delivery-adapter telegram \
|
||||
--delivery-thread <deliveryThread>
|
||||
```
|
||||
|
||||
If more than one bot of the same kind is running, add `--delivery-bot <bot-username>` so that only that bot posts. [Supply-Chain Scan Alerts](/cli/samples/supply-chain-alerts) walks through a complete example.
|
||||
|
||||
Scheduling requires the hub. It starts automatically when you create a schedule.
|
||||
|
||||
+22
-43
@@ -4,33 +4,39 @@ sidebarTitle: "Subagents"
|
||||
description: "Run parallel research agents to explore your codebase without filling the main agent's context window."
|
||||
---
|
||||
|
||||
Subagents let Cline spawn focused research agents that run in parallel. Each subagent gets its own prompt and context window, explores the codebase independently, and returns a detailed report to the main agent. This keeps the main agent's context clean while gathering broad information fast.
|
||||
<Warning>
|
||||
Subagents are available in the Cline CLI and Cline Desktop. The VS Code and JetBrains extensions don't use them.
|
||||
</Warning>
|
||||
|
||||
<Tip>
|
||||
Subagents is an experimental feature. Behavior may change in future releases.
|
||||
</Tip>
|
||||
Subagents let Cline hand a focused task to another agent. Each subagent gets its own prompt and context window, does the work, and returns a report to the main agent. This keeps the main agent's context clean, and several subagents can run at the same time.
|
||||
|
||||
## How It Works
|
||||
|
||||
When Cline uses the `use_subagents` tool, it launches independent agents simultaneously. Each one:
|
||||
When Cline uses the `spawn_agent` tool, it starts a subagent. Each one:
|
||||
|
||||
- Gets its own prompt describing what to investigate
|
||||
- Runs with a separate context window and token budget
|
||||
- Can read files, search code, list directories, run read-only commands, and use skills
|
||||
- Cannot edit files, use the browser, access MCP servers, or spawn nested subagents
|
||||
- Returns a result focused on the most relevant file paths for the main agent to read next
|
||||
- Gets its own instructions and task from the main agent
|
||||
- Runs with a separate context window
|
||||
- Has Cline's built-in tools for the current mode. In Act mode it can read and edit files and run commands. In Plan mode it has no tools for editing files, and Cline refuses shell commands that usually change files, such as `rm` and `git commit`. Other commands still run, and some of them, such as `python -c`, can write files. A subagent can start subagents of its own. It doesn't get MCP tools.
|
||||
- Returns its final reply to the main agent
|
||||
|
||||
Subagent costs (tokens and API spend) are tracked separately per subagent and rolled into the task's total cost. You can see per-subagent stats (tool calls, tokens, cost) in the chat UI as they run.
|
||||
The main agent waits for its subagents, then continues. Their token use and cost are added to the session's total.
|
||||
|
||||
## Enabling Subagents
|
||||
## Approvals
|
||||
|
||||
Subagents are enabled by default. Cline decides when parallel research is worth the overhead — you don't need to opt in or call them out in your prompt. To turn subagents off, disable the `use_subagents` tool in Settings → Features → Agent.
|
||||
Approving the `spawn_agent` call approves everything the subagent then does: its own tool calls don't ask for approval. Approval settings don't apply inside a subagent, so read the subagent's task before you approve it.
|
||||
|
||||
This setting applies across all editors (VS Code, JetBrains, CLI).
|
||||
## Turning Subagents Off
|
||||
|
||||
Subagents are on in Act and Plan modes. To turn them off, turn off the `spawn_agent` tool:
|
||||
|
||||
- **CLI:** run `cline`, type `/settings`, and turn off `spawn_agent` on the **Tools** tab.
|
||||
- **Desktop:** open **Customize**, select **Tools**, and turn off `spawn_agent`.
|
||||
|
||||
The setting applies to new sessions in both products.
|
||||
|
||||
## Using Subagents
|
||||
|
||||
When subagents are enabled, Cline picks them up on its own when a task benefits from parallel exploration. You can also nudge it explicitly by asking for parallel research in your prompt.
|
||||
Cline decides when a task is worth splitting. You can also ask for subagents in your prompt.
|
||||
|
||||
Example prompts:
|
||||
|
||||
@@ -38,34 +44,7 @@ Example prompts:
|
||||
- "Spin up subagents to investigate the API routes, the test setup, and the deployment config"
|
||||
- "I'm new to this codebase. Use subagents to map out the main entry points, the routing layer, and the data access patterns"
|
||||
|
||||
Each subagent prompt should describe a focused research question. Cline will run them in parallel and synthesize the results.
|
||||
You can also run only one subagent when the task is small enough that parallel discovery would be unnecessary overhead.
|
||||
|
||||
## Auto-Approve Behavior
|
||||
|
||||
Subagents follow the **Read project files** auto-approve permission. If you have "Read project files" enabled in [Auto Approve](/features/auto-approve), subagent launches will be auto-approved.
|
||||
|
||||
If auto-approve is off, Cline will ask for your approval before launching subagents, showing you the prompts it plans to send.
|
||||
|
||||
## What Subagents Can Do
|
||||
|
||||
Subagents are read-only research agents. Here is what they have access to:
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| `read_file` | Read file contents |
|
||||
| `list_files` | List directory contents |
|
||||
| `search_files` | Regex search across files |
|
||||
| `list_code_definition_names` | List top-level classes, functions, and methods |
|
||||
| `execute_command` | Run read-only commands (`ls`, `grep`, `git log`, `git diff`, etc.) |
|
||||
| `use_skill` | Load and activate skills |
|
||||
|
||||
Subagents cannot write files, apply patches, use the browser, access MCP servers, or perform web searches. They also cannot spawn their own subagents.
|
||||
|
||||
<Note>
|
||||
Commands run by subagents execute in the background and are restricted to read-only operations. Subagents will not run commands that modify files or system state.
|
||||
Subagents also benefit from command pipelines and filters to narrow output quickly before reading files, for example `rg ... | sort | uniq`.
|
||||
</Note>
|
||||
Give each subagent one focused question. Asking for research only, and working in Plan mode, make subagents less likely to change files, but neither stops every change.
|
||||
|
||||
## When to Use Subagents
|
||||
|
||||
|
||||
@@ -34,45 +34,29 @@ const session = await cline.start({
|
||||
|
||||
## How Teams Work
|
||||
|
||||
When teams are enabled, the coordinator agent gets additional tools:
|
||||
When teams are enabled, the coordinator agent gets these tools:
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `team_spawn_teammate` | Create a new agent with a specific role and task |
|
||||
| `team_delegate_task` | Assign a task to an existing teammate |
|
||||
| `team_check_status` | Check the status of delegated tasks |
|
||||
| `team_get_result` | Retrieve the result of a completed task |
|
||||
| Purpose | Tools |
|
||||
|---------|-------|
|
||||
| Teammates | `team_spawn_teammate`, `team_shutdown_teammate`, `team_status` |
|
||||
| Task board | `team_task` (create, list, claim, complete and block tasks) |
|
||||
| Running tasks | `team_run_task`, `team_list_runs`, `team_await_runs`, `team_cancel_run` |
|
||||
| Messages | `team_send_message`, `team_broadcast`, `team_read_mailbox`, `team_mission_log` |
|
||||
| Combined results | `team_create_outcome`, `team_attach_outcome_fragment`, `team_review_outcome_fragment`, `team_finalize_outcome`, `team_list_outcomes` |
|
||||
| Clean-up | `team_cleanup` |
|
||||
|
||||
The coordinator decides how to split work, which agents to create, and how to combine results.
|
||||
Teammates get the same tools except `team_spawn_teammate`, and only the coordinator can shut teammates down or clean up the team. The coordinator decides how to split work, which agents to create, and how to combine results.
|
||||
|
||||
## Team Persistence
|
||||
|
||||
Team state persists across sessions:
|
||||
|
||||
```
|
||||
~/.cline/data/teams/[team-name]/
|
||||
task-board.json # Current tasks and their status
|
||||
mailbox.json # Inter-agent messages
|
||||
mission-log.json # Team activity history
|
||||
```
|
||||
|
||||
Resume a team's work in a new session:
|
||||
|
||||
```bash
|
||||
cline --team-name auth-sprint "Continue -- pick up incomplete tasks"
|
||||
```
|
||||
Team state belongs to the session. Cline saves each team's task board, mailbox, mission log, results and teammates in `~/.cline/data/db/teams.db`, under the session's ID. When the session resumes, its team and teammates come back.
|
||||
|
||||
## Via CLI
|
||||
|
||||
Start a prompt with `/team` to start a team, and resume the session with `cline --id <session-id>` to continue its work. [Agent Teams](/cli/agent-teams) has the details.
|
||||
|
||||
```bash
|
||||
# Start a new team
|
||||
cline --team-name auth-sprint "Plan and implement user auth with tests"
|
||||
|
||||
# Resume work
|
||||
cline --team-name auth-sprint "What's the status? Continue with unfinished tasks."
|
||||
|
||||
# Different team for a different workstream
|
||||
cline --team-name perf-sprint "Profile the API endpoints and optimize the slowest 3"
|
||||
cline "/team Plan and implement user auth with tests"
|
||||
```
|
||||
|
||||
## Sub-Agents vs Teams
|
||||
@@ -82,10 +66,10 @@ The SDK offers two levels of multi-agent coordination:
|
||||
| Feature | Sub-Agents | Teams |
|
||||
|---------|-----------|-------|
|
||||
| Enable with | `enableSpawnAgent: true` | `enableAgentTeams: true` |
|
||||
| Persistence | Within session only | Across sessions |
|
||||
| Persistence | Within session only | Restored when the session resumes |
|
||||
| Coordination | Parent-child | Peer-to-peer with task board |
|
||||
| Shared state | None | Task board, mailbox, mission log |
|
||||
| Best for | One-off delegation | Complex, multi-session projects |
|
||||
| Best for | One-off delegation | Complex projects that you resume over time |
|
||||
|
||||
Sub-agents are lighter weight. The parent agent spawns a child, waits for its result, and continues. No persistent state, no task board.
|
||||
|
||||
@@ -100,7 +84,7 @@ const session = await cline.start({
|
||||
})
|
||||
```
|
||||
|
||||
Teams are for bigger efforts where work spans multiple sessions and agents need to coordinate asynchronously.
|
||||
Teams are for bigger efforts that you come back to, where agents need to coordinate asynchronously.
|
||||
|
||||
## When to Use Teams
|
||||
|
||||
@@ -108,7 +92,7 @@ Teams add overhead. Use them when:
|
||||
|
||||
- The task naturally decomposes into independent subtasks
|
||||
- Different subtasks benefit from different system prompts or specializations
|
||||
- Work spans multiple sessions or days
|
||||
- You will resume the session over several days
|
||||
- You want a persistent record of task delegation and completion
|
||||
|
||||
For simpler cases, a single agent with good tools is usually more efficient than a team.
|
||||
|
||||
@@ -11,7 +11,7 @@ The SDK supports running agents on cron schedules. Scheduled agents persist acro
|
||||
1. You define a schedule (cron expression + prompt + config)
|
||||
2. The SDK stores the schedule and manages execution
|
||||
3. At each trigger time a new session is created and the agent is run
|
||||
4. Results are stored and can be routed to connectors (Slack, email, etc.)
|
||||
4. Results are stored, and the CLI can post them to a chat through a connector (Telegram, Slack, and others)
|
||||
|
||||
Scheduled agents rely on the [hub-spoke architecture](/sdk/architecture/hub-spoke) that is part of `ClineCore`. The hub runs as a background process on your machine. It starts automatically when needed and persists schedules across restarts.
|
||||
|
||||
@@ -25,16 +25,16 @@ const cline = await ClineCore.create({
|
||||
automation: true,
|
||||
})
|
||||
|
||||
await cline.automation.start()
|
||||
|
||||
// Use cline.automation to reconcile specs, ingest events, and list runs.
|
||||
// Automation starts with ClineCore. Pass automation: { autoStart: false }
|
||||
// to start it later with cline.automation.start().
|
||||
const runs = cline.automation.listRuns()
|
||||
```
|
||||
|
||||
`cline.automation` reads schedule files from `~/.cline/cron/`, reconciles them, ingests events and lists runs. [`sdk/examples/cron`](https://github.com/cline/cline/tree/main/sdk/examples/cron) has sample schedule files.
|
||||
|
||||
## Schedule Wizard with Cline CLI
|
||||
|
||||
An easy way to schedule task is to use Cline CLI for scheduling task, if you've already installed via `npm i -g cline`
|
||||
|
||||
Run `cline schedule` to open an interactive menu for creating and managing schedules, browsing execution history, and viewing performance statistics.
|
||||
If you have the Cline CLI installed (`npm i -g cline`), run `cline schedule` to open an interactive menu for creating and managing schedules, browsing execution history, and viewing performance statistics.
|
||||
|
||||
## Creating Schedules with Flags
|
||||
|
||||
@@ -43,8 +43,7 @@ Run `cline schedule` to open an interactive menu for creating and managing sched
|
||||
cline schedule create "PR summary" \
|
||||
--cron "0 9 * * MON-FRI" \
|
||||
--prompt "List all open PRs, their review status, and any that have been open more than 3 days" \
|
||||
--workspace /path/to/repo \
|
||||
--model anthropic/claude-sonnet-4-6
|
||||
--workspace /path/to/repo
|
||||
|
||||
# Every 6 hours
|
||||
cline schedule create "Health check" \
|
||||
@@ -55,9 +54,12 @@ cline schedule create "Health check" \
|
||||
# Monday mornings
|
||||
cline schedule create "Weekly digest" \
|
||||
--cron "0 8 * * MON" \
|
||||
--prompt "Summarize last week's commits, PRs merged, and issues closed"
|
||||
--prompt "Summarize last week's commits, PRs merged, and issues closed" \
|
||||
--workspace /path/to/repo
|
||||
```
|
||||
|
||||
[Scheduling](/cli/scheduling) lists the other options, such as `--provider` and `--model`.
|
||||
|
||||
## Managing Schedules
|
||||
|
||||
```bash
|
||||
@@ -77,7 +79,7 @@ cline schedule resume <schedule-id>
|
||||
cline schedule delete <schedule-id>
|
||||
|
||||
# View execution history
|
||||
cline schedule executions <schedule-id>
|
||||
cline schedule history <schedule-id>
|
||||
```
|
||||
|
||||
## Cron Expression Reference
|
||||
@@ -120,24 +122,12 @@ cline schedule create "Code health" \
|
||||
--workspace /path/to/project
|
||||
```
|
||||
|
||||
## Concurrency and Resource Limits
|
||||
## Concurrency Limits
|
||||
|
||||
The scheduler enforces limits to prevent resource exhaustion:
|
||||
|
||||
- Schedules have configurable concurrency limits
|
||||
- If a previous execution is still running when the next trigger fires, the new execution is queued or skipped (configurable)
|
||||
- The hub monitors resource usage and can pause schedules if the system is under load
|
||||
- Each schedule runs one execution at a time unless you raise `--max-parallel`. An execution that comes due while the schedule is busy waits in the queue.
|
||||
- The hub runs at most 10 scheduled executions at once across all schedules. `ClineCore.create({ automation: { globalMaxConcurrency } })` changes this limit for the SDK's own scheduler.
|
||||
- If the hub was stopped when a run was due, it queues one catch-up run when it starts again, not one for each missed time.
|
||||
|
||||
## Routing Results
|
||||
|
||||
Combine scheduled agents with [connectors](/cli/connectors) in CLI to route results to messaging platforms:
|
||||
|
||||
```bash
|
||||
# Start a Telegram connector
|
||||
cline connect telegram -k $BOT_TOKEN
|
||||
|
||||
# Schedule an agent whose output gets sent to Telegram
|
||||
cline schedule create "Morning briefing" \
|
||||
--cron "0 8 * * *" \
|
||||
--prompt "Summarize overnight activity in the repo"
|
||||
```
|
||||
The CLI can post each run's final reply to a chat through a running [connector](/cli/connectors). [Routing Results](/cli/scheduling#routing-results) shows how to set the chat.
|
||||
|
||||
Reference in New Issue
Block a user