docs
// Guides

Cline

Global settings, project rules. Cline keeps MCP and provider settings in one ~/.cline/data/settings/ folder shared by the IDE extension, the CLI and the SDK, and reads rules from .cline/rules/. The Erebine bundle merges an MCP server entry and a custom provider into the settings and drops the rules into the project.

Cline 4.x ships as an IDE extension, a CLI and an SDK. All three resolve the same global settings folder, so one merge covers every one of them. Cline has a native MCP client, native custom OpenAI-compatible providers, and native project rules, so the Erebine bundle installs no extension and no adapter: it is three settings snippets and one rules file.

The Client-tab download carries four files, plus a README.txt:

FileWhat it does
cline_mcp_settings.json The mcpServers.erebine entry: streamable-HTTP URL, Authorization and workspace headers, timeout. Merge into ~/.cline/data/settings/cline_mcp_settings.json.
providers.json The erebine provider's key, base URL, default model and limits, and the CLI's active provider. Merge into ~/.cline/data/settings/providers.json. Present only when this workspace advertises a model that calls tools.
models.json Registers every advertised model that calls tools under a custom erebine provider so the picker lists them. Merge into ~/.cline/data/settings/models.json. Present only with providers.json.
erebine.md The Erebine tool-use rules. Save as .cline/rules/erebine.md at your project root.

~/.cline is Cline's root and ~/.cline/data its data root. Four environment variables move the files:

VariableEffect
CLINE_DIRReplaces ~/.cline. The data root becomes $CLINE_DIR/data.
CLINE_DATA_DIRReplaces the data root. The settings files live under $CLINE_DATA_DIR/settings/.
CLINE_MCP_SETTINGS_PATHThe full path of cline_mcp_settings.json.
CLINE_PROVIDER_SETTINGS_PATHThe full path of providers.json. Cline reads models.json from the same folder.

Cline 3.x extension builds kept MCP settings in the editor's own storage. On those, open MCP Servers > Configure > "Configure MCP Servers" and paste the entry there.

See the general MCP integration documentation for the full tool catalog, the governed-execution model, and the security gates that apply to every MCP request.

Quick Start

Download the Cline bundle from the Chat page's Client tab (visible once a specific workspace is selected), then merge it:

  1. Merge cline_mcp_settings.json, providers.json and models.json into the files of the same name under ~/.cline/data/settings/. Copy a file whole if it does not exist yet.
  2. Save erebine.md as .cline/rules/erebine.md at your project root.
  3. Restart Cline: reload the IDE window, or start a new CLI session. The settings are read at startup.
  4. Select the provider. In the IDE, open Cline Settings, set API Provider to erebine and pick a model; with "Use different models for Plan and Act" on, do it in each mode. The CLI starts on lastUsedProvider, which providers.json sets to "erebine"; in a file you merged into, set it yourself, or pass -P erebine -m <model-id> per run.
  5. Prompt: Call the Erebine intelligence brief tool (erebine.intelligence.brief) and summarize this workspace. The answer proves both halves of the bundle.

Both settings files carry your workspace API key. cline_mcp_settings.json holds it in the Authorization header and providers.json holds it in apiKey. Both live outside your repository; delete the extracted copies rather than leaving them in a tracked project tree. erebine.md carries no secrets and is safe to commit. Re-downloading rotates the key and revokes the one in your previous bundle.

Plan and Act

Plan mode reads and discusses; it edits no files and runs no commands. Act mode executes. Every model the bundle registers calls tools, so any of them can serve either mode.

  • IDE: turn on "Use different models for Plan and Act" in Cline Settings and pick an erebine model per mode. A reasoning model suits Plan; Act runs the tool loop, so give it the model that drives your edits. The extension keeps the per-mode choice in its own state, which the bundle does not touch.
  • CLI: sessions start in Act. cline -p starts in Plan. The CLI uses one provider and model for both modes.

The rules file tells the agent to gather workspace context with the read tools in Plan mode and to record decisions and milestones once the plan is approved.

MCP Server

Cline reads MCP servers from one global file, ~/.cline/data/settings/cline_mcp_settings.json (or $CLINE_MCP_SETTINGS_PATH). In the IDE, MCP Servers > Configure > "Configure MCP Servers" opens it; from a terminal, cline mcp add merges one entry into it (see CLI Setup). This is the whole entry:

JSON
{ "mcpServers": { "erebine": { "type": "streamableHttp", "url": "https://api.erebine.ai/proj_ABC123/v1/mcp", "headers": { "Authorization": "Bearer <api_key>", "X-Erebine-Workspace": "<workspace_id>" }, "timeout": 60, "disabled": false, "autoApprove": [] } } }
  • type is not optional. A URL entry without it is treated as legacy SSE, and the Erebine endpoint answers streamable HTTP.
  • timeout is in seconds, not milliseconds. The default is 60 and the accepted range is 1 to 3600.
  • autoApprove lists the tools Cline may call without asking. It ships empty; add tool names to it once you trust them.
  • <api_key>, a key with the inference scope. Mint one with erectl keys --create --name "cline" --scopes inference.
  • <workspace_id>, the ws_xxx identifier this connection pins to. List options with erectl workspaces list.
  • The IDE expands ${env:EREBINE_API_KEY} in a header from the environment the editor starts in, so "Bearer ${env:EREBINE_API_KEY}" keeps the key out of the file. The CLI expands no placeholder: give it the key itself.

Inference Provider

Cline's custom-provider registry is two files. models.json declares the provider and its models; providers.json holds the credentials and the current selection.

models.json registers every model this workspace advertises that calls tools. Cline sends tools on every turn, so a model without tool calling is left out:

JSON
{ "version": 1, "providers": { "erebine": { "provider": { "name": "Erebine - <workspace_id>", "baseUrl": "https://api.erebine.ai/proj_ABC123/<workspace_id>/_direct/v1", "defaultModelId": "erebine/<model-slug>", "protocol": "openai-chat", "client": "openai-compatible", "capabilities": ["streaming", "tools", "reasoning", "vision"] }, "models": { "erebine/<model-slug>": { "id": "erebine/<model-slug>", "name": "<model-name>", "capabilities": ["streaming", "tools", "reasoning", "images"], "contextWindow": 131072, "maxTokens": 32000, "maxInputTokens": 99072, "modalities": { "input": ["text", "image"], "output": ["text"] } } } } } }

providers.json carries the key and the starting selection:

JSON
{ "version": 1, "lastUsedProvider": "erebine", "modes": {}, "providers": { "erebine": { "settings": { "provider": "erebine", "apiKey": "<api_key>", "baseUrl": "https://api.erebine.ai/proj_ABC123/<workspace_id>/_direct/v1", "model": "erebine/<model-slug>", "protocol": "openai-chat", "client": "openai-compatible", "headers": { "X-Erebine-Augment-Corrective-Retries": "on", "X-Erebine-Augment-Max-Output-Tokens-Clamp": "on" }, "contextWindow": 99072, "maxTokens": 32000, "reasoning": { "effort": "medium", "enabled": true } }, "updatedAt": "1970-01-01T00:00:00.000Z", "tokenSource": "manual" } } }
  • Model capabilities come from the descriptor: tools on every entry, reasoning when the model has a reasoning parser, images when it accepts image input. The provider row is the union over every model, and spells that last one vision.
  • contextWindow is the model's window and maxTokens its output cap, at most half the window. maxInputTokens is the window less the output cap, the budget Cline compacts the conversation against. Each is emitted only when the model publishes it and it is positive.
  • Cline sends maxTokens as max_tokens on every request, so providers.json carries X-Erebine-Augment-Max-Output-Tokens-Clamp: on: Erebine shortens an output cap that does not fit the remaining window instead of refusing the request.
  • Cline reads the contextWindow in providers.json as the input budget, so it carries the default model's maxInputTokens, or its window when there is none.
  • modalities lists what the model takes in (text, plus image and audio where it accepts them) and puts out (text). Cline reads audio input from this field only.
  • reasoning.effort is the model's default effort, emitted only when it is one of Cline's seven levels (none, minimal, low, medium, high, xhigh, max). Those seven are the providers.json vocabulary; the CLI's per-session override, cline --thinking <level>, takes the five it supports: none, low, medium, high, xhigh.
  • updatedAt is a fixed epoch timestamp so the file is byte-stable between downloads. Cline rewrites it the next time it saves settings.

Keep providers.json valid. Cline validates the whole file against its schema and treats a file that fails as empty, which signs you out of every provider you had configured, not just Erebine. updatedAt must be an ISO-8601 datetime and baseUrl must be a full URL. Back the file up before merging.

Switch models in the picker, or with cline --model <id>. The model travels in the request payload, so one base URL covers every id in models.json.

The routing mode chosen at download time decides how much of the fleet lands in the files:

  • Direct (default): every generative model in the project that calls tools, all in the picker, under erebine/<model-slug> ids.
  • Semantic router: one entry pointing at the semantic router, which scores the fleet per request.
  • Pinned: the resolved endpoint, pinned. One model.

A workspace with no advertised model that calls tools yields an MCP-only bundle: cline_mcp_settings.json and the rules file, no provider files, and Cline keeps whatever provider you already use. The README says so.

OpenAI Compatible fallback

On a build without a custom-provider registry, or an IDE that does not list erebine as a provider, take the same values through the settings UI: pick the OpenAI Compatible provider and fill in these fields.

FieldValue
Base URLhttps://api.erebine.ai/proj_ABC123/<workspace_id>/_direct/v1, the baseUrl from providers.json
API KeyThe apiKey from providers.json
Model IDThe model from providers.json, or any id listed in models.json
Custom HeadersX-Erebine-Augment-Corrective-Retries and X-Erebine-Augment-Max-Output-Tokens-Clamp, each with the value on
Context WindowThe model's maxInputTokens from models.json, or its contextWindow when it has none
Max Output TokensThe model's maxTokens from models.json
Image SupportOn when the model's capabilities include images, off otherwise. 4.x labels it "Supports Images".

Left empty, Context Window and Max Output Tokens fall back to Cline's defaults, which do not match the model.

Project Rules

.cline/rules/erebine.md carries the shared Erebine tool-use rules every other client receives through its own rules surface, plus a Cline addendum that spells out the tool naming, the prompt commands and the Plan-mode posture. Cline concatenates every .md file in .cline/rules/ into the system prompt as context, so the rules apply to every task in the project without replacing anything.

Without them the agent will sometimes ask you about workspace state instead of calling the Erebine tools to retrieve it.

The rules also ask the agent to sign each commit an Erebine endpoint generates with a Co-Authored-By: Erebine trailer. See Commit Attribution.

.cline/rules/ and .clinerules/. Cline reads workspace rules from both, in the IDE, Desktop and the CLI. The bundle uses .cline/rules/, the directory cline config edits; the VS Code Rules panel creates new workspace rules in .clinerules/. erebine.md works in either. A project that already keeps AGENTS.md can keep it: Cline reads that too, and the files stack rather than shadow each other.

Tools and Prompts

SDK-based Cline builds namespace MCP tools with the server name and sanitize the result to [A-Za-z0-9_-]: the server name, two underscores, then the tool name with dots replaced by underscores. Sanitizing changes every Erebine tool name, and when it does Cline appends an underscore and an eight-character hash it derives from the original dotted name, so every tool carries a suffix: erebine.intelligence.brief becomes erebine__erebine_intelligence_brief_fc26e278. Match a tool to the catalog by the erebine_<group>_<verb> segment between the double underscore and the hash.

The classic extension calls tools through use_mcp_tool instead, with server_name erebine and the dotted tool_name (erebine.intelligence.brief). The rules file documents both spellings, so the model reaches the catalog either way.

The IDE lists the six Erebine prompts as slash commands named /mcp:erebine:<prompt>: /mcp:erebine:session.init, /mcp:erebine:brief, /mcp:erebine:onboard, /mcp:erebine:save-this, /mcp:erebine:mcp-loop and /mcp:erebine:erepress. Resources are read through access_mcp_resource with a URI such as erebine://workspace/current/brief on builds that offer it. Both are documented on the general MCP integration page.

CLI Setup

The Cline CLI merges the MCP entry into its settings file itself. The shell expands $EREBINE_API_KEY before Cline sees it, so the file stores the key:

Shell
export EREBINE_API_KEY=<api_key> cline mcp add erebine https://api.erebine.ai/proj_ABC123/v1/mcp \ --transport streamableHttp \ --header "Authorization: Bearer $EREBINE_API_KEY" \ --header "X-Erebine-Workspace: <workspace_id>" \ --yes

cline mcp add adds one server and keeps every other one in the file. For the provider, merge models.json from the bundle (or copy it when you have none), then save the key and the model:

Shell
cline auth -p erebine -k "$EREBINE_API_KEY" -m erebine/<model-slug>

cline auth writes the key and model into providers.json and makes erebine the active provider. To use it for one run only, pass cline -P erebine -m erebine/<model-slug>.

erectl mcp setup --client cline --workspace <uuid> prints the same server entry with "Bearer ${env:EREBINE_API_KEY}" in place of the key. The IDE expands that form; the CLI does not, so for the CLI pass --inline-api-key <key>, or use cline mcp add as above. Merge the printed mcpServers.erebine key into an existing file rather than redirecting over it: the file holds every MCP server Cline knows about.

Pass --out-dir <dir> to also write providers.json, models.json and the rules file, built from the workspace's _direct models over the management API, exactly as the dashboard's Direct bundle carries them. Without --inline-api-key, providers.json carries no apiKey; run cline auth as above to store the key. --mcp-only keeps the model provider you already use.

Capability Matrix

What the bundle wires into Cline, and how:

SurfaceSupportedMechanism
Inference provideryesmodels.json plus providers.json, models that call tools
Plan/Act modelsyes (IDE)"Use different models for Plan and Act"; the CLI uses one model for both
MCP toolsyesNative MCP client, no bridge
Promptsyes (IDE)/mcp:erebine:<prompt> slash commands
Resourcespartialaccess_mcp_resource, on builds that offer it
Project rulesyes.cline/rules/erebine.md, read as context
Streaming transportyesNative streamable HTTP (type: streamableHttp)
OAuthnoBearer header from cline_mcp_settings.json
Sampling, elicitation, rootsnoThe client advertises no capabilities to the server

See the full per-client comparison in docs/mcp, Security.

Troubleshooting

The server shows as disconnected

Check type in the mcpServers.erebine entry. Cline defaults a URL entry with no type to legacy SSE, and the Erebine endpoint answers streamable HTTP, so the handshake never completes. Set "type": "streamableHttp" and restart Cline.

"Request timed out"

timeout is in seconds. A value copied from a millisecond-based config reads as either far too small or out of range: Cline clamps it to 1 to 3600. Long research and exec calls want a higher number, not a bigger unit.

Signed out of every provider after merging

providers.json failed validation, and Cline treats a file that fails its schema as empty. Restore your backup, then re-merge and check the two fields that most often break it: updatedAt must be an ISO-8601 datetime and baseUrl must be a full URL. The provider id must match ^[a-z0-9][a-z0-9-]*$.

The model is missing from the picker

Either models.json was not merged, or Cline has not restarted since. The custom-provider registry is read once at startup. Reload the IDE window or start a new CLI session. A model without tool calling is never registered; Cline cannot run it. On a build with no models.json support, use the OpenAI Compatible fallback.

401 Unauthorized on every tool call

The key in cline_mcp_settings.json is missing, malformed, or revoked. Each Cline download from the Client tab rotates your Cline key and revokes the previous one; other clients' keys are untouched. Re-download the bundle, or replace the Authorization header value with a key carrying the inference scope. The CLI sends a ${env:EREBINE_API_KEY} placeholder verbatim; re-add the server with cline mcp add and the key.

403 Forbidden with code scope_insufficient

The key authenticated but does not carry the inference scope the MCP surface requires. Mint a replacement with erectl keys --create --name "cline" --scopes inference.