Cline

Cline is an open-source coding agent published by Cline Bot Inc. as a VS Code extension, a terminal CLI, and a desktop app, all on one SDK. The model-facing file family is four dedicated tools in the default set: read_files, editor, run_commands, and search_codebase, with apply_patch swapped in for editor when the model ID contains gpt or codex or the provider is openai-native. The read, search, and shell tools take a batch and return a JSON array of per-item results, and the shell tool runs the items of one call concurrently. This page describes the cline CLI in its default act preset with auto-approve on, on a Linux host, with the SDK's Node executors and a model that keeps editor.

Source

The VS Code host shares the SDK tool definitions but replaces the run_commands and read_files executors with terminal and editor backed ones. It is not surveyed.

Tool inventory

Outside this page: fetch_web_content, skills, ask_question, submit_and_exit, spawn_agent, the team tools, tasks, and provider web_search. There is no list, glob, stat, mkdir, or notebook tool; the run_commands description names listing files as a shell job. apply_patch is the only tool that deletes. Presets live in presets.ts; resolveToolPresetName picks plan for --plan, yolo for --yolo, and act otherwise. A global disabledTools setting or a tool policy with enabled: false removes any tool.

Read

Signature

read_files({ files: Array<{ path: string, start_line?: number | null, end_line?: number | null }> })

path is described as absolute. start_line and end_line are one-based and inclusive, positive integers, coerced from strings, nullable. The runtime also accepts a bare string, an array of strings, file_path and filePath in place of path, and file_paths or paths in place of files, and folds a bare {start_line, end_line} element into the entry before it. start_line above end_line fails that entry. Each file has a 10 s timeout inside the tool. The retryable and maxRetries fields on every definition are metadata; the agent runtime does not read them.

Description

read_files: 634 characters, 634 bytes, 1 line, approximately 130 tokens.

read_files (634 characters)

Read the content of text or image files at the provided absolute paths, or return only an inclusive one-based line range when start_line/end_line are provided on the same file entry as its path. When you already know multiple files you need, read them together in one call, and call this tool in the same response as other independent tool calls. Each read returns at most 2000 lines / ~47k characters; longer files report their total line count, page through them with start_line/end_line on that file's entry. Binary files that are not image and large files are not supported. Returns file contents or error messages for each path. 

Path handling

An absolute path is normalised. A relative path resolves against process.cwd(), the Node process directory, which the CLI does not change when --cwd is passed; editor and apply_patch use the session directory instead. When the path does not exist, resolveExistingFilePath probes variants in order: a narrow no-break space before AM or PM, the NFD form, straight apostrophes replaced by U+2019, NFD with curly apostrophes, then a parent-directory scan that compares basenames after NFC and after collapsing Unicode spaces to a plain space. The first hit is read. The model is not told a variant was used; the query field echoes the requested path. No tilde expansion, no URL handling, no containment check.

Without a match fs.stat throws and the entry reports the Node message:

Error reading file: ENOENT: no such file or directory, stat '<path>'

Symlinks: followed with no check.

Permissions

Binary and conversion

Limits

The window notice is appended after a blank line whenever the last captured line is before the effective end:

[Showing lines <start>-<last> of <total>. Use start_line/end_line to read other sections.]

Output

Executor text for one entry:

1 | import { x } from "./x"
2 | export const y = x

What the model receives for the call:

[{"query":"/repo/src/app.ts","result":"1 | import { x } from \"./x\"\n2 | export const y = x","success":true}]

The examples are reconstructed from the format code. A ranged read echoes query as <path>:<start>-<end> with 1 and EOF as defaults.

Notable

• Stale-read rewrite: when a path or the same range is read again later, the session message builder replaces the older result text with [outdated - see the latest file content] once at least 65 536 bytes of such content are pending. A later whole-file read also outdates earlier ranged reads of that path.
• Multiple entries in one call run in parallel with Promise.all.
• Abort destroys the stream; the entry reports the abort reason or File read was aborted.
• The description says non-image binaries are unsupported; the executor has no check, so a binary file returns replacement-character text.
• No repeat-read guard, no content injection after the read, no redaction, no explicit empty-file notice; an empty file returns "".
• The tool catalog in runtime.ts carries a shorter summary per tool for host settings screens. It is not what the model sees.

Edit

Signature

editor({ path: string, old_text?: string | null, new_text: string, insert_line?: number | null })
apply_patch({ input: string })

editor picks one of three operations: insert_line present inserts new_text before that one-based line (line_count + 1 appends); otherwise a missing file is created with new_text; otherwise old_text is replaced by new_text. old_text and new_text above 6000 characters are refused before the executor runs. apply_patch also accepts a bare string. The grammar markers are *** Begin Patch, *** End Patch, *** Add File: , *** Update File: , *** Delete File: , *** Move to: , @@, and *** End of File. Both have a 30 s timeout inside the tool. editor is the default; apply_patch replaces it under the routing rule in the Tool inventory.

Description

editor: 551 characters, 551 bytes, 1 line, approximately 113 tokens. apply_patch: 1224 characters, 1224 bytes, 37 lines, approximately 298 tokens.

editor (551 characters)

An editor for controlled filesystem edits on the text file at the provided path. Provide `insert_line` to insert `new_text` at a specific line number. Otherwise, the tool replaces `old_text` with `new_text`, or creates the file with `new_text` if file does not exist. Use this tool for making small, precise edits to existing files or creating new files over shell commands. If several edits to different files or non-overlapping regions are already known, emit multiple editor tool calls in the same response instead of serializing them across turns.

apply_patch (1224 characters), present only when the routing rule selects it

Use `apply_patch` to edit files with the canonical freeform patch grammar. Pass the patch text directly as the `input` string. Prefer the exact format below:

*** Begin Patch
*** Update File: path/to/file.ts
@@ optional section marker
 [context before]
-[old line]
+[new line]
 [context after]
*** End Patch

Supported actions:
- `*** Add File: <path>`
- `*** Update File: <path>`
- `*** Delete File: <path>`
- optional `*** Move to: <new path>` immediately after an Update File header

Rules:
- In an Add File section, every file-content line must start with `+`.
- In an Update section, use context lines plus `-` and `+` lines to describe the change.
- Use `@@` markers when extra context is needed to disambiguate repeated code blocks.
- Do not use line numbers; this format is context-based.
- Prefer sending the patch body directly. Legacy shell wrappers such as `%%bash` and `apply_patch <<"EOF"` are accepted for compatibility but are not preferred.

Example:

*** Begin Patch
*** Update File: src/page.tsx
@@
   return (
     <div>
       <button onClick={() => console.log("clicked")}>Click me</button>
+      <button onClick={() => console.log("cancel clicked")}>Cancel</button>
     </div>
   );
 }
*** End Patch

Whole-file write

editor writes a whole file only when the path does not exist: parent directories are created recursively, then fs.writeFile writes new_text directly. On Windows hosts \n becomes \r\n when the content has no \r; elsewhere the content is written as supplied. No temporary file, no rename, no backup, no mode handling, no BOM handling, no read-back. An existing file cannot be replaced whole; old_text omitted or null on an existing path is an error that spells out the recovery. apply_patch *** Add File: writes the same way and refuses an existing path.

Relative paths resolve against the session directory and must stay inside it when restrictToCwd is on, which it is by default: Path must stay within cwd: <path>. Absolute paths are accepted anywhere.

Matching

editor reads the file, detects the line ending (CRLF when \r\n appears anywhere, else LF), normalises old_text and new_text to it, and counts occurrences with split. Zero and more than one are errors; the file is unchanged. Exactly one is replaced with a replacer function so $ sequences in new_text stay literal. Exact match only. No whitespace, indentation, or Unicode fallback. No replace_all.

apply_patch matches context lines through a cascade after canonicalisation (NFC, dash and quote variants folded, no-break spaces to space, backslash escapes removed): exact, trailing whitespace trimmed, fully trimmed, then Levenshtein similarity at or above 0.66. Each stage adds fuzz (1, 100, 1000); a match after *** End of File that falls back to a forward search adds 10 000. A hunk with no match is a warning, and any warning aborts the whole patch before a write. Fuzz above zero is reported to the model.

Multi-file patch

Present as apply_patch. The executor strips wrapper lines or locates the sentinels, reads every update and delete target and any add target that exists, parses all sections, and computes the new content of every file in memory. Then it applies in order: delete removes the file; add creates parents and writes; update writes in place, or writes the destination and removes the source when *** Move to: is present. No staging and no rollback, so an I/O failure part way leaves earlier files changed. A parse or context failure happens before any write. Chunk math runs in LF space and each update is written back in the file's own line ending.

Verification and mutation state

Output

Each is wrapped as one object: query is edit:<path>, insert:<path>, or apply_patch. Reconstructed replace result:

Edited /repo/src/app.ts
```diff
-2: export const y = x
+2: export const y = x + 1
```

Notable

• The editor diff quotes changed lines with a colon prefix; the read_files prefix is a pipe. The model sees two prefix styles.
• No notebook editor, no undo tool. Checkpoints are the SDK's git stash refs.
• The insert_line bound error names the valid range and the append value.
• Hosts can call computePatchChanges to preview a patch; the CLI does not.
• old_text null or omitted on an existing path returns this text, with omitted in place of null when the field was absent:

<path> already exists, but `old_text` was null. To edit an existing file, set `old_text` to the exact text in the file that `new_text` should replace (read the file first if needed). To insert instead, provide `insert_line`. Do not re-send this call unchanged.

Shell

Signature

run_commands({ commands: string[] })

The runtime also accepts a bare string, an array, { command }, { cmd }, and structured { command, args } entries that spawn the executable directly without a shell. A heredoc split across array elements is rejoined. There is no timeout, cwd, or background parameter.

Description

run_commands: 993 characters, 993 bytes, 1 line, approximately 197 tokens. Rendered for shell /bin/bash on a non-Windows host, which is what getDefaultShell returns on Linux and macOS. Six other renders follow, each selected by the configured shell and the host platform through buildRunCommandsDescription.

run_commands (993 characters), shell /bin/bash, non-Windows host

Run non-interactive shell commands from the root of the workspace. Use for listing files, checking git status, running builds, executing tests, etc. Commands must be non-interactive. Commands that require follow-up input like pagers should be skipped or used with supported flags/env (e.g. git --no-pager, --non-interactive) to bypass the interaction steps. Commands should be properly shell-escaped and targeted to avoid error or timeout. Include multiple commands in the same call when they are independent complete shell commands and safe to run concurrently; multiline scripts and heredocs must be a single command string. When independent reads, searches, or edits are also needed, call those tools in the same response. Output beyond ~48k characters is middle-truncated (start and end preserved); pipe through grep/head/tail when you need specific sections of large output. For long-running commands, run them in background and redirect output to a tmp file that you can read from later.

run_commands (1058 characters), a POSIX shell such as bash.exe on a Windows host

Run non-interactive shell commands from the root of the workspace. Use for listing files, checking git status, running builds, executing tests, etc. Commands must be non-interactive. Commands that require follow-up input like pagers should be skipped or used with supported flags/env (e.g. git --no-pager, --non-interactive) to bypass the interaction steps. Commands run through a POSIX (bash-compatible) shell on Windows. Commands should be properly shell-escaped and targeted to avoid error or timeout. Include multiple commands in the same call when they are independent complete shell commands and safe to run concurrently; multiline scripts and heredocs must be a single command string. When independent reads, searches, or edits are also needed, call those tools in the same response. Output beyond ~48k characters is middle-truncated (start and end preserved); pipe through grep/head/tail when you need specific sections of large output. For long-running commands, run them in background and redirect output to a tmp file that you can read from later.

run_commands (1098 characters), shell wsl.exe

Run non-interactive shell commands from the root of the workspace. Use for listing files, checking git status, running builds, executing tests, etc. Commands must be non-interactive. Commands that require follow-up input like pagers should be skipped or used with supported flags/env (e.g. git --no-pager, --non-interactive) to bypass the interaction steps. Commands run through bash in WSL (wsl.exe); the Windows working directory is mounted under /mnt/<drive>. Commands should be properly shell-escaped and targeted to avoid error or timeout. Include multiple commands in the same call when they are independent complete shell commands and safe to run concurrently; multiline scripts and heredocs must be a single command string. When independent reads, searches, or edits are also needed, call those tools in the same response. Output beyond ~48k characters is middle-truncated (start and end preserved); pipe through grep/head/tail when you need specific sections of large output. For long-running commands, run them in background and redirect output to a tmp file that you can read from later.

run_commands (1022 characters), shell powershell on a Windows host

Run non-interactive shell commands from the root of the workspace in Windows environment. Use for listing files, checking git status, running builds, executing tests, etc. Commands must be non-interactive. Commands that require follow-up input like pagers should be skipped or used with supported flags/env (e.g. git --no-pager, --non-interactive) to bypass the interaction steps. Output beyond ~48k characters is middle-truncated (start and end preserved); filter output when you need specific sections. Commands run through Windows PowerShell (powershell.exe); quote paths and arguments for powershell.exe and use ';' to sequence commands. Write commands directly; do not wrap them in another powershell.exe -Command invocation. Only start another shell when you intentionally need a different shell or a separate process. Include multiple commands in the same call when they are independent and safe to run concurrently. When independent reads, searches, or edits are also needed, call those tools in the same response.

run_commands (996 characters), shell pwsh.exe on a Windows host

Run non-interactive shell commands from the root of the workspace in Windows environment. Use for listing files, checking git status, running builds, executing tests, etc. Commands must be non-interactive. Commands that require follow-up input like pagers should be skipped or used with supported flags/env (e.g. git --no-pager, --non-interactive) to bypass the interaction steps. Output beyond ~48k characters is middle-truncated (start and end preserved); filter output when you need specific sections. Commands run through PowerShell (pwsh.exe); quote paths and arguments for pwsh.exe and use ';' to sequence commands. Write commands directly; do not wrap them in another pwsh.exe -Command invocation. Only start another shell when you intentionally need a different shell or a separate process. Include multiple commands in the same call when they are independent and safe to run concurrently. When independent reads, searches, or edits are also needed, call those tools in the same response.

run_commands (961 characters), shell pwsh on a non-Windows host

Run non-interactive shell commands from the root of the workspace. Use for listing files, checking git status, running builds, executing tests, etc. Commands must be non-interactive. Commands that require follow-up input like pagers should be skipped or used with supported flags/env (e.g. git --no-pager, --non-interactive) to bypass the interaction steps. Output beyond ~48k characters is middle-truncated (start and end preserved); filter output when you need specific sections. Commands run through PowerShell (pwsh); quote paths and arguments for pwsh and use ';' to sequence commands. Write commands directly; do not wrap them in another pwsh -Command invocation. Only start another shell when you intentionally need a different shell or a separate process. Include multiple commands in the same call when they are independent and safe to run concurrently. When independent reads, searches, or edits are also needed, call those tools in the same response.

run_commands (975 characters), shell cmd.exe

Run non-interactive shell commands from the root of the workspace in Windows environment. Use for listing files, checking git status, running builds, executing tests, etc. Commands must be non-interactive. Commands that require follow-up input like pagers should be skipped or used with supported flags/env (e.g. git --no-pager, --non-interactive) to bypass the interaction steps. Output beyond ~48k characters is middle-truncated (start and end preserved); filter output when you need specific sections. Commands run through cmd.exe; quote paths and arguments for cmd.exe and use '&&' to sequence commands. Write commands directly; do not wrap them in another cmd.exe /c invocation. Only start another shell when you intentionally need a different shell or a separate process. Include multiple commands in the same call when they are independent and safe to run concurrently. When independent reads, searches, or edits are also needed, call those tools in the same response.

Working directory and environment

The working directory is the session directory (--cwd or the launch directory). The environment is process.env with no additions from the CLI. The shell is /bin/bash unless configured, invoked as bash -c <command>: non-login, non-interactive. PowerShell editions run -NoProfile -NonInteractive -Command with a bootstrap that reads the script from UTF-8 stdin, sets $ErrorActionPreference='Stop', and exits 1 when the last statement failed. cmd.exe runs /d /s /c. wsl.exe runs bash -c inside the guest.

Process lifecycle

A detached command returns [Command is still running. Output will continue in <path>] plus the output so far; later output goes to a cline-command-*/output.log file under the OS temp directory, capped at 10 MiB and kept 24 h.

Output limits

The 8000-character per-string cut in the session message builder applies to result on every provider request after the executor's own cut.

Sandbox

None. No container, seccomp, Seatbelt, or network policy. The child inherits the Cline process account and environment. The --data-dir flag, called sandbox in the CLI code, isolates Cline's own state directory and does not confine commands.

Approval

Order in the agent runtime: beforeTool hooks, then the tool policy. enabled: false skips the call; autoApprove: false asks the host; a refusal returns an error result whose text is the host reason plus -- NOT a tool or system failure. Clarify with user before proceeding.

Plan mode adds a beforeTool hook on run_commands. It masks quoted text, heredoc bodies, escapes, and comments, rejects output redirection outside /dev/null, /dev/stdout, /dev/stderr, /dev/tty, nul, /tmp/, /var/tmp/, $TMPDIR, %TEMP%, and $env:TEMP, then splits on newlines, ;, |, &, parentheses, and backticks and checks the first command word of each segment after skipping assignments, reserved words, and wrappers such as sudo, env, xargs, and timeout. Blocked: a fixed list of file commands (rm, mv, cp, touch, mkdir, chmod, and the PowerShell item and content cmdlets), mutating subcommands of git, npm, pnpm, yarn, bun, pip, cargo, apt, brew, gem, composer, go, dotnet, winget, and nuget, python -m pip, sed -i, perl -i, awk -i inplace, sort -o, curl -o, wget without --spider or -O-, find -delete and the tail of -exec, and tee outside a temp path. git stash list, git worktree list, git submodule status, and --help pass. The hook runs before approval and the result is a skip with this text:

Command not executed: <construct> can modify files, and file modifications are blocked in plan mode. You are in PLAN MODE — explore, analyze, and present a plan; do not make changes. Use read-only commands to inspect the project (redirecting output to /tmp, or %TEMP% on Windows, is allowed), and if this change is part of the task, put it in your plan so it can run after the user approves switching to act mode.

Notable

• A non-zero exit is a per-command failure inside a successful tool result: result is [Command exited with code <n>] followed by the output, error is Command exited with code <n>, success is false.
• No PTY, no interactive input, no streaming to the model, no per-call timeout.
• A run_commands entry with an args key runs the executable directly, so shell operators in its arguments are literal.
• Timeouts are reported to telemetry with the source of the timeout setting.

Search and listing

Tools

Each query first runs rg --json --context=2 --max-count=1 -i <query> in the session directory: case-insensitive, at most one match per file. Context events attach to the most recent match, so lines before a match attach to the previous match and the first match's leading context is dropped. Zero matches, a ripgrep failure, a timeout, or an abort fall through to a regex scan with new RegExp(query, "gim") over the file index, where every match on every line counts and context rows mark the match line with >. Output is Found <n> results for pattern: <query>, a blank line, then <file>:<line>:<column> and its context rows per match; the fallback adds Searched <m> files. after the first line, and returns No results found for pattern: <query> then Searched <m> files. when nothing matched. At the cap: (Showing first 100 results. Refine your search for more specific results.). Over budget: [... search output truncated: <n> chars total. Narrow the pattern or scope to view the elided matches ...].

Description

search_codebase: 444 characters, 444 bytes, 1 line, approximately 85 tokens.

search_codebase (444 characters)

Perform regex pattern searches across the codebase. Supports multiple parallel searches. When several search patterns could be useful and do not depend on each other, run them together in one call, and call this tool in the same response as other independent tool calls. Use for finding code patterns, function definitions, class names, imports, etc. Output beyond ~48k characters per query is middle-truncated; narrow patterns beat broad ones.

Errors

Entry transport means one element of the JSON array returned by a successful tool call, with query, an empty result unless noted, error, and success: false. Tool-level transport means {"error": <text>} with isError set. The table has 33 rows because each row is a distinct string family in source.