cline-api

An OpenAI-compatible HTTP bridge for the Cline coding agent.

cline-api runs @cline/core in-process and exposes chat completions over HTTP. It supports regular JSON responses, SSE streaming, file attachments, and an optional agent mode with Cline's file and shell tools.

English | Русский | 简体中文 | Español

What it provides

• POST /v1/chat/completions with an OpenAI-style request and response shape
• Streaming completions using server-sent events
• Inline files, multipart uploads, and workspace file paths
• Text and image message content
• OAuth through an existing Cline login or direct API-key authentication
• Optional Cline tools with workspace-scoped request paths
• No runtime npm dependencies beyond the globally installed Cline package

The bridge targets chat-completion clients. OpenAI function calling is intentionally not emulated: Cline tools are a separate server-side agent capability.

Requirements

• Node.js 22 or newer
• Cline CLI installed globally
• An authenticated Cline account or a provider API key

npm install -g cline
cline auth

Quick start

git clone https://github.com/The2oser-dev/cline-api.git
cd cline-api
powershell -ExecutionPolicy Bypass -File start-api.ps1

The server listens on http://127.0.0.1:8080 by default.

curl.exe http://127.0.0.1:8080/health
curl.exe http://127.0.0.1:8080/v1/models

The default model is cline-free/glm-5.2. Availability and free-tier limits are controlled by Cline and may change.

Basic request

$body = @{ messages = @(@{ role = "user"; content = "Explain this repository in one sentence." }) } |
  ConvertTo-Json -Depth 5 -Compress
Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8080/v1/chat/completions `
  -ContentType "application/json; charset=utf-8" `
  -Body ([Text.Encoding]::UTF8.GetBytes($body))

With API authentication enabled:

$env:CLINE_API_AUTH_TOKEN="replace-with-a-long-random-token"
powershell -ExecutionPolicy Bypass -File start-api.ps1

Then, from another terminal:

$env:CLINE_API_AUTH_TOKEN="replace-with-a-long-random-token"
$body = @{ messages = @(@{ role = "user"; content = "Hello" }) } |
  ConvertTo-Json -Depth 5 -Compress
Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8080/v1/chat/completions `
  -Headers @{ Authorization = "Bearer $env:CLINE_API_AUTH_TOKEN" } `
  -ContentType "application/json; charset=utf-8" `
  -Body ([Text.Encoding]::UTF8.GetBytes($body))

Streaming

Set stream to true. Each response frame contains an OpenAI-style chat.completion.chunk; the stream ends with data: [DONE].

$body = @{ stream = $true; messages = @(@{ role = "user"; content = "Write two short sentences." }) } |
  ConvertTo-Json -Depth 5 -Compress
$file = [IO.Path]::GetTempFileName()
[IO.File]::WriteAllText($file, $body, [Text.UTF8Encoding]::new($false))
curl.exe -N http://127.0.0.1:8080/v1/chat/completions `
  -H "Content-Type: application/json" `
  --data-binary "@$file"
Remove-Item $file

Python client

Install the official OpenAI Python SDK:

python -m pip install openai

import os
from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8080/v1",
    api_key=os.environ.get("CLINE_API_AUTH_TOKEN", "local"),
)

response = client.chat.completions.create(
    model="cline-free/glm-5.2",
    messages=[{"role": "user", "content": "Hello"}],
)

print(response.choices[0].message.content)

See example.py for regular responses, files, workspace paths, and streaming.

Files

Inline content:

{
  "message": "Review this file",
  "files": [
    { "name": "example.py", "content": "print('hello')" }
  ]
}

Existing files inside the configured workspace:

{
  "message": "Summarize this file",
  "file_paths": ["server.mjs"]
}

Multipart upload:

curl.exe -s http://127.0.0.1:8080/v1/chat/completions `
  -F "message=Review this file" `
  -F "files=@C:\path\to\example.py"

Temporary uploads are removed after the request finishes.

Agent tools

Tools are disabled by default. Enable them only for trusted clients and set a dedicated workspace root:

$env:CLINE_API_ENABLE_TOOLS="1"
$env:CLINE_API_WORKSPACE_ROOT="C:\work\project"
powershell -ExecutionPolicy Bypass -File start-api.ps1

cwd, file_paths, and files[].path cannot leave the workspace root. This restriction does not turn the agent into a security sandbox: shell commands still run as the server's operating-system user.

Set agent to false in an individual request to disable tools for that request. A request cannot enable tools if the server has them disabled.

Request fields

Field	Description
model	Model allowed by CLINE_API_ALLOWED_MODELS
messages	OpenAI-style chat messages
message	Shorthand for one user message
system	Explicit system prompt
prompt	Raw Cline prompt instead of translated messages
stream	Enable SSE streaming
files	Inline files or workspace file objects
file_paths	Existing paths inside the workspace
cwd	Session directory inside the workspace
agent	Disable server-side Cline tools for this request
mode	act or plan
temperature	Number from 0 to 2
max_tokens	Maximum tokens per turn
thinking	Enable model reasoning when supported
thinking_budget_tokens	Reasoning-token budget
timeout_ms	Request timeout, capped by the server maximum

Configuration

Environment variable	Default	Purpose
CLINE_API_HOST	127.0.0.1	Listening address
CLINE_API_PORT	8080	Listening port
CLINE_API_AUTH_TOKEN	empty	Bearer token for completion requests
CLINE_AUTH	oauth	oauth or key
CLINE_API_KEY	empty	Provider key used when CLINE_AUTH=key
CLINE_PROVIDER	cline	Cline provider ID
CLINE_MODEL	cline-free/glm-5.2	Default model
CLINE_API_ALLOWED_MODELS	default model	Comma-separated model allowlist
CLINE_API_WORKSPACE_ROOT	repository directory	Allowed filesystem root
CLINE_API_ENABLE_TOOLS	0	Set to 1 to enable Cline tools
CLINE_API_MAX_CONCURRENT	2	Maximum active agent requests
CLINE_API_TIMEOUT_MS	600000	Maximum session duration
CLINE_API_MAX_BODY_BYTES	67108864	Maximum request-body size
CLINE_API_ALLOWED_ORIGINS	empty	Comma-separated browser origins
CLINE_API_ALLOW_REMOTE_IMAGES	0	Enable public IPv4 image URLs
CLINE_API_MAX_IMAGE_BYTES	16777216	Maximum downloaded image size
CLINE_API_IMAGE_TIMEOUT_MS	30000	Remote image timeout
CLINE_API_ALLOW_REMOTE	0	Permit a non-loopback bind
CLINE_CORE_INDEX	auto-detected	Explicit path to @cline/core/dist/index.js

Security model

• Keep the server on loopback unless remote access is required.
• Always set CLINE_API_AUTH_TOKEN for shared machines or remote use.
• A non-loopback bind requires both CLINE_API_ALLOW_REMOTE=1 and an auth token.
• The built-in server uses plain HTTP. Put it behind a TLS reverse proxy for remote access.
• Browser access is denied unless the origin is listed in CLINE_API_ALLOWED_ORIGINS.
• Remote image downloads are disabled by default and restricted to public IPv4 addresses when enabled.
• Model selection, timeouts, body size, image size, and concurrency are bounded by server policy.
• Tool-enabled requests have the privileges of the account running the server.

Authentication modes

OAuth mode uses the account already configured by Cline. Provider settings are copied into an isolated data directory under ~/.cline/cline-api-data.

$env:CLINE_AUTH="oauth"

API-key mode passes CLINE_API_KEY to Cline:

$env:CLINE_AUTH="key"
$env:CLINE_API_KEY="your-provider-key"
$env:CLINE_PROVIDER="provider-id"
$env:CLINE_MODEL="model-id"
$env:CLINE_API_ALLOWED_MODELS=$env:CLINE_MODEL

Tests

npm run check

The automated suite validates syntax, authentication order, CORS, request validation, workspace boundaries, temporary-file cleanup, and remote-image SSRF protection without calling a model.

Live checks are available separately and may consume provider quota:

python smoke_utf8.py
python smoke_stream.py

Compatibility notes

• This is a focused bridge, not a complete implementation of the OpenAI API.
• Function tools and tool_calls are not supported.
• Usage accounting is currently returned as null.
• Streaming errors are sent as an SSE chunk with an error object before [DONE].
• Available model IDs and free-tier rules come from Cline and can change independently of this project.

Project layout

server.mjs           HTTP server and Cline integration
start-api.ps1        Windows launcher
example.py           OpenAI Python SDK examples
smoke_utf8.py        Live UTF-8 and attachment check
smoke_stream.py      Live SSE check
test/server.test.mjs Offline HTTP boundary tests

License

MIT