chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,57 @@
|
||||
---
|
||||
title: "Agent Teams"
|
||||
sidebarTitle: "Agent Teams"
|
||||
description: "Coordinate multiple agents working together on complex tasks from the CLI."
|
||||
---
|
||||
<Warning>
|
||||
This feature currently only applies to Cline SDK, CLI, and Kanban. This feature is not applicable on VSCode and JetBrains Extension for now.
|
||||
</Warning>
|
||||
|
||||
|
||||
Agent teams let you break complex work across multiple agents that coordinate through a shared task board. One agent acts as the coordinator, delegating subtasks to specialist agents.
|
||||
|
||||
## Starting a Team
|
||||
|
||||
```bash
|
||||
cline --team-name auth-sprint "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.
|
||||
|
||||
## Resuming Team Work
|
||||
|
||||
Team state persists across sessions. Resume where you left off:
|
||||
|
||||
```bash
|
||||
cline --team-name auth-sprint "Continue with incomplete tasks"
|
||||
```
|
||||
|
||||
## Interactive Mode
|
||||
|
||||
In interactive mode, use the `/team` slash command:
|
||||
|
||||
```
|
||||
/team Plan and implement a REST API with tests
|
||||
```
|
||||
|
||||
## Team State
|
||||
|
||||
Team state is stored at `~/.cline/data/teams/[team-name]/` and includes:
|
||||
|
||||
- Task board with current tasks and status
|
||||
- Inter-agent mailbox
|
||||
- Mission log with activity history
|
||||
|
||||
## Disabling Teams
|
||||
|
||||
Teams are enabled by default. Disable them with:
|
||||
|
||||
```bash
|
||||
cline --no-teams "your prompt"
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
See the [SDK Multi-Agent Teams guide](/sdk/guides/multi-agent-teams) for the programmatic API.
|
||||
@@ -0,0 +1,305 @@
|
||||
---
|
||||
title: "CLI Reference"
|
||||
description: "Complete command reference for Cline CLI including all commands, flags, and configuration options."
|
||||
---
|
||||
|
||||
```bash
|
||||
cline --help # Show all commands
|
||||
cline <command> --help # Show help for a specific command
|
||||
```
|
||||
|
||||
## Synopsis
|
||||
|
||||
```bash
|
||||
cline [options] [command] [prompt]
|
||||
```
|
||||
|
||||
## Help Menu (Source of Truth)
|
||||
|
||||
```text
|
||||
Usage: cline [options] [command] [prompt]
|
||||
|
||||
Cline CLI - AI coding assistant in your terminal
|
||||
|
||||
Arguments:
|
||||
prompt Your prompt. Default to start in act mode with auto-approve enabled.
|
||||
|
||||
Options:
|
||||
-V, --version Output the version number
|
||||
-p, --plan Run in plan mode
|
||||
--json Output messages as JSON instead of styled text
|
||||
--auto-approve <boolean> Set tool auto-approval for all tools (default: true)
|
||||
-t, --timeout <seconds> Optional timeout in seconds (default: 0 for no timeout)
|
||||
-m, --model <model-id> Model to use for the session with the selected provider
|
||||
-v, --verbose Show verbose output
|
||||
-c, --cwd <path> Working directory
|
||||
--config <path> Configuration directory (default: ~/.cline/data/settings)
|
||||
--data-dir <path> Use isolated local state at this directory path (default: ~/.cline)
|
||||
--thinking <level> Set reasoning effort level between none|low|medium|high|xhigh (default: medium)
|
||||
--retries <count> Maximum consecutive mistakes (retries) before halting
|
||||
--hooks-dir <path> Directory path to additional hooks for runtime hook injection (default: ~/.cline/hooks)
|
||||
--acp Run in Agent Client Protocol (ACP) mode for editor integration
|
||||
-i, --tui Open the terminal user interface (TUI) for interactive sessions
|
||||
--id <session-id> Resume an existing session by ID
|
||||
-k, --key <api-key> API key override for this run
|
||||
-P, --provider <id> Provider id (default: cline)
|
||||
-s, --system <system-prompt> Override the default system prompt
|
||||
-z, --zen Start a session that runs in the background hub
|
||||
-h, --help display help for command
|
||||
|
||||
Commands:
|
||||
auth [options] [provider] Authenticate a provider and configure what model is used
|
||||
config [options] Show current configuration
|
||||
connect [options] [adapter] Connect to an editor or IDE adapter
|
||||
mcp Manage MCP servers
|
||||
dev Developer tools and utilities
|
||||
doctor Diagnose and fix configuration issues
|
||||
history|h [options] List session history or manage saved sessions
|
||||
hook Handle a hook payload from stdin
|
||||
plugin Manage Cline Plugins
|
||||
schedule Manage scheduled tasks
|
||||
hub Manage the local hub daemon
|
||||
update [options] Check for updates and install if available
|
||||
version Show Cline CLI version number
|
||||
kanban Launch the kanban app and exit
|
||||
```
|
||||
|
||||
## Global Options
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `-V, --version` | Output the version number |
|
||||
| `-p, --plan` | Run in plan mode |
|
||||
| `--json` | Output messages as JSON instead of styled text |
|
||||
| `--auto-approve <boolean>` | Set tool auto-approval for all tools (default: `true`) |
|
||||
| `-t, --timeout <seconds>` | Optional timeout in seconds (default: `0` for no timeout) |
|
||||
| `-m, --model <model-id>` | Model to use for the session with the selected provider |
|
||||
| `-v, --verbose` | Show verbose output |
|
||||
| `-c, --cwd <path>` | Working directory |
|
||||
| `--config <path>` | Configuration directory (default: `~/.cline/data/settings`) |
|
||||
| `--data-dir <path>` | Use isolated local state at this directory path (default: `~/.cline`) |
|
||||
| `--thinking <level>` | Set reasoning effort: `none\|low\|medium\|high\|xhigh` (default `medium`) |
|
||||
| `--retries <count>` | Maximum consecutive mistakes (retries) before halting |
|
||||
| `--hooks-dir <path>` | Directory path to additional hooks for runtime hook injection (default: `~/.cline/hooks`) |
|
||||
| `--acp` | Run in Agent Client Protocol (ACP) mode for editor integration |
|
||||
| `-i, --tui` | Open the terminal user interface (TUI) for interactive sessions |
|
||||
| `--id <session-id>` | Resume an existing session by ID |
|
||||
| `-k, --key <api-key>` | API key override for this run |
|
||||
| `-P, --provider <id>` | Provider id (default: `cline`) |
|
||||
| `-s, --system <system-prompt>` | Override the default system prompt |
|
||||
| `-z, --zen` | Start a session that runs in the background hub |
|
||||
| `-h, --help` | Display help for command |
|
||||
|
||||
## Commands
|
||||
|
||||
### `cline` (default)
|
||||
|
||||
Start a task or enter interactive mode.
|
||||
|
||||
```bash
|
||||
cline
|
||||
cline "your prompt here"
|
||||
cline "Run tests and fix failures"
|
||||
echo "prompt" | cline
|
||||
```
|
||||
|
||||
### `auth [options] [provider]`
|
||||
|
||||
Configure authentication with an AI provider.
|
||||
|
||||
```bash
|
||||
cline auth
|
||||
```
|
||||
|
||||
### `config [options]`
|
||||
|
||||
Show current configuration.
|
||||
|
||||
```bash
|
||||
cline config
|
||||
```
|
||||
|
||||
### `connect [options] [adapter]`
|
||||
|
||||
Connect to messaging platforms. See [Connectors](/cli/connectors).
|
||||
|
||||
```bash
|
||||
cline connect
|
||||
cline connect [adapter]
|
||||
```
|
||||
|
||||
### `mcp`
|
||||
|
||||
Manage MCP servers. See [MCP](/mcp/mcp-overview).
|
||||
|
||||
```bash
|
||||
cline mcp
|
||||
```
|
||||
|
||||
### `dev`
|
||||
|
||||
Developer tools and utilities.
|
||||
|
||||
```bash
|
||||
cline dev
|
||||
```
|
||||
|
||||
### `doctor`
|
||||
|
||||
Diagnose and fix configuration issues.
|
||||
|
||||
```bash
|
||||
cline doctor
|
||||
```
|
||||
|
||||
### `history|h [options]`
|
||||
|
||||
List session history or manage saved sessions.
|
||||
|
||||
```bash
|
||||
cline history
|
||||
cline h
|
||||
```
|
||||
|
||||
### `hook`
|
||||
|
||||
Handle a hook payload from stdin.
|
||||
|
||||
```bash
|
||||
cat payload.json | cline hook
|
||||
```
|
||||
|
||||
### `plugin`
|
||||
|
||||
Manage Cline plugins. Install plugins from file URLs, npm, git repositories, or local paths. See [Plugins](/customization/plugins) for full details and the plugin manifest format.
|
||||
|
||||
```bash
|
||||
cline plugin install <source> # Install a plugin
|
||||
cline plugin i <source> # Shorthand alias
|
||||
```
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--npm` | Treat source as an npm package |
|
||||
| `--git` | Treat source as a git repository |
|
||||
| `--force` | Replace an existing install for the same source |
|
||||
| `--json` | Output result as JSON |
|
||||
| `--cwd <path>` | Install to `<path>/.cline/plugins` instead of the global directory |
|
||||
|
||||
Try it with the [TypeScript Navigation Plugin](https://github.com/cline/typescript-lsp-plugin):
|
||||
|
||||
```bash
|
||||
cline plugin install https://github.com/cline/typescript-lsp-plugin.git
|
||||
```
|
||||
|
||||
### `schedule`
|
||||
|
||||
Manage scheduled agents. See [Scheduling](/cli/scheduling).
|
||||
|
||||
```bash
|
||||
cline schedule
|
||||
```
|
||||
|
||||
### `hub`
|
||||
|
||||
Manage the local hub daemon.
|
||||
|
||||
```bash
|
||||
cline hub
|
||||
```
|
||||
|
||||
### `update [options]`
|
||||
|
||||
Check for updates and install if available.
|
||||
|
||||
```bash
|
||||
cline update
|
||||
```
|
||||
|
||||
### `version`
|
||||
|
||||
Show Cline CLI version number.
|
||||
|
||||
```bash
|
||||
cline version
|
||||
cline -V
|
||||
```
|
||||
|
||||
### `kanban`
|
||||
|
||||
Launch the kanban app and exit.
|
||||
|
||||
```bash
|
||||
cline kanban
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `CLINE_DATA_DIR` | Custom configuration directory (replaces `~/.cline/data/`) |
|
||||
| `CLINE_HUB_ADDRESS` | Override hub address (default: `127.0.0.1:25463`) |
|
||||
| `CLINE_SESSION_BACKEND_MODE` | Force backend mode (`local`, `hub`, `remote`, `auto`) |
|
||||
| `CLINE_SANDBOX_DATA_DIR` | Sandbox session storage directory |
|
||||
| `CLINE_SANDBOX` | Enable sandbox mode |
|
||||
| `CLINE_HOOKS_DIR` | Additional hooks directory |
|
||||
| `CLINE_BUILD_ENV` | Set to `development` for debug features |
|
||||
| `CLINE_DEBUG_PORT_BASE` | Base port for Node.js inspector |
|
||||
| `CLINE_COMMAND_PERMISSIONS` | JSON policy restricting shell commands (see below) |
|
||||
|
||||
### CLINE_COMMAND_PERMISSIONS
|
||||
|
||||
Restrict which shell commands the agent can execute:
|
||||
|
||||
```bash
|
||||
export CLINE_COMMAND_PERMISSIONS='{"allow": ["npm *", "git *"], "deny": ["rm -rf *", "sudo *"]}'
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `allow` | `string[]` | Glob patterns for allowed commands. If set, only matching commands are permitted. |
|
||||
| `deny` | `string[]` | Glob patterns for denied commands. Deny rules always take precedence. |
|
||||
| `allowRedirects` | `boolean` | Whether to allow shell redirects (`>`, `>>`, `<`). Default: `false`. |
|
||||
|
||||
## JSON Output Format
|
||||
|
||||
When using `--json`, each message is a JSON object on its own line:
|
||||
|
||||
```json
|
||||
{"type": "say", "text": "I'll create the file now.", "ts": 1760501486669, "say": "text"}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `type` | `"ask"` or `"say"` | Message category |
|
||||
| `text` | `string` | Message content |
|
||||
| `ts` | `number` | Unix timestamp in milliseconds |
|
||||
| `say` | `string` | Subtype when `type` is `"say"` |
|
||||
| `ask` | `string` | Subtype when `type` is `"ask"` |
|
||||
| `reasoning` | `string` | Model reasoning (if available) |
|
||||
| `partial` | `boolean` | `true` while streaming |
|
||||
|
||||
## Configuration Files
|
||||
|
||||
```
|
||||
~/.cline/
|
||||
data/
|
||||
settings/
|
||||
providers.json # API keys and provider config
|
||||
rules/ # Global rules
|
||||
skills/ # Global skills
|
||||
teams/ # Team state
|
||||
sessions/ # Session database (SQLite)
|
||||
logs/
|
||||
hub-daemon.log # Hub logs
|
||||
plugins/ # Global plugins
|
||||
_installed/ # Managed by `cline plugin install`
|
||||
|
||||
.cline/ # Project root
|
||||
rules/ # Project rules
|
||||
skills/ # Project skills
|
||||
hooks/ # Lifecycle hooks
|
||||
plugins/ # Project plugins
|
||||
mcp.json # MCP server config
|
||||
agents.yaml # Agent definitions
|
||||
```
|
||||
@@ -0,0 +1,286 @@
|
||||
---
|
||||
title: "Connectors"
|
||||
sidebarTitle: "Connectors"
|
||||
description: "Connect the CLI to Telegram, Slack, Discord, Google Chat, WhatsApp, etc."
|
||||
---
|
||||
<Warning>
|
||||
This feature currently only applies to Cline CLI.
|
||||
</Warning>
|
||||
|
||||
Connectors let you chat with your agent from messaging platforms. Each incoming message creates or continues an agent session, and the agent's response is sent back to the conversation.
|
||||
|
||||
## Setup Wizard
|
||||
|
||||
Run `cline connect` to open an interactive wizard that guides you through platform selection, credential entry, security configuration, and advanced options (provider, model, system prompt, agent mode).
|
||||
|
||||
```bash
|
||||
cline connect
|
||||
```
|
||||
|
||||
## Supported Platforms
|
||||
|
||||
| Platform | Direct Command | Required Credentials |
|
||||
|----------|---------------|---------------------|
|
||||
| Telegram | `cline connect telegram` | Bot token |
|
||||
| Slack | `cline connect slack` | Bot token plus webhook signing secret/base URL or socket app token |
|
||||
| Discord | `cline connect discord` | Application ID, bot token, public key, base URL |
|
||||
| Google Chat | `cline connect gchat` | Service account credentials JSON, base URL |
|
||||
| WhatsApp | `cline connect whatsapp` | Phone number ID, access token, app secret, verify token, base URL |
|
||||
| Linear | `cline connect linear` | API key, webhook signing secret, base URL |
|
||||
|
||||
## Telegram
|
||||
|
||||
<Steps>
|
||||
<Step title="Create a Telegram bot">
|
||||
Open Telegram and start a chat with [@BotFather](https://t.me/BotFather). Send `/newbot` and follow the prompts:
|
||||
|
||||
1. Enter a display name (e.g., "Cline")
|
||||
2. Enter a username ending in `bot` (e.g., `cline_myname_bot`). Must be unique across Telegram.
|
||||
3. BotFather responds with your bot token (looks like `7123456789:AAH...`)
|
||||
</Step>
|
||||
|
||||
<Step title="Start the connector">
|
||||
```bash
|
||||
cline connect telegram -k <BOT-TOKEN>
|
||||
```
|
||||
|
||||
The connector discovers the bot username from the token. Use `--bot-username` only if you need to override it.
|
||||
</Step>
|
||||
|
||||
<Step title="Chat with your bot">
|
||||
Open Telegram, search for your bot's username, and send a message. The agent processes it and replies in the chat.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Security
|
||||
|
||||
By default, anyone who finds your bot can message it and it will execute tasks on your machine. The `cline connect` wizard asks whether to restrict Telegram access and can configure this for you.
|
||||
|
||||
<Steps>
|
||||
<Step title="Get your Telegram user ID">
|
||||
Message [@userinfobot](https://t.me/userinfobot) on Telegram. It replies with your numeric user ID immediately.
|
||||
</Step>
|
||||
|
||||
<Step title="Use the wizard">
|
||||
```bash
|
||||
cline connect
|
||||
```
|
||||
|
||||
Choose Telegram, enter the bot token, answer yes to access restriction, then enter your user ID.
|
||||
</Step>
|
||||
|
||||
<Step title="Or pass the flag manually">
|
||||
Replace `12345` with your Telegram user ID:
|
||||
|
||||
```bash
|
||||
cline connect telegram -k <BOT-TOKEN> \
|
||||
--allowed-user-id 12345
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Use `--hook-command` only when you need custom access logic. The hook receives each incoming message with sender info via stdin. Your script returns `{"action": "allow"}` or `{"action": "deny", "message": "reason"}`. Without `--allowed-user-id` or `--hook-command`, everything is auto-approved, so restrict Telegram bots that can reach a running Cline instance.
|
||||
|
||||
## Slack
|
||||
|
||||
Slack supports webhook mode and socket mode. Each Slack thread maps to an agent session, so the agent maintains conversation context within a thread.
|
||||
|
||||
Webhook mode requires a bot token, signing secret, and public base URL:
|
||||
|
||||
```bash
|
||||
cline connect slack \
|
||||
--bot-token <BOT-TOKEN> \
|
||||
--signing-secret <SECRET> \
|
||||
--base-url <URL>
|
||||
```
|
||||
|
||||
Configure the Slack app's event subscription and interactivity request URLs to `<URL>/api/webhooks/slack`.
|
||||
|
||||
Socket mode requires a bot token and an app-level token with the `connections:write` scope:
|
||||
|
||||
```bash
|
||||
cline connect slack \
|
||||
--bot-token <BOT-TOKEN> \
|
||||
--app-token <APP-LEVEL-TOKEN>
|
||||
```
|
||||
|
||||
Enable Socket Mode in the Slack app. Socket mode does not need a public request URL and is single-workspace only.
|
||||
|
||||
## Discord
|
||||
|
||||
Requires a Discord application ID, bot token, public key, and public base URL.
|
||||
The connector listens for Discord interactions at `/api/webhooks/discord` and
|
||||
also starts a Discord gateway listener for mentions, replies, reactions, and DMs.
|
||||
|
||||
<Steps>
|
||||
<Step title="Create a Discord application and bot">
|
||||
Open [Discord Developer Portal](https://discord.com/developers/applications)
|
||||
and create an application.
|
||||
|
||||
1. In **General Information**, copy the **Application ID** and **Public Key**.
|
||||
2. In **Bot**, create a bot if one does not exist, then reset and copy the bot token.
|
||||
3. Enable **Message Content Intent** if you want normal messages, replies, and DMs to include text content.
|
||||
</Step>
|
||||
|
||||
<Step title="Expose a public base URL">
|
||||
For local development, use a tunnel such as ngrok:
|
||||
|
||||
```bash
|
||||
ngrok http 8788
|
||||
```
|
||||
|
||||
Copy the HTTPS forwarding URL. This is your connector base URL, for example
|
||||
`https://1234-5678.ngrok-free.app`.
|
||||
</Step>
|
||||
|
||||
<Step title="Start the connector">
|
||||
```bash
|
||||
cline connect discord \
|
||||
--application-id <ID> \
|
||||
--bot-token <TOKEN> \
|
||||
--public-key <KEY> \
|
||||
--base-url <URL> \
|
||||
--port 8788 \
|
||||
--cwd /path/to/repo \
|
||||
--enable-tools
|
||||
```
|
||||
|
||||
`--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.
|
||||
</Step>
|
||||
|
||||
<Step title="Configure the Discord interactions endpoint">
|
||||
In the Discord Developer Portal, set **Interactions Endpoint URL** to:
|
||||
|
||||
```text
|
||||
<base-url>/api/webhooks/discord
|
||||
```
|
||||
|
||||
For example:
|
||||
|
||||
```text
|
||||
https://1234-5678.ngrok-free.app/api/webhooks/discord
|
||||
```
|
||||
|
||||
You can verify the connector is reachable with:
|
||||
|
||||
```bash
|
||||
curl <base-url>/health
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Invite the bot to a test server">
|
||||
In **OAuth2 > URL Generator**, select the `bot` and
|
||||
`applications.commands` scopes, then give the bot permission to send
|
||||
messages and read message history. Open the generated URL and install the bot
|
||||
into your test server.
|
||||
</Step>
|
||||
|
||||
<Step title="Chat with the bot">
|
||||
Mention the bot in a server channel, reply in a bot-created thread, or DM the
|
||||
bot. Each Discord conversation keeps its own agent session and context.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Discord Command Reference
|
||||
|
||||
Send these commands in Discord:
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/help` or `/start` | Show connector help |
|
||||
| `/new` or `/clear` | Start a fresh session for this Discord conversation |
|
||||
| `/whereami` | Show thread, channel, DM state, `cwd`, `workspaceRoot`, tools, and yolo state |
|
||||
| `/tools [on\|off\|toggle]` | View or change whether repo/file/shell tools are allowed |
|
||||
| `/yolo [on\|off\|toggle]` | View or change automatic tool approval |
|
||||
| `/cwd [path]` | View or change the working directory for this conversation |
|
||||
| `/schedule create/list/trigger/delete` | Manage scheduled workflows targeting this conversation |
|
||||
| `/abort` | Stop the current task |
|
||||
| `/exit` | Stop the connector |
|
||||
|
||||
Normal messages are treated as agent tasks. If a task is already running, normal
|
||||
messages steer the active task.
|
||||
|
||||
### Discord Security
|
||||
|
||||
By default, anyone who can reach the bot can ask it to run tasks. Restrict access
|
||||
with `--hook-command`. The hook receives the Discord user as a participant key
|
||||
such as `discord:user:123456789`.
|
||||
|
||||
```bash
|
||||
cline connect discord \
|
||||
--application-id <ID> \
|
||||
--bot-token <TOKEN> \
|
||||
--public-key <KEY> \
|
||||
--base-url <URL> \
|
||||
--hook-command 'jq -r ".payload.actor.participantKey" | grep -q "discord:user:123456789" && echo "{\"action\":\"allow\"}" || echo "{\"action\":\"deny\",\"message\":\"unauthorized\"}"'
|
||||
```
|
||||
|
||||
## Google Chat
|
||||
|
||||
Requires a service account credentials JSON file and public base URL.
|
||||
|
||||
```bash
|
||||
cline connect gchat --credentials <JSON> --base-url <URL>
|
||||
```
|
||||
|
||||
## WhatsApp
|
||||
|
||||
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>
|
||||
```
|
||||
|
||||
## Linear
|
||||
|
||||
Requires an API key, webhook signing secret, and public base URL.
|
||||
|
||||
```bash
|
||||
cline connect linear --api-key <KEY> --signing-secret <SECRET> --base-url <URL>
|
||||
```
|
||||
|
||||
## Managing Connectors
|
||||
|
||||
```bash
|
||||
# Stop all connectors
|
||||
cline connect --stop
|
||||
|
||||
# Stop a specific connector
|
||||
cline connect telegram --stop
|
||||
```
|
||||
|
||||
## Hook Command Protocol
|
||||
|
||||
The `--hook-command` pattern works across all connectors. The script receives a JSON payload via stdin:
|
||||
|
||||
```json
|
||||
{
|
||||
"payload": {
|
||||
"actor": {
|
||||
"participantKey": "telegram:id:12345",
|
||||
"displayName": "User Name"
|
||||
},
|
||||
"message": "The incoming message text"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Return `{"action": "allow"}` or `{"action": "deny", "message": "reason"}`.
|
||||
|
||||
## Running Multiple Connectors
|
||||
|
||||
Multiple connectors can run simultaneously. They all share the same hub:
|
||||
|
||||
```bash
|
||||
# Terminal 1
|
||||
cline connect telegram -k $TELEGRAM_TOKEN
|
||||
|
||||
# Terminal 2
|
||||
cline connect slack --bot-token $SLACK_TOKEN --signing-secret $SECRET --base-url $URL
|
||||
```
|
||||
|
||||
Connectors require the hub. Start it with `cline hub start` if it doesn't auto-start.
|
||||
@@ -0,0 +1,304 @@
|
||||
---
|
||||
title: "GitHub Actions Integration"
|
||||
description: "Automatically respond to GitHub issues by mentioning @cline in comments using Cline CLI in GitHub Actions."
|
||||
---
|
||||
|
||||
Automate GitHub issue analysis with AI. Mention `@cline` in any issue comment to trigger an autonomous investigation that reads files, analyzes code, and provides actionable insights - all running automatically in GitHub Actions.
|
||||
|
||||
|
||||
<Note>
|
||||
**New to Cline CLI?** This sample assumes you understand Cline CLI basics and have completed the [Installation Guide](https://docs.cline.bot/getting-started/installing-cline). If you're new to Cline CLI, we recommend starting with the [GitHub RCA sample](./github-issue-rca) first, as it's simpler and will help you understand the fundamentals before setting up GitHub Actions.
|
||||
</Note>
|
||||
|
||||
## The Workflow
|
||||
|
||||
Trigger Cline by mentioning `@cline` in any issue comment:
|
||||
|
||||
<Frame>
|
||||
<img src="https://storage.googleapis.com/cline_public_images/ss0a-comment.png" alt="Issue comment with @cline mention" width="600" />
|
||||
</Frame>
|
||||
|
||||
Cline's automated analysis appears as a new comment, with insights drawn from your actual codebase:
|
||||
|
||||
<Frame>
|
||||
<img src="https://storage.googleapis.com/cline_public_images/ss0b-final.png" alt="Automated analysis response from Cline" width="600" />
|
||||
</Frame>
|
||||
|
||||
The entire investigation runs autonomously in GitHub Actions - from file exploration to posting results.
|
||||
|
||||
Let's configure your repository.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you begin, you'll need:
|
||||
|
||||
- **Cline CLI knowledge** - Completed the [Installation Guide](https://docs.cline.bot/getting-started/installing-cline) and understand basic usage
|
||||
- **GitHub repository** - With admin access to configure Actions and secrets
|
||||
- **GitHub Actions familiarity** - Basic understanding of workflows and CI/CD
|
||||
- **API provider account** - OpenRouter, Anthropic, or similar with API key
|
||||
|
||||
## Setup
|
||||
|
||||
### 1. Copy the Workflow File
|
||||
|
||||
|
||||
|
||||
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`:
|
||||
|
||||
<Accordion title="Click to view the complete cline-responder.yml workflow">
|
||||
```yaml
|
||||
name: Cline Issue Assistant
|
||||
|
||||
on:
|
||||
issue_comment:
|
||||
types: [created, edited]
|
||||
|
||||
permissions:
|
||||
issues: write
|
||||
|
||||
jobs:
|
||||
respond:
|
||||
runs-on: ubuntu-latest
|
||||
environment: cline-actions
|
||||
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
|
||||
|
||||
# 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'
|
||||
|
||||
- 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
|
||||
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
|
||||
|
||||
- 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 }}
|
||||
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"
|
||||
|
||||
- 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 }}
|
||||
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)"
|
||||
});
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Warning>
|
||||
**You MUST edit the workflow file before committing!**
|
||||
|
||||
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.
|
||||
|
||||
### 2. Configure API Keys
|
||||
|
||||
Add your AI provider API keys as repository secrets:
|
||||
|
||||
1. Go to your GitHub repository
|
||||
2. Navigate to **Settings** → **Environment** and Add a new environment.
|
||||
|
||||
<Frame>
|
||||
<img src="https://storage.googleapis.com/cline_public_images/ss01-environment.png" alt="Navigate to Actions secrets" width="600" />
|
||||
</Frame>
|
||||
|
||||
Make sure to name it "cline-actions" so that it matches the `environment`
|
||||
value at the top of the `cline-responder.yml` file.
|
||||
|
||||
3. Click **New repository secret**
|
||||
4. Add a secret for the `OPENROUTER_API_KEY` with a value of an API key from
|
||||
[openrouter.com](https://openrouter.com).
|
||||
|
||||
<Frame>
|
||||
<img src="https://storage.googleapis.com/cline_public_images/ss02-api-key.png" alt="Add API key secret" width="600" />
|
||||
</Frame>
|
||||
|
||||
5. Verify your secret is configured:
|
||||
|
||||
<Frame>
|
||||
<img src="https://storage.googleapis.com/cline_public_images/ss03-ready.png" alt="API key configured" width="600" />
|
||||
</Frame>
|
||||
|
||||
Now you're ready to supply Cline with the credentials it needs in a GitHub Action.
|
||||
|
||||
### 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:
|
||||
|
||||
```bash
|
||||
# In your repository root
|
||||
mkdir -p git-scripts
|
||||
# Create and edit the file with your preferred editor
|
||||
nano git-scripts/analyze-issue.sh # or use vim, code, etc.
|
||||
```
|
||||
|
||||
<Accordion title="Click to view the complete analyze-issue.sh script">
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Analyze a GitHub issue using Cline CLI
|
||||
|
||||
if [ -z "$1" ]; then
|
||||
echo "Usage: $0 <github-issue-url> [prompt]"
|
||||
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?'"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Gather the args
|
||||
ISSUE_URL="$1"
|
||||
PROMPT="${2:-What is the root cause of this issue?}"
|
||||
|
||||
# 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'
|
||||
```
|
||||
|
||||
After pasting the script content, make it executable:
|
||||
```bash
|
||||
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.
|
||||
|
||||
### 4. Commit and Push
|
||||
|
||||
```bash
|
||||
git add .github/workflows/cline-responder.yml
|
||||
git add git-scripts/analyze-issue.sh
|
||||
git commit -m "Add Cline issue assistant workflow"
|
||||
git push
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
Once set up, simply mention `@cline` in any issue comment:
|
||||
|
||||
```text
|
||||
@cline what's causing this error?
|
||||
|
||||
@cline analyze the root cause
|
||||
|
||||
@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.
|
||||
|
||||
## How It Works
|
||||
|
||||
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. **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
|
||||
|
||||
## Related Samples
|
||||
|
||||
- **[github-issue-rca](./github-issue-rca)**: The reusable script that powers this integration
|
||||
@@ -0,0 +1,340 @@
|
||||
---
|
||||
title: "GitHub Issue RCA Sample"
|
||||
description: "Automated GitHub issue analysis using Cline CLI to identify root causes."
|
||||
---
|
||||
|
||||
Automated GitHub issue analysis using Cline CLI. This script uses Cline's autonomous AI capabilities to fetch, analyze, and identify root causes of GitHub issues, outputting clean, parseable results that can be easily integrated into your development workflows.
|
||||
|
||||
<Note>
|
||||
**New to Cline CLI?** This sample assumes you have already completed the [Installation Guide](https://docs.cline.bot/getting-started/installing-cline) and authenticated with `cline auth`. If you haven't set up Cline CLI yet, please start there first.
|
||||
</Note>
|
||||
|
||||
<Frame>
|
||||
<img src="https://storage.googleapis.com/cline_public_images/cli-rca.gif" alt="CLI Root Cause Analysis Demo" width="600" />
|
||||
</Frame>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
This sample assumes you have already:
|
||||
|
||||
- **Cline CLI** installed and authenticated ([Installation Guide](https://docs.cline.bot/getting-started/installing-cline))
|
||||
- **At least one AI model provider** configured (e.g., OpenRouter, Anthropic, OpenAI)
|
||||
- **Basic familiarity** with Cline CLI commands
|
||||
|
||||
Additionally, you'll need:
|
||||
|
||||
- **GitHub CLI** (`gh`) installed and authenticated
|
||||
- **jq** installed for JSON parsing
|
||||
- **bash** shell (or compatible shell)
|
||||
|
||||
### Installation Instructions
|
||||
|
||||
#### macOS
|
||||
|
||||
<Note>
|
||||
These instructions require [Homebrew](https://brew.sh/) to be installed. If you don't have Homebrew, install it first by running:
|
||||
```bash
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||||
```
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
# Install GitHub CLI
|
||||
brew install gh
|
||||
|
||||
# Install jq
|
||||
brew install jq
|
||||
|
||||
# Authenticate with GitHub
|
||||
gh auth login
|
||||
```
|
||||
|
||||
#### Linux
|
||||
|
||||
```bash
|
||||
# Install GitHub CLI (Debian/Ubuntu)
|
||||
sudo apt install gh
|
||||
|
||||
# Or for other Linux distributions, see: https://cli.github.com/manual/installation
|
||||
|
||||
# Install jq (Debian/Ubuntu)
|
||||
sudo apt install jq
|
||||
|
||||
# Authenticate with GitHub
|
||||
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**
|
||||
|
||||
<Accordion title="Click to view the complete analyze-issue.sh script">
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Analyze a GitHub issue using Cline CLI
|
||||
|
||||
if [ -z "$1" ]; then
|
||||
echo "Usage: $0 <github-issue-url> [prompt]"
|
||||
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?'"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Gather the args
|
||||
ISSUE_URL="$1"
|
||||
PROMPT="${2:-What is the root cause of this issue?}"
|
||||
# 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'
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Note>
|
||||
**After downloading or creating the script**, make it executable by running:
|
||||
```bash
|
||||
chmod +x analyze-issue.sh
|
||||
```
|
||||
</Note>
|
||||
|
||||
## Quick Usage Examples
|
||||
|
||||
### Basic Usage
|
||||
|
||||
Run this command in your terminal from the directory where you saved the script to analyze an issue with the default root cause prompt:
|
||||
|
||||
```bash
|
||||
./analyze-issue.sh https://github.com/owner/repo/issues/123
|
||||
```
|
||||
|
||||
This will:
|
||||
- Fetch issue #123 from the repository
|
||||
- Analyze the issue to identify root causes
|
||||
- Provide detailed analysis with recommendations
|
||||
|
||||
### Custom Analysis Prompt
|
||||
|
||||
Ask specific questions about the issue:
|
||||
|
||||
```bash
|
||||
./analyze-issue.sh https://github.com/owner/repo/issues/456 "What is the security impact?"
|
||||
```
|
||||
|
||||
<Note>
|
||||
The script will automatically handle everything: fetching the issue, analyzing it with Cline, and displaying the results. The analysis typically takes 30-60 seconds depending on the issue complexity.
|
||||
</Note>
|
||||
|
||||
## How It Works
|
||||
|
||||
Let's analyze each component of the script to understand how it works.
|
||||
|
||||
### Argument Validation
|
||||
|
||||
The script validates input and provides usage instructions:
|
||||
|
||||
```bash
|
||||
if [ -z "$1" ]; then
|
||||
echo "Usage: $0 <github-issue-url> [prompt]"
|
||||
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?'"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
**Key Points:**
|
||||
- Validates required GitHub issue URL
|
||||
- Shows clear usage examples
|
||||
- Supports optional custom prompt
|
||||
|
||||
### Argument Parsing
|
||||
|
||||
The script extracts and sets up the arguments:
|
||||
|
||||
```bash
|
||||
# Gather the args
|
||||
ISSUE_URL="$1"
|
||||
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
|
||||
# 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'
|
||||
```
|
||||
|
||||
<Accordion title="Pipeline Breakdown: Understanding Each Component">
|
||||
|
||||
**1. `cline --auto-approve true --json "$PROMPT: $ISSUE_URL"`**
|
||||
- `cline` is the Cline CLI binary
|
||||
- Act mode is the default for prompt runs
|
||||
- `--auto-approve true` allows tool use without interactive prompts
|
||||
- `--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
|
||||
|
||||
</Accordion>
|
||||
|
||||
## Sample Output
|
||||
|
||||
Here's an example analyzing a real Flutter issue:
|
||||
|
||||
```bash
|
||||
$ ./analyze-issue.sh https://github.com/csells/flutter_counter/issues/2
|
||||
```
|
||||
|
||||
**Output:**
|
||||
|
||||
```markdown
|
||||
**Root Cause Analysis of Issue #2: "setState isn't cutting it"**
|
||||
|
||||
After examining the GitHub issue and analyzing the Flutter counter codebase,
|
||||
I've identified the root cause of why setState() is insufficient for this
|
||||
project's needs:
|
||||
|
||||
## Current Implementation Problems
|
||||
|
||||
The current Flutter counter app uses setState() for state management, which
|
||||
has several limitations:
|
||||
|
||||
1. **Local State Only**: setState() only works within a single widget, making
|
||||
it difficult to share state across the app
|
||||
2. **Rebuild Overhead**: Every setState() call rebuilds the entire widget tree,
|
||||
causing performance issues with complex UIs
|
||||
3. **No State Persistence**: State is lost when the widget is disposed
|
||||
4. **Testing Challenges**: setState-based logic is tightly coupled to the UI,
|
||||
making unit testing difficult
|
||||
|
||||
## Why This Matters
|
||||
|
||||
As the app grows beyond a simple counter, these limitations become critical:
|
||||
- Multiple screens need to access the count
|
||||
- State needs to persist across navigation
|
||||
- Business logic should be testable independently
|
||||
- UI should only rebuild when necessary
|
||||
|
||||
## Recommended Solutions
|
||||
|
||||
The issue mentions "Provider or Bloc" - both are excellent alternatives:
|
||||
|
||||
1. **Provider**: Simple, lightweight state management using InheritedWidget
|
||||
- Easy migration path from setState
|
||||
- Good for small to medium apps
|
||||
- Official Flutter recommendation
|
||||
|
||||
2. **Bloc**: More structured approach with clear separation between events,
|
||||
states, and business logic
|
||||
- Better for complex apps
|
||||
- Excellent testability
|
||||
- Clear architectural patterns
|
||||
|
||||
3. **Riverpod**: Modern alternative to Provider with better performance and
|
||||
developer experience
|
||||
- Compile-time safety
|
||||
- Better testing support
|
||||
- More flexible than Provider
|
||||
|
||||
4. **GetX**: Full-featured solution with state management, routing, and
|
||||
dependency injection
|
||||
- Minimal boilerplate
|
||||
- Fast and lightweight
|
||||
- All-in-one solution
|
||||
|
||||
## Next Steps
|
||||
|
||||
The current codebase needs refactoring to implement proper state management
|
||||
architecture to handle more complex state scenarios effectively. Provider
|
||||
would be the easiest migration path while Bloc provides better long-term
|
||||
scalability.
|
||||
```
|
||||
|
||||
## When to Use This Pattern
|
||||
|
||||
This script pattern is ideal for various development scenarios where automated GitHub issue analysis can accelerate your workflow.
|
||||
|
||||
### Bug Investigation
|
||||
|
||||
Quickly analyze bug reports and identify root causes without manual code exploration:
|
||||
|
||||
```bash
|
||||
./analyze-issue.sh https://github.com/project/repo/issues/123 \
|
||||
"What is the root cause of this bug?"
|
||||
```
|
||||
|
||||
### Feature Request Analysis
|
||||
|
||||
Understand context and implications of feature requests:
|
||||
|
||||
```bash
|
||||
./analyze-issue.sh https://github.com/project/repo/issues/456 \
|
||||
"What are the implementation challenges?"
|
||||
```
|
||||
|
||||
### Security Audits
|
||||
|
||||
Assess security implications of reported issues:
|
||||
|
||||
```bash
|
||||
./analyze-issue.sh https://github.com/project/repo/issues/789 \
|
||||
"What are the security implications?"
|
||||
```
|
||||
|
||||
### Documentation Generation
|
||||
|
||||
Generate detailed technical documentation from issues:
|
||||
|
||||
```bash
|
||||
./analyze-issue.sh https://github.com/project/repo/issues/654 \
|
||||
"Provide detailed technical documentation for this issue"
|
||||
```
|
||||
|
||||
### Code Review Assistance
|
||||
|
||||
Get second opinions on proposed changes:
|
||||
|
||||
```bash
|
||||
./analyze-issue.sh https://github.com/project/repo/issues/987 \
|
||||
"Review the proposed solution approach"
|
||||
```
|
||||
|
||||
## Conclusion
|
||||
|
||||
This sample demonstrates how to build an autonomous GitHub issue analysis tool using Cline CLI:
|
||||
|
||||
1. **Building autonomous CLI tools** using Cline's capabilities
|
||||
2. **Parsing structured JSON output** from Cline CLI
|
||||
3. **Creating flexible automation scripts** with custom prompting
|
||||
4. **Integrating with GitHub** for issue analysis
|
||||
5. **Handling command-line arguments** effectively
|
||||
|
||||
This pattern can be adapted for many other automation scenarios, from pull request reviews to documentation generation to code quality analysis.
|
||||
|
||||
## Related Resources
|
||||
|
||||
- [CLI Installation Guide](https://docs.cline.bot/getting-started/installing-cline)
|
||||
- [CLI Reference Documentation](https://docs.cline.bot/cli/cli-reference)
|
||||
- [Headless Mode](https://docs.cline.bot/usage/cli-overview#headless-mode)
|
||||
@@ -0,0 +1,192 @@
|
||||
---
|
||||
title: "GitHub PR Review"
|
||||
description: "Automatically review Pull Requests with AI using Cline CLI in GitHub Actions."
|
||||
---
|
||||
|
||||
Automate code review for every Pull Request. Detailed analysis, security checks, and code suggestions provided by Cline running autonomously in GitHub Actions.
|
||||
|
||||
## The Workflow
|
||||
|
||||
When a PR is opened or marked ready for review, this workflow:
|
||||
1. **Checks out** the code.
|
||||
2. **Installs** Node.js and Cline CLI.
|
||||
3. **Configures** authentication (e.g., Anthropic, OpenAI).
|
||||
4. **Runs Cline** with a comprehensive system prompt to analyze the diff, context, and related issues using GitHub CLI (`gh`).
|
||||
5. **Posts** a detailed review comment with inline code suggestions.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **GitHub repository** with Actions enabled.
|
||||
- **AI Provider API Key** (e.g., Anthropic, OpenRouter) added as a repository secret (e.g., `ANTHROPIC_API_KEY`).
|
||||
- **GitHub Token** (automatically provided by Actions as `GITHUB_TOKEN`).
|
||||
|
||||
## Setup
|
||||
|
||||
### 1. Create the Workflow File
|
||||
|
||||
Create a file named `.github/workflows/cline-pr-review.yml` in your repository:
|
||||
|
||||
```yaml
|
||||
name: Cline PR Code Review
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
types: [opened, ready_for_review]
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
pr_number:
|
||||
description: "PR number to review"
|
||||
required: true
|
||||
type: string
|
||||
|
||||
concurrency:
|
||||
group: pr-review-${{ github.event.pull_request.number || inputs.pr_number }}
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
cline-pr-review:
|
||||
if: |
|
||||
(github.event_name == 'pull_request' && github.event.pull_request.draft == false) ||
|
||||
github.event_name == 'workflow_dispatch'
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 60
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
pull-requests: write
|
||||
issues: read
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
cache: "npm"
|
||||
|
||||
- name: Install Cline CLI
|
||||
run: npm install -g cline
|
||||
|
||||
- name: Configure Cline Authentication
|
||||
# Replace 'anthropic' with your provider of choice (openai, openrouter, etc.)
|
||||
# and ensure the corresponding secret is set in your repo settings.
|
||||
run: |
|
||||
cline auth --provider anthropic \
|
||||
--apikey "${{ secrets.ANTHROPIC_API_KEY }}" \
|
||||
--modelid claude-opus-4-5-20251101
|
||||
|
||||
- name: Get PR number
|
||||
id: pr
|
||||
run: |
|
||||
if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
|
||||
echo "number=${{ inputs.pr_number }}" >> $GITHUB_OUTPUT
|
||||
else
|
||||
echo "number=${{ github.event.pull_request.number }}" >> $GITHUB_OUTPUT
|
||||
fi
|
||||
|
||||
- name: Review PR with Cline
|
||||
env:
|
||||
PR_NUMBER: ${{ steps.pr.outputs.number }}
|
||||
GITHUB_REPO: ${{ github.repository }}
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
# Restrict Cline to only safe, read-only GitHub CLI commands
|
||||
CLINE_COMMAND_PERMISSIONS: |
|
||||
{
|
||||
"allow": [
|
||||
"gh pr diff *",
|
||||
"gh pr view *",
|
||||
"gh pr checks *",
|
||||
"gh pr list *",
|
||||
"gh issue list *",
|
||||
"gh issue view *",
|
||||
"git log *",
|
||||
"gh pr comment ${{ steps.pr.outputs.number }} *",
|
||||
"gh api repos/${{ github.repository }}/pulls/${{ steps.pr.outputs.number }}/comments *",
|
||||
"gh api repos/${{ github.repository }}/pulls/${{ steps.pr.outputs.number }}/reviews *"
|
||||
]
|
||||
}
|
||||
run: |
|
||||
cline --auto-approve true 'You are a GitHub PR reviewer for this repository. Your goal is to give the PR author helpful feedback and give maintainers the context they need to review efficiently.
|
||||
|
||||
PR: #'"${PR_NUMBER}"'
|
||||
|
||||
## Gather context
|
||||
Use `gh` commands to fetch the PR diff, details, and checks.
|
||||
|
||||
```bash
|
||||
# Get full PR details
|
||||
gh pr view '"${PR_NUMBER}"' --json number,title,body,author,createdAt,updatedAt,isDraft,labels,commits,files,additions,deletions,changedFiles,baseRefName,headRefName,mergeable,reviewDecision
|
||||
|
||||
# Get the diff
|
||||
gh pr diff '"${PR_NUMBER}"'
|
||||
|
||||
# Check CI status
|
||||
gh pr checks '"${PR_NUMBER}"'
|
||||
```
|
||||
|
||||
## Deep code review
|
||||
Analyze the code changes. Look for:
|
||||
- Logic errors and edge cases
|
||||
- Security vulnerabilities
|
||||
- Performance issues
|
||||
- adherence to patterns in the codebase
|
||||
|
||||
## Submit Review
|
||||
Post a single comprehensive comment summarizing your review.
|
||||
|
||||
If you have specific code suggestions, use the GitHub API to post inline comments:
|
||||
|
||||
```bash
|
||||
gh api repos/'"${GITHUB_REPO}"'/pulls/'"${PR_NUMBER}"'/reviews \
|
||||
-X POST \
|
||||
-f event="COMMENT" \
|
||||
-f body="" \
|
||||
-F comments='[{"path": "src/file.ts", "line": 10, "body": "Suggestion: ..."}]'
|
||||
```
|
||||
|
||||
Start your main comment with "Reviewed by Cline".'
|
||||
```
|
||||
|
||||
### 2. Configure Secrets
|
||||
|
||||
1. Go to your repository settings -> **Secrets and variables** -> **Actions**.
|
||||
2. Add a **New repository secret**.
|
||||
3. Name: `ANTHROPIC_API_KEY` (or match the key used in your workflow).
|
||||
4. Value: Your actual API key.
|
||||
|
||||
## Key Components Explained
|
||||
|
||||
### Permissions
|
||||
```yaml
|
||||
permissions:
|
||||
contents: read
|
||||
pull-requests: write
|
||||
issues: read
|
||||
```
|
||||
We grant `pull-requests: write` so Cline can post comments and inline reviews. `contents: read` ensures it can analyze the code but **cannot push changes directly**, providing a security boundary.
|
||||
|
||||
### Authentication
|
||||
```bash
|
||||
cline auth --provider anthropic --apikey "..."
|
||||
```
|
||||
The `auth` command configures Cline in the CI environment without interactive prompts. You can switch providers (e.g., `openai`, `openrouter`) by changing the flags.
|
||||
|
||||
### Autonomous Mode (`--auto-approve true`)
|
||||
```bash
|
||||
cline --auto-approve true '...'
|
||||
```
|
||||
The `--auto-approve true` flag tells Cline to run autonomously, executing approved tools without waiting for interactive confirmation. Prompt runs start in Act mode by default, so CI/CD workflows can perform the requested work immediately.
|
||||
|
||||
### Command Permissions
|
||||
We explicitly restrict what commands Cline can run using `CLINE_COMMAND_PERMISSIONS`. This ensures Cline can only use `gh` and `git` commands relevant to reviewing, preventing any accidental or malicious system modifications.
|
||||
|
||||
## Customizing the Reviewer
|
||||
|
||||
The "System Prompt" passed to Cline in the final step is fully customizable. You can modify it to:
|
||||
- Enforce specific style guides.
|
||||
- Focus on security vs. performance.
|
||||
- Ask for specific types of feedback (e.g., "Roast my code" vs. "Be gentle").
|
||||
@@ -0,0 +1,222 @@
|
||||
---
|
||||
title: "Model Orchestration"
|
||||
description: "Use multiple AI models strategically: optimize costs, reduce bias, and leverage model-specific strengths in your workflows"
|
||||
---
|
||||
|
||||
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**
|
||||
|
||||
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.
|
||||
|
||||
**Bias Reduction**
|
||||
|
||||
Different models catch different issues, so cross-validating solutions with multiple AI perspectives helps reduce blind spots that come from relying on a single model. In code reviews especially, combining viewpoints surfaces problems that any one model might miss.
|
||||
|
||||
**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.
|
||||
|
||||
## 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 --auto-approve true --config ~/.cline-haiku \
|
||||
"summarize this issue in 2-3 sentences")
|
||||
|
||||
# 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")
|
||||
|
||||
# Phase 3: Execute with mid-tier model
|
||||
echo "$PLAN" | cline --auto-approve true --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 --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 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 \
|
||||
"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 --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" &
|
||||
|
||||
# Wait for all to complete
|
||||
wait
|
||||
|
||||
# Synthesize
|
||||
cat *-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.
|
||||
</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 --auto-approve true "refactor this codebase"
|
||||
|
||||
# With thinking: Slower but more thorough
|
||||
cline --auto-approve true --thinking high \
|
||||
"refactor this codebase - consider: performance, maintainability, backward compatibility"
|
||||
```
|
||||
|
||||
The `--thinking <level>` flag sets reasoning effort. Use `--thinking high` or `--thinking xhigh` when you want the model to spend more effort on complex tradeoffs. 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 --auto-approve true --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 --auto-approve true --thinking high --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 --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
|
||||
|
||||
# High-priority: Issues all 3 models found
|
||||
cat *-sec.md | cline --auto-approve true "find security issues all 3 reviews mentioned"
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
<Columns cols={2}>
|
||||
<Card title="CLI Reference" icon="terminal" href="/cli/cli-reference">
|
||||
Complete documentation for --config and --thinking flags
|
||||
</Card>
|
||||
|
||||
<Card title="Headless Mode" icon="robot" href="/usage/cli-overview#headless-mode">
|
||||
Run Cline autonomously in scripts, CI/CD pipelines, and automated workflows.
|
||||
</Card>
|
||||
|
||||
<Card title="Cline Provider" icon="brain" href="/getting-started/cline-provider">
|
||||
Fastest built-in model access setup and account workflow
|
||||
</Card>
|
||||
|
||||
<Card title="CI/CD Integration" icon="github" href="/cli/samples/github-integration">
|
||||
Automate GitHub workflows with Cline CLI
|
||||
</Card>
|
||||
</Columns>
|
||||
@@ -0,0 +1,213 @@
|
||||
---
|
||||
title: "Supply-Chain Scan Alerts"
|
||||
description: "Schedule the Cline CLI to scan your machine for compromised packages with Bumblebee and text you on Telegram when it finds one."
|
||||
---
|
||||
|
||||
npm worms like Shai-Hulud spread through install scripts: the moment you run `npm install`, a `preinstall` hook executes and steals your npm, GitHub, AWS, and SSH credentials. New campaigns are reported almost every week.
|
||||
|
||||
This guide wires three pieces together so your machine checks itself automatically and pings your phone only when it matters:
|
||||
|
||||
- [Bumblebee](https://github.com/perplexityai/bumblebee), Perplexity's open-source, read-only supply-chain scanner. It maintains catalogs of recent campaigns and checks whether any compromised package or version is present on disk.
|
||||
- The Cline CLI scheduler, which runs an agent on a cron schedule.
|
||||
- The Cline CLI Telegram connector, which delivers the result to a chat.
|
||||
|
||||
The end result: every morning, a Cline agent pulls the latest threat intelligence, runs a read-only scan, and texts you a green check if you are clean or a red alert with details if you are exposed.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
cron["cline schedule (daily)"] --> agent["Cline agent"]
|
||||
agent --> pull["git pull (latest catalogs)"]
|
||||
agent --> scan["bumblebee scan (read-only)"]
|
||||
scan --> q{"any findings?"}
|
||||
q -- "no" --> clean["✅ Clean"]
|
||||
q -- "yes" --> alert["🚨 Compromise detected"]
|
||||
clean --> tg["Telegram on your phone"]
|
||||
alert --> tg
|
||||
```
|
||||
|
||||
## How Bumblebee works
|
||||
|
||||
Bumblebee answers one narrow question fast: when an advisory names a package and version, is it present on this machine right now?
|
||||
|
||||
The important design choice is that it is read-only. A scanner that runs `npm`, `pnpm`, or `pip` to enumerate your dependencies would trigger the very install-script payload it is looking for. Bumblebee never does that. It only reads metadata files directly:
|
||||
|
||||
| Surface | What it reads |
|
||||
|---|---|
|
||||
| npm / pnpm / yarn / bun | lockfiles and installed `package.json` metadata |
|
||||
| PyPI | `*.dist-info/METADATA`, `*.egg-info/PKG-INFO` |
|
||||
| Go modules | `go.sum`, `go.mod` |
|
||||
| RubyGems | `Gemfile.lock`, installed gemspecs |
|
||||
| Composer | `composer.lock`, `vendor/composer/installed.json` |
|
||||
| MCP servers | `mcp.json`, `claude_desktop_config.json`, and similar configs |
|
||||
| Editor extensions | VS Code-family extension manifests |
|
||||
| Browser extensions | Chromium-family and Firefox extension manifests |
|
||||
|
||||
It never runs package managers, never executes install scripts or lifecycle hooks, and never reads your application source. It ships no bundled threat intelligence either: you point it at an exposure catalog, and it reports exact `(ecosystem, name, version)` matches.
|
||||
|
||||
The catalogs live in the repo under `threat_intel/`, maintained by Perplexity and updated via pull requests as new campaigns are reported. That is why this automation simply pulls the latest before each scan: a `git pull` is all it takes to stay current.
|
||||
|
||||
Read the announcement: [Perplexity is open-sourcing Bumblebee](https://www.perplexity.ai/hub/blog/perplexity-is-open-sourcing-bumblebee).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js 22 or newer (for the Cline CLI).
|
||||
- Go 1.22 or newer (to build Bumblebee).
|
||||
- A Telegram account.
|
||||
- An AI provider key, or a Cline account.
|
||||
|
||||
## 1. Install the Cline CLI
|
||||
|
||||
```bash
|
||||
npm install -g cline
|
||||
cline # run once to configure inference provider and model
|
||||
```
|
||||
|
||||
## 2. Clone and build Bumblebee
|
||||
|
||||
Clone the repository somewhere stable. The clone is both the scanner and the catalog source, so the scheduled job will run from inside it.
|
||||
|
||||
```bash
|
||||
mkdir -p ~/tools
|
||||
git clone https://github.com/perplexityai/bumblebee.git ~/tools/bumblebee
|
||||
cd ~/tools/bumblebee
|
||||
go build -o bumblebee ./cmd/bumblebee
|
||||
```
|
||||
|
||||
Confirm it works with the built-in self test, which runs embedded fixtures and makes no network calls:
|
||||
|
||||
```bash
|
||||
./bumblebee selftest
|
||||
# selftest OK (2 findings in 1ms)
|
||||
```
|
||||
|
||||
## 3. Run a scan manually
|
||||
|
||||
Point `--exposure-catalog` at the whole `threat_intel/` directory to use every maintained catalog at once. The `--findings-only` flag suppresses the full inventory so you only get matches.
|
||||
|
||||
```bash
|
||||
cd ~/tools/bumblebee
|
||||
./bumblebee scan --profile deep --root "$HOME" \
|
||||
--exposure-catalog ./threat_intel/ \
|
||||
--findings-only
|
||||
```
|
||||
|
||||
Output is NDJSON, one JSON object per line. A match looks like this:
|
||||
|
||||
```json
|
||||
{ "record_type": "finding", "severity": "critical", "ecosystem": "npm",
|
||||
"package_name": "example-pkg", "version": "1.2.3",
|
||||
"source_file": "/Users/you/code/app/pnpm-lock.yaml",
|
||||
"evidence": "exact name+version match (version=1.2.3)" }
|
||||
```
|
||||
|
||||
If you are clean, you get no `finding` records. Exit code is `0` on a successful run, `1` if the scan hit errors, `2` for bad arguments.
|
||||
|
||||
<Note>
|
||||
Scan profiles control where Bumblebee looks. `baseline` checks standard global tool, editor, and browser locations. `project` scans your development directories (pass `--root ~/code`). `deep` walks whatever roots you give it, typically your whole home directory. Use `deep` for the most thorough "am I exposed anywhere" check, or `project` for a faster daily scan of your repos.
|
||||
</Note>
|
||||
|
||||
## 4. Create a Telegram bot and start the connector
|
||||
|
||||
<Steps>
|
||||
<Step title="Create a bot">
|
||||
Open Telegram, start a chat with [@BotFather](https://t.me/BotFather), send `/newbot`, and follow the prompts. Copy the bot token it gives you (it looks like `7123456789:AAH...`). Treat it like a password.
|
||||
</Step>
|
||||
|
||||
<Step title="Start the connector">
|
||||
Run the connector and point its working directory at your Bumblebee clone, so the scheduled agent runs there:
|
||||
|
||||
```bash
|
||||
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.
|
||||
</Step>
|
||||
|
||||
<Step title="Open the chat">
|
||||
In Telegram, search for your bot's username and send it any message (for example `/whereami`). This creates the thread binding that delivery needs.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Warning>
|
||||
By default, anyone who finds your bot can message it and it will run tasks on your machine. Lock it down before leaving the connector running. The `cline connect` wizard can guide you through Telegram user ID setup, or you can message [@userinfobot](https://t.me/userinfobot) and restart the connector with your allowed user ID:
|
||||
|
||||
```bash
|
||||
cline connect telegram -k "<BOT-TOKEN>" --cwd ~/tools/bumblebee \
|
||||
--allowed-user-id 12345
|
||||
```
|
||||
|
||||
Replace `12345` with your Telegram user ID.
|
||||
</Warning>
|
||||
|
||||
## 5. Schedule the scan
|
||||
|
||||
There are two ways to create the scheduled scan. Both run the same agent and deliver the result to Telegram, so pick whichever you prefer.
|
||||
|
||||
### Option A: From the Telegram chat
|
||||
|
||||
Creating the schedule from the chat automatically targets that thread for delivery, so results come straight back to you. Send this to your bot as a single message:
|
||||
|
||||
```text
|
||||
/schedule create "supply-chain-watch" --cron "0 8 * * *" --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.'"
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```bash
|
||||
cline schedule create "supply-chain-watch" \
|
||||
--cron "0 8 * * *" \
|
||||
--workspace ~/tools/bumblebee \
|
||||
--delivery-adapter telegram \
|
||||
--delivery-bot <bot-username> \
|
||||
--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.'"
|
||||
```
|
||||
|
||||
Either way, this schedules a daily scan at 8am.
|
||||
|
||||
## Why the green check matters
|
||||
|
||||
Scheduled delivery always sends the run's final reply, so the prompt is written to make that reply meaningful either way:
|
||||
|
||||
- Clean run: one line, `✅ Clean: no compromised packages found.` You get a daily heartbeat confirming the scan actually ran.
|
||||
- Exposure: `🚨 COMPROMISE DETECTED` followed by the package, version, and the file where it was found, so you can act immediately (rotate credentials, remove the package, pin a safe version).
|
||||
|
||||
## Test it
|
||||
|
||||
Trigger the scan now instead of waiting for 8am.
|
||||
|
||||
First find your schedule id. The create step returns it (the Telegram bot's reply shows `id=...`), or list your schedules at any time:
|
||||
|
||||
```bash
|
||||
cline schedule list
|
||||
```
|
||||
|
||||
Then trigger it with that id. From the terminal:
|
||||
|
||||
```bash
|
||||
cline schedule trigger <schedule-id>
|
||||
```
|
||||
|
||||
Or from Telegram: `/schedule trigger <schedule-id>`. Within a few seconds you should get the result in your chat.
|
||||
|
||||
To see a real alert, add a package and version that matches a catalog entry to a throwaway project's lockfile and run the scan against it. Bumblebee reports the match, and the agent texts you the red alert.
|
||||
|
||||
## 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 hub runs the schedule and starts automatically when you create one. If it is not running, start it with `cline hub start`.
|
||||
- Manage schedules anytime with `cline schedule list`, `cline schedule pause <id>`, `cline schedule resume <id>`, and `cline schedule delete <id>`.
|
||||
|
||||
## Customize
|
||||
|
||||
- Cadence: change the cron expression. `0 */6 * * *` scans every six hours; `0 8 * * MON-FRI` runs on weekdays only.
|
||||
- Scope: swap `--profile deep --root $HOME` for `--profile project --root ~/code` for a faster scan of just your repos, or `--profile baseline` for global tools, editors, and browser extensions.
|
||||
- Channels: the same delivery pattern works for Slack, Discord, WhatsApp, and Google Chat. See [Connectors](/cli/connectors).
|
||||
- Fleet use: Bumblebee can `POST` NDJSON to an ingest endpoint with `--output http --http-url <url>` if you want to centralize findings across many machines.
|
||||
|
||||
## Credits
|
||||
|
||||
Bumblebee is built and open-sourced by Perplexity. See the [announcement](https://www.perplexity.ai/hub/blog/perplexity-is-open-sourcing-bumblebee) and the [repository](https://github.com/perplexityai/bumblebee).
|
||||
@@ -0,0 +1,110 @@
|
||||
---
|
||||
title: "Scheduling"
|
||||
sidebarTitle: "Scheduling"
|
||||
description: "Run agents on cron schedules for recurring automations like daily summaries and code reviews."
|
||||
---
|
||||
<Warning>
|
||||
This feature currently only applies to Cline SDK, CLI, and Kanban. This feature is not applicable on VSCode and JetBrains Extension for now.
|
||||
</Warning>
|
||||
|
||||
The CLI supports running agents on cron schedules through the hub. Scheduled agents persist across process restarts and run independently of any terminal session.
|
||||
|
||||
## Schedule Wizard
|
||||
|
||||
Run `cline schedule` to open an interactive menu for creating and managing schedules, browsing execution history, and viewing performance statistics.
|
||||
|
||||
```bash
|
||||
cline schedule
|
||||
```
|
||||
|
||||
The wizard provides:
|
||||
|
||||
| Action | Description |
|
||||
|--------|-------------|
|
||||
| Create new schedule | Set up a recurring task with cron timing and prompt |
|
||||
| List schedules | View all schedules with status and next run time |
|
||||
| Upcoming runs | Preview the next 10 scheduled executions |
|
||||
| Active executions | Show currently running tasks |
|
||||
| Trigger now | Immediately run a selected schedule |
|
||||
| Pause / Resume | Suspend or restart a schedule |
|
||||
| Execution history | View past runs with status, duration, tokens, and cost |
|
||||
| Statistics | Success rate, average duration, last failure |
|
||||
| Delete | Remove a schedule |
|
||||
|
||||
## Creating Schedules with Flags
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
## Managing Schedules
|
||||
|
||||
```bash
|
||||
cline schedule list
|
||||
cline schedule trigger <schedule-id>
|
||||
cline schedule pause <schedule-id>
|
||||
cline schedule resume <schedule-id>
|
||||
cline schedule delete <schedule-id>
|
||||
cline schedule executions <schedule-id>
|
||||
```
|
||||
|
||||
## Cron Expression Reference
|
||||
|
||||
| Expression | Schedule |
|
||||
|-----------|----------|
|
||||
| `*/5 * * * *` | Every 5 minutes |
|
||||
| `*/15 * * * *` | Every 15 minutes |
|
||||
| `0 * * * *` | Every hour |
|
||||
| `0 */6 * * *` | Every 6 hours |
|
||||
| `0 0 * * *` | Daily at midnight |
|
||||
| `0 9 * * *` | Daily at 9am |
|
||||
| `0 9 * * 1-5` | Every weekday at 9am |
|
||||
| `0 9 * * 1` | Every Monday at 9am |
|
||||
| `0 0 1 * *` | First of every month |
|
||||
|
||||
## Examples
|
||||
|
||||
### Daily Standup Summary
|
||||
|
||||
```bash
|
||||
cline schedule create "Standup prep" \
|
||||
--cron "0 8 * * MON-FRI" \
|
||||
--prompt "Summarize: (1) PRs merged yesterday, (2) PRs currently in review, (3) open issues assigned to team members." \
|
||||
--workspace /path/to/repo
|
||||
```
|
||||
|
||||
### Weekly Dependency Check
|
||||
|
||||
```bash
|
||||
cline schedule create "Dependency check" \
|
||||
--cron "0 10 * * MON" \
|
||||
--prompt "Check for outdated npm dependencies. For any with security vulnerabilities, create a branch with the update and open a PR." \
|
||||
--workspace /path/to/project
|
||||
```
|
||||
|
||||
### Codebase Health Report
|
||||
|
||||
```bash
|
||||
cline schedule create "Code health" \
|
||||
--cron "0 6 * * MON" \
|
||||
--prompt "Analyze the codebase for: (1) files with no test coverage, (2) TODO/FIXME comments older than 30 days, (3) functions longer than 100 lines." \
|
||||
--workspace /path/to/project
|
||||
```
|
||||
|
||||
## Routing Results
|
||||
|
||||
Combine schedules with [connectors](/cli/connectors) to send results to messaging platforms:
|
||||
|
||||
```bash
|
||||
cline connect telegram -k $BOT_TOKEN
|
||||
|
||||
cline schedule create "Morning briefing" \
|
||||
--cron "0 8 * * *" \
|
||||
--prompt "Summarize overnight activity in the repo"
|
||||
```
|
||||
|
||||
Scheduling requires the hub. It starts automatically when you create a schedule.
|
||||
Reference in New Issue
Block a user