![Cline AI Setup: 12 Steps, 60 Min [2026]](https://shattered.io/wp-content/uploads/2026/10/cline-ai-setup-vscode-cli-12-steps-2026-gen.webp)
Cline now ships as a VS Code extension (v4.1.26), a terminal CLI (v3.0.74), a Desktop app (v0.0.49) and an SDK, each on its own release track, and the model behind them changes almost weekly. The agent itself costs nothing, and the optional ClinePass subscription runs $9.99 a month for open-weight coding models. That mix of a free client and a cheap flat-rate model plan explains why Cline keeps turning up in searches for an open source ai coding assistant.
Developers are already comfortable handing work to agents. Stack Overflow’s 2025 developer survey reported, in its own words, that “31% of developers currently use AI agents, while 17% plan to use them” (source). Among the developers using agents at work, 69% agreed the tools had raised their productivity, per the same survey. The open question is no longer whether to try one. It is how to set one up so it stays cheap, predictable and under your control.
If you have already tried Aider with a local Ollama model or another terminal agent, Cline AI will feel familiar and different at once. It asks permission for every file edit and every shell command by default, keeps checkpoints you can roll back, and runs in your editor, your terminal or a script. The walkthrough below installs it in both places, wires up a model, and finishes with a working demo repo called logscrub. Cline adds IPv6 redaction to that repo, and a review script gates the push.
Don't miss new tech stories on Google
Add Shattered once in the Google app and our stories show up in your news suggestions.
Cline AI in October 2026: Four Products, One Agent Core #
Cline began as a VS Code extension. By late October 2026 the official docs list a Desktop app, a CLI, the VS Code extension, a JetBrains plugin, an SDK and a Kanban board, all running on one agent core. Version numbers differ per surface, so write them down before you start. The extension reached v4.1.26 on October 26, the CLI reached v3.0.74 the same day, and the Cline site lists the Desktop app at v0.0.49. A changelog tracker shows the extension at the same version.
Those October 26 releases refreshed the model catalog. Providers CommandCode, Reflection, Liquid Inference and Munito AI arrived, while CrofAI, iFlow and Llama left. The free-model list gained Reflection Beam, Nemotron 3.5 Lightning and Laguna S 2.1 and dropped Mimo V2.6 Flash and Muse Spark 1.3 Contributor. If your saved config named a removed entry, expect to pick a new one on the next launch.
Defaults move too. The release notes say the Cline provider’s default model returned to Claude Sonnet 5.5. Anthropic describes that model as more than 30% faster than Sonnet 5 and up to 30% cheaper for most work, according to its Claude release notes. One release tracker reports that Gemini 4 Argon briefly took the top recommended slot on October 16 before Sonnet 5.5 came back. Treat that as a warning label. Any setup that trusts the default model can change behavior between two npm updates, which is why the steps below pin a model by name.
Rival tools move on the same clock. Claude Code, Codex CLI and OpenCode all shipped updates inside four days in mid-October, so version drift is the norm across the whole category and not a Cline quirk.
One more October addition matters for planning. Since v4.1.25 on October 16, Cline Cloud sessions have been rolling out gradually. A task can run in a hosted sandbox against a chosen GitHub repository and branch, and it keeps going after you close the editor. This walkthrough stays local-first, so cloud sessions only show up in the advanced tips near the end.
Prerequisites and Versions to Check First #
Gather the pieces for your Cline AI setup before you touch an installer. Most failures in the first hour trace back to a missing runtime or a stale global npm package, not to Cline itself.
| Component | Version or requirement | Needed for |
|---|---|---|
| Cline VS Code extension | 4.1.26 | Steps 2, 3, 7, 8 |
| Cline CLI | 3.0.74 | Steps 4, 11, 12 |
| Cline Desktop (optional) | 0.0.49 | Advanced tips |
| Visual Studio Code | Current stable build | Steps 2 to 8 |
| Node.js and npm | Current LTS release | Installing the CLI |
| Python | 3.10 or newer | Demo project |
| Git | Any recent release | Branches, checkpoints, hooks |
| jq | Any recent release | Step 12 JSON parsing |
| Ollama (optional) | Current release | Step 9 |
| Model access | Cline sign-in, ClinePass, or your own key | Step 3 |
Budget about 60 minutes end to end. The split below assumes a fast connection and no corporate proxy.
- Steps 1 to 3 (choose a path, install the extension, connect a provider): 12 minutes.
- Step 4 (CLI install and sign-in): 6 minutes.
- Steps 5 and 6 (demo repo and project rules): 10 minutes.
- Steps 7 and 8 (plan, act, review): 14 minutes.
- Step 9 (local fallback with Ollama): 8 minutes, plus model download time.
- Steps 10 to 12 (MCP, guardrails, headless review): 10 minutes.
The demo project needs no paid account for the first pass, because Cline’s built-in free models should handle the small feature in Step 7. A flat-rate or pay-as-you-go plan only matters once you point the agent at a larger codebase.
Step 1: Pick an Access Path Before You Install Anything #
Cline separates the agent from the model, and the docs describe three common ways to connect them. Choose one now, because it decides which screen you see in Step 3 and what the work costs later. You can switch at any time, and you can keep several configured side by side.
| Path | How you pay | Setup effort | Best for |
|---|---|---|---|
| Cline (usage-billing) | Prepaid credits, with free model options | One sign-in, no key to manage | Fastest first run |
| ClinePass | $9.99 per month flat, 2-5x the usage of standard API rates on selected open coding models | Subscribe, then select the ClinePass provider | Heavy agent use on open-weight models |
| Bring your own key (cloud) | Whatever your provider bills | Paste a key from OpenRouter, Anthropic, OpenAI, Google Gemini, AWS Bedrock or DeepSeek | Teams with existing provider contracts |
| Bring your own weights (local) | Your hardware and power | Run Ollama or LM Studio, no key | Code that cannot leave the machine |
ClinePass deserves a closer look because it changes the math for long sessions. The docs describe it as a separate provider from the usage-billing option, with usage tracked against rolling 5-hour, weekly and monthly limits. Its curated lineup covers open-weight models from Z.ai, Moonshot AI, DeepSeek, MiniMax, MiMo and Qwen families. As of October 26 the CLI release notes say the ClinePass default became Kimi K3.1 Pro, with MiniMax M3.1 Flash and DeepSeek V4.1 Flash 1017 added. The lineup rotates as capacity changes, so read the live model list in the ClinePass docs before you promise a specific model to your team.
Pay-as-you-go pricing needs a rough budget. Anthropic lists Claude Sonnet 5.5 at $2 per million input tokens and $10 per million output tokens. Take a hypothetical task that reads 200,000 input tokens across file reads and tool results and writes 10,000 output tokens. That costs $0.40 for input plus $0.10 for output, or $0.50 in total. Ten such tasks in an afternoon cost about $5. Your real numbers will differ because agents re-read context on every turn, but the arithmetic shows why a flat plan appeals to people who run agents all day and why a small pay-as-you-go balance suits occasional use.
For this walkthrough, pick the sign-in path (usage-billing with a free model) if you want zero setup, or paste a provider key if you already have one. Keep the local path for Step 9, where it serves as an offline fallback instead of your daily driver. If a local-first agent is your main goal, OpenCode paired with Ollama takes that route from the start.
Steps 2 and 3: Install the Extension and Connect a Provider #
Step 2. Install the extension. Open VS Code, switch to the Extensions view, search for Cline, and install the extension published by the Cline team. Cline’s site also lists installers for Windsurf, JetBrains IDEs and Cursor, and the docs add Zed and Neovim through the Agent Client Protocol mode. After the install, open the Extensions view again and confirm the version reads 4.1.26 or newer. If it reads something older, your editor has not refreshed its marketplace cache yet. Reload the window and check again.
VS Code itself changed this month. Microsoft’s October 15 post on modernizing the VS Code UI introduces the Dark 2026 and Light 2026 themes and gives the editor and its Agents window a shared design system. Cline’s side panel picks up whichever theme you run, so a fresh install can look different from older screenshots in tutorials. The controls described below sit in the same places.
Step 3. Connect a provider. Click the gear icon in the Cline panel and follow the docs’ four-part flow.
- Open Cline settings and find the API Provider dropdown.
- Choose Cline (usage-billing), ClinePass, a bring-your-own-key provider, or a local runtime.
- Authenticate. The two Cline providers use an OAuth sign-in in your browser. Cloud providers need an API key pasted into the key field. Local runtimes need no key, only a running server.
- Open the Model dropdown and pick a model by name.
Pick the model explicitly even when a recommended one is highlighted. The recommended slot is the part that moved twice in October. A pinned model makes your results repeatable, and it makes cost estimates meaningful.
Send a throwaway prompt to prove the connection, such as asking Cline to list the files in an empty folder. A reply means the provider works. An “Unauthorized: Please sign in” message means your session expired, and the fix is to click Sign In again. If the browser never opens, copy the sign-in URL from the Cline output panel and paste it into the browser yourself. Both cases appear in the troubleshooting table later.
Step 4: Install the Cline CLI and Authenticate #
The Cline CLI shares the agent core with the extension but has its own release numbers, its own config and a headless mode that the extension lacks. Install it globally with npm.
npm i -g cline
cline --help
cline auth
The cline auth command runs the same authentication flow as the IDE and lets you choose a provider and model. The docs list cline a as a shorthand. For ClinePass subscribers, the CLI route is slightly different: open the settings view with /settings inside an interactive session and select ClinePass as the provider.
Three more commands earn a place in your muscle memory before you do real work.
cline configprints the current configuration, which settles most “why did it pick that model” arguments.cline doctordiagnoses and repairs configuration problems.cline historyshows and manages past tasks, which helps when you want to recover a half-finished session.
Run cline --version after the install if your build supports it, and compare the result with the table in the prerequisites section. Before v3.0.72 the CLI accepted CLINE_PLUGIN_MODE=in_process. Version 3.0.72 and later run plugins in a worker by default and also support a sandbox mode. If you use plugins, this single change breaks old setups, so check before you blame the plugin author.
Start an interactive session with cline and ask a harmless question to confirm the loop works. The docs show the three entry points you will use most: cline for an interactive session, cline "refactor this module to use async/await" for a one-shot task, and cline --json "list TODO comments" for structured output in scripts. With the Cline CLI running, keep an eye on the first response time, because a hang here usually means the provider selection did not stick.
A permission error during npm i -g cline is the most common install snag on Linux and macOS. Resist the urge to rerun it with sudo. A root-owned global folder causes update failures later and lets install scripts run with more rights than they need. Point npm at a user-level prefix instead, add that folder’s bin directory to your PATH, and rerun the install. On Windows, open a fresh terminal after the install so the new PATH entry loads, and check that your editor’s integrated terminal inherits it. Once cline --help prints, compare cline config with the provider the IDE shows. The two surfaces keep separate sessions, so signing in on one does not always sign you in on the other.
Step 5: Create the Demo Project #
Any open source ai coding assistant needs a real repo to prove itself on. The demo is logscrub, a small Python module that strips secrets and personal data from log lines. It is the kind of utility every team writes once, and it gives Cline a clean, testable feature to add. Browse more tools like this in our coding and developer tools coverage if you want other projects to practice on.
mkdir cline-demo && cd cline-demo
git init -b main
python3 -m venv .venv && . .venv/bin/activate
pip install pytest
mkdir -p src/logscrub tests scripts
Create pyproject.toml first. It registers the console script and tells pytest where the source lives, so imports work without installing the package.
[project]
name = "logscrub"
version = "0.1.0"
requires-python = ">=3.10"
[project.scripts]
logscrub = "logscrub.cli:main"
[tool.pytest.ini_options]
pythonpath = ["src"]
testpaths = ["tests"]
Next, the module itself. It holds an ordered list of named patterns and replaces every match with a marker such as [REDACTED:email]. Order matters, because the email pattern must run before anything that could chew up part of an address.
"""Redact secrets and personal data from log lines."""
import re
PATTERNS = [
("bearer", re.compile(r"(?i)\bBearer\s+[A-Za-z0-9._~+/=-]{8,}")),
("api_key", re.compile(r"(?i)\b(api[_-]?key|token|secret)\s*[=:]\s*[^\s,;]{6,}")),
("aws_key", re.compile(r"\bAKIA[0-9A-Z]{16}\b")),
("email", re.compile(r"\b[\w.+-]+@[\w-]+\.[\w.-]+\b")),
("ipv4", re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}\b")),
]
def scrub_line(line: str) -> str:
"""Replace every match with a [REDACTED:<kind>] marker."""
for kind, pattern in PATTERNS:
line = pattern.sub(f"[REDACTED:{kind}]", line)
return line
def scrub_text(text: str) -> str:
return "\n".join(scrub_line(line) for line in text.splitlines())
Add src/logscrub/__init__.py with two lines that export scrub_line and scrub_text, then a small cli.py that reads a file or standard input and prints the scrubbed lines. The test file covers six cases: bearer tokens, key assignments, AWS key IDs, email plus IPv4, an untouched clean line, and multi-line text. Run the suite and commit.
pytest -q
git add -A && git commit -m "init logscrub"
git checkout -b feature/ipv6
...... [100%]
6 passed in 0.02s
Try the finished command line tool on a sample line. This is the exact output from the demo repo, and it shows the gap Cline will close in Step 7. An IPv6 address would sail straight through.
printf 'user [email protected] hit 198.51.100.7 with token=abcd1234efgh\nok line\n' | logscrub
user [REDACTED:email] hit [REDACTED:ipv4] with [REDACTED:api_key]
ok line
Step 6: Write Project Rules Cline Will Actually Follow #
Rules are the cheapest quality upgrade in the whole setup. Cline reads a .clinerules file that ships with the repo, so every contributor and every headless run gets the same instructions. The Cline site pitches the file as a way to teach the agent your coding standards, architecture and deployment conventions. Keep yours short and verifiable. Vague advice such as “write clean code” costs tokens on every turn and changes nothing.
## Stack
- Python 3.10+, standard library only at runtime
- Tests with pytest, run with `pytest -q` from the repo root
## Workflow
- Work only on a feature branch, never on main
- Add or update a test before changing a pattern
- Run `pytest -q` after every change and report the result
- Keep each commit to one pattern or one fix
## Safety
- Never print, log or commit real credentials, even in tests
- Use documentation address ranges in tests: 192.0.2.0/24,
198.51.100.0/24, 203.0.113.0/24 and the 2001:db8::/32 IPv6 prefix
- Do not add dependencies without asking first
## Style
- Type hints on public functions
- One-line docstrings, no multi-paragraph comments
Three habits keep a rules file useful. First, write commands the agent can run, because “run pytest -q” produces a check while “ensure quality” produces prose. Second, list what is forbidden, since agents rarely volunteer restraint. Third, review the file whenever the agent surprises you. A surprise usually means a missing rule.
One caution from the docs navigation: the older .clineignore file is marked as deprecated soon. If you rely on it to hide secrets from the agent, plan a move to the newer rules and hooks approach, and treat any ignore file as a convenience rather than a security boundary.
Steps 7 and 8: Plan the Change, Act, Then Review Every Diff #
Step 7. Start in Plan mode. Cline has a Plan and an Act mode. Plan mode lets the agent read the project and propose an approach without editing anything. Act mode executes. In the extension you toggle between them in the chat panel. In the CLI, the -p flag starts in Plan mode, so cline -p "..." gives you the same plan-first behavior from a terminal.
Model quality matters here, and our roundup of the best open source LLM options for October 2026 compares current open-weight picks on price and capability. Give the agent a precise, bounded task. Precision matters more than length. This prompt names the file, the failure case and the acceptance test.
Add IPv6 redaction to logscrub. Detect full and compressed IPv6 addresses
and replace them with [REDACTED:ipv6]. A clock time such as 12:30:45 must not
match. Add tests first, then change src/logscrub/scrub.py, then run pytest -q.
Read the plan before you approve it. A good plan names scrub.py and tests/test_scrub.py, lists the test cases, and flags the timestamp risk. A weak plan promises to “improve the regex” without naming a file. If you see the second kind, reply with the specific gap instead of accepting and hoping. Switch to Act mode only when the plan matches what you would do by hand.
Context is the other lever on quality and cost. Cline lets you add files, folders and images to a task by mention, and the CLI accepts the same at-sign syntax. Point the agent at the two files that matter instead of the whole tree. Long sessions drag every earlier turn along as input tokens, so start a fresh task once a feature lands rather than stacking unrelated work into one thread. Small, finished tasks also make the history easier to audit, since each one maps to one commit and one diff you can read in a minute.
What a Good Result Looks Like
Your model will not write identical code, and it does not need to. It needs to satisfy three checks. The new tests must fail before the change and pass after it. The timestamp test must stay green. And the diff must touch only the two expected files. Here is the reference change the demo repo uses, so you can compare. It adds an ipv6 pattern ahead of ipv4 and matches three shapes: the eight-group form, compressed forms containing ::, and a leading ::.
("ipv6", re.compile(
r"(?<![\w:])(?:"
r"(?:[0-9A-Fa-f]{1,4}:){7}[0-9A-Fa-f]{1,4}"
r"|(?:[0-9A-Fa-f]{1,4}:){1,7}:(?:[0-9A-Fa-f]{1,4}(?::[0-9A-Fa-f]{1,4}){0,6})?"
r"|::(?:[0-9A-Fa-f]{1,4}:){0,6}[0-9A-Fa-f]{1,4}"
r")(?![\w:])"
)),
The accompanying tests assert that 2001:db8::1, the full eight-group form and ::1 all redact, and that 12:30:45 job done passes through unchanged. A naive pattern such as “any run of hex groups separated by colons” fails that last test, which is exactly the trap the prompt warned about. With the change in place the suite reads:
........ [100%]
8 passed in 0.02s
Step 8. Review Diffs, Checkpoints and Approvals
Step 8. Review every diff. Cline asks before each file edit and each shell command unless you turn on auto-approve. Keep that default for the first week. Read the diff, run the tests yourself at least once, and use the checkpoint feature to roll back when a task wanders. The Cline site promises checkpoints and one-click undo on every step, which makes an experiment cheap to abandon.
Auto-approve is where people get hurt. It is a convenience for trusted, reversible work, such as reading files and running the test suite on a throwaway branch. It is a poor fit for anything that touches the network, installs packages or deletes files. Approve narrow categories rather than flipping the global switch, and keep the feature off whenever the agent works near credentials.
Commit the finished change on the feature branch with a message that names the pattern. The repo now has a green suite, a branch with one clean diff, and a rules file that did its job. Nothing in this flow needed a paid plan.
Step 9: Add a Local Fallback Model With Ollama #
Hosted models go down, rate limits hit at bad moments, and some code simply cannot leave the laptop. A local fallback covers all three, and it is where an open source ai coding assistant earns its keep. Cline lists Ollama as its CLI-friendly local runtime and LM Studio as the GUI option. This step uses Ollama, which the docs say needs no API key, only a running server.
export LOCAL_MODEL="your-model-tag"
ollama pull "$LOCAL_MODEL"
ollama serve
Ollama’s default context window is small for agent work, and Cline sends a lot of context on every turn. Create a derived model with a larger window. Use a number your memory can carry, because an oversized window slows generation and can push the model out of GPU memory.
cat > Modelfile <<EOF
FROM $LOCAL_MODEL
PARAMETER num_ctx 32768
EOF
ollama create cline-local -f Modelfile
In the extension, set the API Provider to Ollama, leave the base URL at its default of http://localhost:11434, and choose cline-local from the model list. If the list stays empty, the server is not running or the URL is wrong. In the CLI, run cline auth again and select the local provider. Expect slower answers and weaker multi-file planning than a hosted flagship produces. A local model shines on small, well-specified edits, which is exactly what your Plan mode prompts should produce anyway.
Model choice here is a separate decision from the tool, and several open-weight models that run locally also appear in the ClinePass lineup. To see how another editor agent handles the same Ollama setup, the Kilo Code local setup guide walks through it side by side.
Step 10: Connect MCP Servers Without Losing Output #
The Model Context Protocol lets Cline call tools such as database readers, issue trackers or documentation search. The CLI manages servers through the cline mcp command, and the extension has a matching settings screen. Run cline mcp --help to see the subcommands your build supports, because the surface has changed across recent releases and a remembered syntax can be stale.
Three October fixes explain most MCP trouble reports. CLI v3.0.67 added a way to page through MCP tool output that exceeds the context limit, so long results no longer vanish. Extension v4.1.23 added the same kind of pagination for oversized tool results. And CLI v3.0.69 raised the Windows startup timeout for MCP servers launched through npx or uvx from 3 seconds to 10, because slow-starting servers were being silently dropped. If a server works on macOS and Linux but never shows up on Windows, update before you debug anything else.
Treat every MCP server as code with the permissions you hand it. Give database tools a read-only account, scope tokens to one project, and keep secrets in environment variables rather than in a committed config file. Start with a single server, confirm that its tools appear in a task, and add the next one only after the first behaves. Each added tool also adds description text to every request, so a long tool list quietly raises your token bill.
Steps 11 and 12: Guardrails and a Headless Review Gate #
Step 11. Block Runs on Dirty Trees and Protected Branches
The CLI documents one behavior that surprises newcomers. The global --auto-approve flag defaults to true. A bare cline "task" run, especially a headless one, can therefore edit files and run commands without asking. The docs also state that the CLI has no allow or deny list for shell commands. To block specific commands, they point to a PreToolUse hook that cancels run_commands calls you do not allow. Read the Hooks page of the docs for the current file format before you write one.
A hook is the right tool for command filtering, but a plain shell guard handles the first line of defense without any Cline-specific format. The script below refuses to start an agent run on main, master or a release/ branch, and refuses a dirty working tree so you can always diff the agent’s work against a clean commit.
#!/usr/bin/env bash
set -euo pipefail
branch="$(git rev-parse --abbrev-ref HEAD)"
case "$branch" in
main|master|release/*)
echo "guard: refusing to run on protected branch '$branch'" >&2
exit 1
;;
esac
if [ -n "$(git status --porcelain)" ]; then
echo "guard: working tree is dirty, commit or stash first" >&2
exit 1
fi
echo "guard: ok on branch '$branch'"
Run it before any unattended session, and chain it with the agent so a failure stops everything: bash scripts/guard.sh && cline --auto-approve true "run tests and fix failures". These are the results from the demo repo in three situations.
$ git checkout main && bash scripts/guard.sh
guard: refusing to run on protected branch 'main'
$ git checkout feature/ipv6 && bash scripts/guard.sh
guard: ok on branch 'feature/ipv6'
$ echo "dirty" >> README.md && bash scripts/guard.sh
guard: working tree is dirty, commit or stash first
Step 12. Gate Pushes With a Headless Review
Headless mode activates when you pass --json, pipe data into Cline, or redirect its output. The docs show the pattern this step uses: pipe a diff in, request newline-delimited JSON, and let jq keep only the final answer. Each JSON line carries a type. Agent events arrive as agent_event lines, and a run_result line holds the final text when the run ends.
#!/usr/bin/env bash
set -euo pipefail
BASE="${1:-main}"
MODEL_FLAG=()
if [ -n "${CLINE_REVIEW_MODEL:-}" ]; then
MODEL_FLAG=(-m "$CLINE_REVIEW_MODEL")
fi
diff="$(git diff "$BASE"...HEAD -- . ':(exclude)*.lock')"
if [ -z "$diff" ]; then
echo "review: no changes against $BASE"
exit 0
fi
printf '%s\n' "$diff" | cline --json --auto-approve false --timeout 300 "${MODEL_FLAG[@]}" \
"Review this diff for bugs, leaked secrets and missing tests. Reply with a short bullet list." \
| jq -r 'select(.type == "run_result") | .text'
Several choices in that script are deliberate. It passes --auto-approve false so a review run cannot edit files, which keeps a read-only job read-only. It sets --timeout 300 so a stalled provider cannot hang your push. It takes the model from an environment variable and passes it with -m, so a team can pin one model without editing the script. And it excludes lock files, which burn tokens and rarely contain reviewable logic.
The pipeline was tested against a stub cline that emits one agent_event line and one run_result line, to confirm the jq filter. With a real model the bullets will differ, but the shape matches the docs. Sample output looks like this:
$ bash scripts/review.sh main
- No secrets found
- Add a test for IPv6 addresses with an embedded IPv4 tail
Wire the script into a pre-push hook so the review runs before code leaves your machine. Keep the hook advisory at first, printing the review without blocking, until you trust the signal.
cat > .git/hooks/pre-push <<'EOF'
#!/usr/bin/env bash
bash scripts/guard.sh || exit 0
echo "--- Cline review ---"
bash scripts/review.sh main || true
EOF
chmod +x .git/hooks/pre-push
That hook skips the review on protected branches and dirty trees, prints the result, and never blocks the push.
Judge the reviewer the way you would judge a new teammate. For the first week, keep a short note of each flagged item and mark it useful, noise or wrong. If more than a handful per day land in the noise bucket, tighten the prompt, narrow the diff with a path filter, or switch to a stronger model for reviews only. A cheap fast model often suffices for catching missing tests and obvious leaks, while subtle logic errors reward a larger one. Because the script reads its model from CLINE_REVIEW_MODEL, that experiment takes one environment variable and no code change. Once your team agrees the reviews are useful, replace || true with a check that fails the hook when the answer mentions a leaked secret. Run the same script in CI as well, with one caveat: confirm how your CI job authenticates the CLI by checking cline auth --help for your build, since interactive browser sign-in does not work on a runner.
Common Pitfalls That Burn Time and Tokens #
Seven mistakes account for most of the support questions around Cline. Each one is cheap to avoid.
- Trusting the default model. The recommended model changed more than once in October, and the Cline provider’s default went back to Claude Sonnet 5.5 after a short detour. Pin a model with the model dropdown in the IDE or
-min the CLI so your tests and your bill stay stable. - Mixing up version tracks. The extension (4.1.26), CLI (3.0.74) and Desktop app (0.0.49) have unrelated numbers. Reporting “version 4” to a teammate tells them nothing. Always name the surface.
- Assuming headless runs ask permission. The CLI’s auto-approve flag defaults to true. Add
--auto-approve falseto read-only jobs and run write jobs on a clean feature branch. - Confusing ClinePass with usage-billing. They are separate providers. A ClinePass subscription does not fund the pay-as-you-go balance, and the reverse is also true. If a model shows as unavailable, check which provider is selected before you assume an outage.
- Starving a local model of context. Agent prompts are long. A default Ollama window truncates them silently, and the agent then “forgets” your rules. Raise the window with a Modelfile as shown in Step 9.
- Vague tasks. “Improve the tests” invites a sprawling diff. Name the file, the failure and the acceptance check, as the Step 7 prompt does.
- Skipping the diff. An approved edit you never read is a bug you chose to ship. Read it, run the suite yourself once, and use checkpoints when a session drifts.
Two quieter traps deserve a mention.
A third trap is specific to security tooling like logscrub. Agents love realistic fixtures, and a model asked for “a sample AWS key” may produce something that looks live. The rules file in Step 6 bans real credentials and names the documentation address ranges for that reason. Scan the diff for anything that resembles a real key before you commit, and treat any value that survives a search of your provider’s console as compromised. The self-hosted Qwen Code walkthrough covers credential hygiene for a different agent, and most of its advice transfers. Plugin authors who relied on the old in-process mode must move to the worker or sandbox mode that CLI v3.0.72 made standard. And the model catalog keeps growing, with one release summary reporting the SDK catalog rising from 6,862 to 6,952 models in a single update. A huge catalog makes the search box more useful than the dropdown, so type the model name instead of scrolling.
Troubleshooting: 12 Failures and Fixes #
Work down this table from the top. The first five rows come straight from the docs’ own authorization troubleshooting list or from documented CLI behavior. The rest come from the October release notes.
| Symptom | Likely cause | Fix |
|---|---|---|
cline: command not found after install |
The global npm bin folder is not on your PATH | Run npm config get prefix , add itsbin folder to PATH, open a new shell |
| “Unauthorized: Please sign in” | Session expired | Click Sign In in the IDE or run cline auth again |
| Browser does not open during sign-in | Default browser setting or a blocked launch | Copy the URL from the Cline output panel and open it manually |
| Frequent re-authentication | Org security policy or cleared IDE secrets | Check policies, stop clearing IDE secret storage, do a full sign-out and sign-in |
| Cannot access your organization | Membership missing or stale session | Verify membership at app.cline.bot, ask your admin, sign out and back in |
| Selected model vanished after an update | The catalog refresh removed or renamed it | Open the model dropdown, pick a current entry, then run cline config to confirm |
| Windows MCP server never appears | Slow npx oruvx start hit the old 3-second limit |
Update the CLI to v3.0.69 or newer, where the limit is 10 seconds |
| Plugin fails to load on CLI 3.0.72 or later | CLINE_PLUGIN_MODE=in_process no longer exists |
Remove the variable and use the default worker mode or sandbox mode |
| Local model list is empty | Ollama is not running or the URL is wrong | Start ollama serve , confirmhttp://localhost:11434 responds, refresh the list |
| Agent ignores your rules on a local model | Context window too small | Rebuild the model with a larger num_ctx as in Step 9 |
| Long MCP tool results get cut off | Build predates output paging | Update the CLI to v3.0.67 or newer and the extension to v4.1.23 or newer |
| Headless run hangs | Stalled provider or an endless tool loop | Add --timeout 600 , or a lower value, and rerun with--json to see the last event |
When none of these fit, run cline doctor first and keep its output. Then compare cline config against what the IDE shows, because a mismatch between the two surfaces is a common cause of “works in VS Code but not in the terminal” reports. If the problem survives that check, the project’s GitHub issues page is the right place to search, and including your exact extension and CLI versions makes the report actionable.
Advanced Tips and the Finished Project Checklist #
Once the basics hold, a few features turn Cline from a chat box into a workflow. The docs list every one of them, but they are easy to miss.
- Reasoning effort. The CLI takes
--thinkingwith the values none, low, medium, high or xhigh. A bare--thinkingmeans medium. Use low for mechanical edits and high for design questions. - Pipes and chains.
git diff | cline "explain these changes" | cline "write a commit message"strings two runs together. PipeREADME.mdin for a quick summary of setup steps. - Isolated state. The
--data-dirand--configflags point a run at its own state and config directory, which is handy for CI jobs and for testing a new provider without touching your daily setup. - Images. Mention a file with the at sign, as in
cline "fix the UI shown in @./design-mockup.png", and the CLI attaches the image to the prompt. - Schedules and the hub.
cline scheduleruns tasks on a timer andcline hubmanages the local daemon. The v3.0.74 notes reportedly make a duplicate request attach to an already-running task instead of starting a second one. - Parallel agents.
npx kanbanopens a web task board that runs many agents in parallel, with per-card worktrees and dependency chains, so two agents never edit the same checkout. - Other editors. The Agent Client Protocol mode lets Zed, JetBrains IDEs and Neovim use Cline as their coding agent, and the Desktop app runs it without any editor.
- Cloud sessions. Since mid-October, the extension can run a task in a hosted sandbox against a GitHub repository and branch, with a separate model setting for cloud tasks. Keep sensitive repos on local runs until your team approves the data path.
- Team controls. Cline’s enterprise tier adds SSO, role-based access control, per-team model and tool limits, and remote configuration, according to the docs overview.
The finished demo repo should now look like this, and every file in it earns its place.
cline-demo/
.clinerules project rules the agent reads
.gitignore
pyproject.toml
src/logscrub/__init__.py
src/logscrub/scrub.py patterns, now including ipv6
src/logscrub/cli.py
tests/test_scrub.py 8 tests after Step 7
scripts/guard.sh branch and tree check
scripts/review.sh headless diff review
.git/hooks/pre-push advisory review before push
Run this last checklist for your Cline AI setup and mark each line.
pytest -qprints 8 passed on the feature branch.cline configshows the provider and the model you pinned.bash scripts/guard.shfails onmainand passes onfeature/ipv6.bash scripts/review.sh mainprints a short bullet list and exits cleanly.- The diff against
maintouchesscrub.py,test_scrub.pyand the scripts, and nothing else. - No real credential appears anywhere in the repo or the test data.
The takeaway: as an open source ai coding assistant, Cline is easy to start and just as easy to over-trust. Pin the model, keep the rules short, review every diff, and make the safe path the default one. Do that and the same setup scales from one demo repo to a team’s daily work without surprises on the bill.
FAQ #
Is Cline AI free to use?
The Cline extension and CLI are free, and you pay only for model inference through credits, your own provider key, or the optional ClinePass subscription at $9.99 a month. Local models through Ollama or LM Studio cost nothing beyond your hardware. Some models in Cline’s free list cost nothing per request, though that list changes often.
What is the difference between ClinePass and Cline usage-billing?
They are separate providers. Usage-billing is pay-as-you-go with prepaid credits and a few free model options. ClinePass is a flat monthly plan that gives 2-5x the usage of standard API rates on a curated set of open coding models, tracked against rolling 5-hour, weekly and monthly limits. Neither requires the other, and you can configure both.
Can Cline run entirely offline?
Yes, with a local runtime. Point the provider at Ollama or LM Studio, pick a model your hardware can hold, and no code leaves the machine. Expect weaker multi-file planning than a hosted flagship offers, and raise the context window so the agent keeps your rules in view.
How do I stop Cline from running commands without asking?
In the IDE, keep auto-approve off and approve each action. In the CLI, pass --auto-approve false, because the flag defaults to true. The CLI has no allow or deny list for shell commands, so use a PreToolUse hook to cancel commands you do not want, and run unattended jobs on a clean feature branch.
Which model should I pick in October 2026?
Start with Claude Sonnet 5.5 if you use a hosted key, since it is the Cline provider’s current default and lists at $2 per million input tokens and $10 per million output tokens. For a flat-rate open-weight route, the ClinePass default is Kimi K3.1 Pro as of October 26. Whatever you choose, pin it by name and recheck after each catalog refresh.
Does the CLI work in CI?
Yes. Headless mode activates with --json, piped input or redirected output, and it supports timeouts and non-interactive flags. The open question is authentication, since browser sign-in does not work on a runner. Check cline auth --help for your build and store credentials as encrypted CI secrets.
Should I use the extension, the CLI or the Desktop app?
Use the extension for day-to-day edits where you want to see diffs inline, the CLI for scripts, pipes and automation, and the Desktop app if you prefer a standalone window for open-weight models with parallel sessions and scheduled tasks. They share one agent core, so rules and habits carry across.