Web2CLI

Turn recorded browser requests into login-aware CLI tools.

Web2CLI is a Chrome extension + CLI template that helps you — and your AI coding agent (e.g. DeepSeek Harness) — turn a website's authenticated API calls into a reusable command-line tool, without manually copying cookies.

中文说明见 README.zh-CN.md。

---

Why

Building a quick CLI on top of an internal web service usually means:

1. Open DevTools, copy a Cookie header by hand (and it silently expires later).
2. Copy each curl, guess which parameters matter.
3. Paste everything into a script and pray the auth keeps working.

Web2CLI automates the painful parts:

• Cookie sync — one click exports the current site's cookies (including httpOnly) to a fixed local file. Generated CLIs read that file at runtime, so when the login refreshes, your CLI keeps working with zero edits.
• Request recording — record real XHR/Fetch traffic (including POST bodies and response bodies) via the Chrome DevTools Protocol, then hand a clean curl/Markdown bundle to an AI agent that writes the CLI for you.

How it fits DeepSeek Harness (and other agents)

DeepSeek Harness (dsh) is a terminal agent harness ("everything is a plugin"). It cannot drive a browser. Web2CLI covers the browser side and hands the agent everything it needs:

 ┌───────────┐   record + sync   ┌────────────────────┐
 │  Browser   │ ───────────────▶ │  Web2CLI extension  │
 └───────────┘                    └─────────┬──────────┘
                                            │ cookie file + recorded requests
                                            ▼
                      ┌───────────────────────────────────────┐
                      │  AI agent (dsh / any) + this repo's    │
                      │  AGENTS.md guide + cli-template/       │
                      └─────────────────────┬─────────────────┘
                                            │ generates
                                            ▼
                              ┌──────────────────────────┐
                              │  your CLI (Python)        │
                              │  reads cookie file at run │
                              └──────────────────────────┘

Point your agent's workspace at this repo (or reference AGENTS.md) and ask it to generate a CLI from your recording — it follows the minimal-interface-set rules and the cookie-alignment contract automatically.

Repository layout

web2cli/
├── README.md               # this file
├── README.zh-CN.md         # 中文文档
├── AGENTS.md               # guide for AI agents: recording → CLI (read this, dsh!)
├── LICENSE                 # MIT
├── extension/              # Chrome MV3 extension (the browser side)
│   ├── manifest.json
│   ├── background.js       # service worker: cookie sync + CDP recording
│   ├── popup.html / popup.js
│   ├── records.html / records.js   # result page: select + copy curl/Markdown/JSON
│   └── README.md
└── cli-template/           # what the agent fills in to produce a CLI
    ├── cli_template.py     # CLI skeleton (runtime cookie loading, auth-expiry detection)
    └── read_cookie.py      # inspect synced cookie files

Install the extension

1. Open chrome://extensions.
2. Enable Developer mode (top-right).
3. Click Load unpacked and select the extension/ directory of this repo.
4. Pin the Web2CLI icon. The popup shows two sections: Cookie sync and Request recording.

After any code change, hit the reload icon on the Web2CLI card in chrome://extensions.

Usage

1. Sync cookies (login state)

1. Open the target site in the browser (you must be logged in).
2. Click the Web2CLI icon → Sync Cookie to local file.
3. Output: ~/Downloads/web2cli-cookies/{host}.json. The cookie_header field is a ready-to-use Cookie string.
4. Optional: tick Auto sync to rewrite the file whenever that site's login cookies change.

2. Record requests

1. Open the target page → popup → Start recording (the "debugging this browser" bar is normal).
2. Use the page normally; newly opened tabs are captured automatically.
3. Stop recording → Open results.
4. Click Smart preselect (minimal set) to auto-pick the relevant requests, adjust as needed, then Copy Markdown (for AI).

3. Generate the CLI

Paste the Markdown into your AI agent together with a one-line description, e.g.:

"Here are the recorded requests. Build me a CLI to query orders."

The agent follows AGENTS.md: it keeps only the minimal interface set (target action + its parameter-source queries), fills cli-template/cli_template.py, and verifies.

Cookie file format

~/Downloads/web2cli-cookies/{host}.json (format: "web2cli-cookie-v1"):

{
  "format": "web2cli-cookie-v1",
  "host": "example.com",
  "base_domain": "example.com",
  "updated_at": "2026-08-20T08:00:00.000Z",
  "cookie_count": 12,
  "cookie_header": "a=1; b=2; ...",      // paste-ready Cookie string
  "cookies": [ { "name": "a", "value": "1", "domain": ".example.com", "httpOnly": true } ]
}

Generated CLIs read cookie_header at runtime and apply browser-style domain filtering, so a stale/overly-broad file can't trigger 400 Request Header Or Cookie Too Large.

Security

• Cookie files are plaintext credentials — treat them like passwords. Never commit them to git or share them.
• CLIs must read cookies from the file at runtime; never hardcode cookie values.
• Write APIs (POST/PUT/DELETE) are never auto-executed by the agent — you run them yourself.

FAQ

Symptom	Fix
CLI says [cookie not synced]	Sync cookies for that host first (Usage §1).
400 Request Header Or Cookie Too Large	Use the latest extension (host-scoped filtering) and re-sync.
Redirected to / served a login page	Login session expired — log in again in the browser, then re-sync.
Missing POST body in recording	Wait for the request to finish before stopping the recording.
Blue "debugging this browser" bar	Required by Chrome during recording; cannot be removed.

License

MIT