pi-clinepass-auto

English · 简体中文

Use your Cline Pass subscription inside pi: the ClinePass models, billed usage as the server reports it, and web search / page fetching on the same account — all without a separate API key.

pi install npm:pi-clinepass-auto
/login        # choose ClinePass

• Live model catalog — new ClinePass models appear without a package update.
• Server-truth usage meter — the footer shows what Cline actually billed.
• Web tools — web_search and web_fetch, billed to the same subscription.
• Upstream channels — see which channel serves a model, and set it when the gateway allows it.
• Zero configuration — reuses an existing Cline CLI login if you have one.

Quick start

1. Install

pi install npm:pi-clinepass-auto                    # from npm
pi install git:github.com/zhangweiii/pi-clinepass-auto   # from git
pi install ./pi-clinepass-auto                      # from a local checkout
pi -e ./pi-clinepass-auto                           # try it for one invocation

The provider id is clinepass — the same id used by pi-clinepass and pi-clinepass-provider. Install only one of them, otherwise the provider is registered twice.

2. Sign in

Run /login inside pi and pick ClinePass. The login flow:

1. reuses an existing Cline CLI login (~/.cline/data/settings/providers.json) when present — no copy/paste needed;
2. otherwise asks you to paste a ClinePass API key (app.cline.bot → Settings → API Keys).

A static key also works without /login:

export CLINE_API_KEY="your_key_here"

Browser sign-in is intentionally not reimplemented here. If you prefer it, run cline auth first and then /login in pi to import that session.

3. Pick a model

pi --list-models clinepass                  # everything the account can see
pi --model clinepass/cline-pass/glm-5.3     # start with a specific model

Or just run pi and use /model to pick from the list.

4. Check usage

While a clinepass model is active, the footer shows what Cline billed:

Cline: $0.01 turn · $0.18 session ($0.05 search) · 5h 12% · 7d 34% · 30d 13% of $50

turn is the cost of the most recent model request (pi's own definition of a turn), session is everything adopted in this session — including web searches, shown separately in parentheses — and the percentages are the plan windows Cline reports. Run /cline-usage (alias /usage) for the full report, or /clinepass for the menu.

What you get

Models

The provider is registered as clinepass; model ids look like cline-pass/glm-5.3 and cline-free/mimo-v2.6-flash.

pi --list-models clinepass
pi --model clinepass/cline-pass/deepseek-v4.1-flash

• New and retired models appear on their own. Availability comes from Cline's recommended-models endpoint, so a model that Cline retires disappears from the list and a newly launched one shows up on the next refresh — no package update involved.
• Metadata (price, context window, max output, reasoning options) comes from models.dev. Models that models.dev does not know yet still register, with conservative defaults and no invented prices.
• Refresh on demand with /clinepass → Refresh model catalog, which re-registers models immediately without restarting pi.
• Offline-safe: the last cached catalog (or the bundled seed on a first run) is used when the network is unavailable. The provider is never empty.

Free-tier models (cline-free/*, stealth/*) are hidden by default. Cline's documentation is explicit: "Free model usage is not supported through the Cline API. Free models are only available in the Cline IDE Extension and CLI", and its gateway answers them with 403 … only available via Cline product surfaces. /clinepass → Show free models registers them anyway (labelled (Cline Free, IDE/CLI only)) for inspection; a call that still fails is explained in plain language instead of surfacing the raw 403 JSON.

Usage meter and plan limits

Cline bills the subscription server-side, so this extension does not estimate token costs. It reads the same /usages feed the Cline apps use and adopts the records Cline created for your turns.

Cline: $0.01 turn · $0.18 session ($0.05 search) · 5h 12% · 7d 34% · 30d 13% of $50

Notes:

• The meter appears only while a clinepass model is active and can be turned off with /clinepass → Hide footer meter (remembered across sessions).
• Costs are persisted as session entries, so the session total survives pi --resume.
• Web search records are only counted when they fall inside a time window in which this extension actually ran a web_search. Searches made by another Cline client on the same account never leak into the figure.
• Cline's billing pipeline flushes asynchronously. A record that does not show up within ~12 s is not counted; the meter simply keeps its last known value.
• The text is plain (no box-drawing frame) so footer extensions such as pi-status-line can style it like their own widgets — the ext-status widget dims it to match the rest of the status line.

/cline-usage (alias /usage) prints the report without using the footer:

ClinePass — Cline Pass (Annual)
5h   [██░░░░░░░░░░]  12% of $10  resets 13:00
7d   [████░░░░░░░░]  34% of $25  resets 00:41
30d  [█░░░░░░░░░░░]   5% of $50  resets 10-21 00:41

Session  $0.2012 across 12 adopted turns
Search   4 web searches ($0.028, included above)
Catalog  17 models (network, updated 9/27 11:02)

/clinepass opens a menu:

Web search and page fetching

Two tools are registered, both usable by any model — the credential, not the active model, decides what is available.

web_search

web_search(query, allowed_domains?, blocked_domains?, fetch_top?)

• The endpoint returns titles and URLs only — no snippets. The tool appends a reminder telling the model to open a page with web_fetch before answering.
• allowed_domains / blocked_domains narrow the search; they are mutually exclusive (the API rejects a request with both).
• fetch_top: 0–3 also fetches the full text of the top results in the same call. It is free but adds latency and context; each page is truncated to a share of the 50 KB result budget. Prefer leaving it at 0 and letting the model choose pages after seeing all ten results.
• Because one search costs roughly as much as ten model requests, the tool guides the model not to repeat the same query.

web_fetch

web_fetch(url, prompt?)

• Fetches the URL over plain HTTP (browser-ish user agent, 30 s timeout, 5 MB response cap, redirects followed) and converts HTML to text with the same dependency-free extractor Cline's fetch_web_content uses. JSON is pretty-printed; other content types are returned verbatim.
• Output is truncated to pi's standard limit (50 KB / 2000 lines). When truncated, the full text is written to a temp file that the model can read.
• prompt is an optional note describing what to extract; it is appended to the returned text as Extract focus: ….

Turning them off

web_search is activated only while a Cline credential exists. Without one, the tool is neither sent to the provider nor mentioned in the system prompt — the model does not know it exists. Signing in mid-session (for example with /login) activates it immediately. Tools excluded with -t / -xt are never re-enabled by the extension; the /clinepass toggle only restores what it hid itself.

Upstream channels

Every ClinePass model is served by one of several upstream channels (baseten, fireworks, deepinfra, …) and Cline's gateway picks which one. The gateway reports its choice in every response, so the plugin can show it — and, where the gateway allows it, change it.

/cline-route                      # the current model
/cline-route cline-pass/glm-5.3   # a specific model
/clinepass → Upstream channel…    # pick a model, then set / clear / re-check

The panel answers one question first — can this model be set right now? — and only then shows the details:

Upstream  cline-pass/minimax-m3
Can set   yes — verified with a pinned probe
Serving   minimax  0.8s
Channels  minimax · nebius · gmicloud
Checked   12:41 · 2 probes ≈ $0.0001

• How Can set is decided. The plugin sends a tiny probe pinned to a channel other than the one serving the model. If the answer comes back on the requested channel, a preference takes effect. If not, the panel says no right now and explains the observed evidence on a Why line instead of guessing whether the gateway forbids it or is holding on to its channel.
• Not every model allows it. Routing belongs to Cline's gateway, and it keeps some models on its own route — for example cline-pass/deepseek-v4.1-flash, which is served by the vendor's own endpoint. Those report no right now; the plugin never pretends otherwise.
• A preference is sent with every request, so it keeps applying even after the gateway's sticky affinity drifts away. Saving one that is not effective yet is fine: the plugin re-checks when a session starts and tells you when it starts working.
• Cost. One check is two (sometimes three) tiny probes with reasoning disabled: about two seconds and roughly $0.0001 of plan quota. Results are cached for ten minutes, so re-opening the panel inside that window is free.
• The /cline-usage report prints the cached result as a Route line.
• Preferences live in clinepass-auto-prefs.json under routes.

Commands and settings

Slash commands

Environment variables

Files written

Troubleshooting

How it works

The short version, for people who want to know what is happening underneath.

Catalog discovery

Cline recommended-models (/api/v1/ai/cline/recommended-models)
        │  "which cline-pass/* and free models exist right now"
        ▼
models.dev (api.json → provider "cline-pass")
        │  "price, context window, max output, reasoning options"
        ▼
merged catalog ──► pi provider models
        │
        ├─ on-disk cache  <agent dir>/clinepass-auto-catalog.json (6 h TTL)
        └─ bundled seed   (first run without network)

Availability always comes from Cline, so retired models disappear and new ones appear on the next refresh. Metadata comes from models.dev, which only knows the paid lineup; unknown models still register with conservative defaults and no invented prices. Thinking levels are derived from models.dev reasoning_options (effort values map 1:1 to pi levels; off maps to none only when the provider advertises it) — without metadata a conservative default map is used instead of guessing.

Credentials

Credentials are resolved in this order: CLINE_API_KEY → pi's credential store (<agent dir>/auth.json, written by /login) → the Cline CLI login (~/.cline/data/settings/providers.json).

ClinePass access tokens are short-lived WorkOS JWTs and are refreshed through Cline's /api/v1/auth/refresh. Rotated refresh tokens are written back to the store they came from with a compare-and-swap, so pi and the Cline CLI can both keep refreshing without clobbering each other.

Usage accounting

After every assistant message the extension polls /usages for the record of that model request and adopts it into the session meter. The poll runs in the background and never gates the agent loop; adoption is serialized so overlapping tool loops cannot adopt a record twice.

Web search records share the same feed (operation: "web_search", searchProviderName: "exa"). They are adopted through the same polling loop and folded into the session total; the turn figure keeps its original meaning of “last model request”. To avoid stealing another Cline client's spending, a search record is only adopted when its timestamp falls inside a window in which this extension actually ran a web_search (±60 s for clock/queue spread).

Web tool internals

web_search calls POST {CLINE_API_BASE}/api/v1/search/websearch with the account bearer token and retries once with a refreshed token on 401.

web_fetch never touches Cline's API: it is a local GET plus a small HTML-to-text pass (strip scripts/styles/comments, turn block tags into line breaks, drop tags, decode common and numeric entities, collapse whitespace). This is deliberately the same approach Cline's fetch_web_content uses, with one fix: Cline's version collapses the line breaks it inserts, producing a single very long line.

Development

npm install           # dev dependencies: typescript, @types/node, typebox
npm test              # node --test, no build step
npm run typecheck     # tsc --noEmit
npm run generate-seed # regenerate src/seed.ts from the live sources

Layout:

The test suite is node --test over TypeScript (Node 22.19+ strips types natively), so there is no build step. CI runs npm ci, the type check, and the tests on every push and pull request.

Releasing

Releases are tag driven and run in GitHub Actions (.github/workflows/release.yml):

The workflow refuses to publish when the tag does not match the version in package.json, runs the test suite, publishes with provenance, and creates a GitHub release with generated notes (marked prerelease for -beta / -rc versions).

Authentication: npm Trusted Publishing (no tokens)

npm removed classic/Automation tokens in November 2025 and retires direct-publish granular tokens in January 2027, so this repository uses Trusted Publishing (OIDC) only — there is no NPM_TOKEN secret anywhere.

One-time bootstrap. A trusted publisher can only be configured for a package that already exists on npm, so the first version has to be published by hand:

npm login
npm publish --access public   # prompts for your 2FA code

Then, on npmjs.com → the package → Settings:

1. Trusted publishing → add GitHub Actions with organization/user zhangweiii, repository pi-clinepass-auto, and workflow filename release.yml. Leave npm publish unchecked — npm's own recommendation is stage-only publishing, so CI can only stage a release.
2. Publishing access → Require two-factor authentication and disallow tokens — after this, only the trusted workflow can stage a release.

Every release is then two steps: CI stages it, you approve it.

npm run release:beta        # stages 0.2.0-beta.0 through GitHub Actions
npm stage list              # find the stage id
npm stage approve <id>      # prompts for your 2FA code

The Actions run summary prints the same instructions. Provenance attestations are generated automatically for OIDC publishes from a public repository.

If you would rather skip the approval step, check npm publish in the trusted-publisher configuration and change the workflow's npm stage publish back to npm publish. npm considers that weaker: a compromised workflow could publish without a human in the loop.

Install a prerelease with a pinned dist-tag:

pi install npm:pi-clinepass-auto@beta

Publishing with the pi-package keyword is all that is needed for the Pi package gallery to pick the release up; optional pi.image / pi.video fields add gallery previews.

Limits and caveats

• Undocumented APIs. The catalog, usage, plan, and search endpoints are Cline APIs that are not publicly documented and may change. Parsing is defensive and unit-tested; web_search fails loudly rather than returning invented results.
• Search shape. POST /api/v1/search/websearch is Exa-backed, ignores result-count parameters, and returns ten title/URL pairs with no snippets. It currently bills about $0.007 per request.
• Search attribution relies on time windows (±60 s). A search made by another Cline client inside that window can be attributed to this session.
• HTML extraction uses the regex extractor described above, so JavaScript-rendered pages come back mostly empty and navigation chrome is not stripped. web_fetch never touches Cline's API.
• Billing latency. A record that Cline has not flushed within ~12 s is not counted. In --print mode the process can exit before the final record is adopted, so the footer in an interactive session is the accurate view.
• Upstream routing belongs to the gateway. A channel preference is a request, not a command: some models (for example cline-pass/deepseek-v4.1-flash) are served from a route the gateway will not hand over. The plugin reports that as no right now with the observed evidence rather than pretending the preference worked.
• Free tier is hidden by default and blocked on the API path (see Models); /clinepass → Show free models registers it anyway so it can be listed.
• This package is not affiliated with Cline, pi, or models.dev.

License

MIT