--- name: sigcli description: Guide Claude to use SigCLI correctly — check auth, login, get credentials, configure providers, and onboard new websites. Trigger when using sig commands, editing ~/.sig/config.yaml, or needing authenticated API access. --- # SigCLI Reference for using SigCLI correctly. Prevents common mistakes like inventing flags, using redacted output, or misconfiguring providers. ## Constraints These are the most common mistakes. Read them FIRST. 1. **`sig get` MUST use `--no-redaction` to get usable values.** Without it, output is `****`. This is the #1 mistake. 2. **Never invent commands.** The ONLY commands are: `init`, `doctor`, `login`, `logout`, `get`, `request`, `status`, `providers`, `rename`, `remove`, `remote`, `sync`, `watch`, `proxy`, `run`, `completion`. 3. **Never invent flags.** See Command Reference below for exact flags per command. 4. **Never invent config fields.** There is NO `requiredCookies`, `loginUrl`, `cookies`, `headers`, `authUrl`, `token`, `credentials`, or `session` field. See Provider Config Schema for the exact list. 5. **`sig login` two forms:** - `sig login ` — provider already configured in config.yaml - `sig login https://example.com` — auto-provision (creates provider automatically). Use `--as` for a meaningful name: `sig login https://example.com --as example` 6. **`sig run` output is redacted.** It injects `SIG__` env vars into the child process, but redacts them in stdout. Use `env | grep SIG_` inside the child to discover var names. 7. **`sig get --format` only accepts:** `json`, `header`, `value`. Not `cookie-jar`, `env`, `raw`, etc. 8. **Provider config `extract` and `apply` are ARRAYS** (list of objects), not single objects. 9. **Don't modify existing provider configs** unless explicitly asked by the user. ## Command Reference | Command | Usage | Key Flags | | ------------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `init` | `sig init` | `--remote`, `--yes`, `--force` | | `doctor` | `sig doctor` | — | | `login` | `sig login ` | `--as `, `--strategy oauth2`, `--token-url`, `--client-id`, `--client-secret`, `--scope`, `--mode auto\|headless\|visible`, `--network-proxy` | | `logout` | `sig logout [provider]` | — | | `get` | `sig get ` | `--format json\|header\|value`, `--no-redaction` | | `request` | `sig request ` | `--method`, `--body`, `--header "K: V"`, `--format json\|body\|headers` | | `status` | `sig status [provider]` | `--format json\|yaml\|table\|plain` | | `providers` | `sig providers` | `--format json\|yaml\|table\|plain` | | `rename` | `sig rename ` | — | | `remove` | `sig remove ` | `--keep-config`, `--force` | | `remote` | `sig remote add\|remove\|list` | **add:** ` ` `--user`, `--path`, `--ssh-key` | | `sync` | `sig sync push\|pull [remote]` | `--provider`, `--force` | | `watch` | `sig watch add\|remove\|set-interval` | **add:** `` `--auto-sync` | | `proxy` | `sig proxy start\|stop\|status\|trust` | **start:** `--port` | | `run` | `sig run [providers...] -- ` | `--expand-cookies`, `--mount `, `--mount-format env\|json` | | `completion` | `sig completion ` | bash, zsh, fish | Global: `--verbose`, `--help` ## Common Patterns ### Check if auth is valid ```bash sig status # Look for "valid": true in JSON output ``` ### Get credentials for use ```bash # JSON with headers (most common) sig get --no-redaction # Just the cookie/token string sig get --no-redaction --format value # Inject into another command sig run -- ``` ### Login when expired ```bash sig login # auto mode (headless first, then visible) sig login --mode visible # force open browser — USE THIS for first-time public site login ``` Note: `sig login` reuses existing valid credentials if available — it only re-authenticates when credentials are expired or missing. ### Make an authenticated request ```bash sig request https://api.example.com/endpoint --method GET ``` ## Onboarding a New Provider When the user wants to authenticate to a new website, follow these steps: ### Step 1: Try auto-provision first ```bash sig login https://example.com --as my-site ``` This auto-provisions a basic config (domains, entryUrl, extract all cookies, apply as Cookie header). **If it works** (you get a chance to log in, `sig status my-site` shows `valid: true`) → done. **If the browser closes immediately without letting you log in** — this happens on public sites (Weibo, Reddit, X, Bilibili) where the homepage returns 200 without auth. sigcli thinks it's already authenticated because there's no redirect. **Fix:** Add a `validateUrl` to the auto-provisioned config. Don't rewrite the config — just add the one field: ```bash # Check what was auto-provisioned grep -A15 "my-site:" ~/.sig/config.yaml ``` Edit `~/.sig/config.yaml` and add a `validateUrl` under the provider — a URL that redirects or returns 401 when not logged in: ```yaml my-site: domains: - example.com entryUrl: https://example.com/ validateUrl: https://example.com/notifications # ADD THIS strategy: browser ... ``` Then login again: ```bash sig login my-site ``` Now sigcli keeps the browser open until validateUrl confirms you're authenticated. Verify after login: ```bash sig status my-site # should show valid: true sig request # should return authenticated response (not redirect/401) ``` ### Step 2: Figure out validateUrl or validateRule **validateUrl** — an endpoint that returns non-2xx (or redirects) when NOT logged in: - Check if the site has `/api/me`, `/api/user`, `/notifications`, `/rest/auth/1/session` - The URL must return 2xx ONLY when authenticated ```yaml validateUrl: https://example.com/api/me ``` **validateRule** — when the endpoint always returns 200 but body differs: - Use a JS expression that evaluates to truthy when authenticated - Available variables in the sandbox: - `res.status` — HTTP status code (number) - `res.body` — parsed JSON (if response is valid JSON) or raw string - `res.headers` — object (e.g. `{ location: "..." }`) - The expression is wrapped in `(...)` and evaluated — must return truthy for "authenticated" - Common pitfall: `res.body && res.body.name` fails because empty objects `{}` are truthy. Be specific about what field proves authentication. ```yaml validateUrl: https://example.com/api/me validateRule: 'res.body.name !== undefined' ``` More examples: ```yaml # Douyin: API returns {status_code: 0} when authenticated validateRule: "res.body.status_code === 0" # Site returns {logged_in: true/false} validateRule: "res.body.logged_in === true" # Reddit /api/me.json: returns {} when not logged in, {name: "user"} when logged in validateRule: "typeof res.body.name === 'string'" ``` **How to discover validateUrl and validateRule:** **Prerequisites:** You should know at least one authenticated API endpoint of the target site (e.g. from docs, DevTools network tab, or common patterns). **Step 1: Login first (auto-provision handles basics)** ```bash sig login https://new-website.com --as new-site ``` **Step 2: Verify with a known API** ```bash sig request https://new-website.com/my/api ``` If this works (returns authenticated data), you have a good `validateUrl` candidate. Add it to the config. **Step 3: If `sig request` fails, find a suitable validateUrl** A good validateUrl must be: - **GET** method (validation only does GET) - **Callable with just the `apply` rules** — sigcli builds the request using your `extract` + `apply` config. If the API needs headers beyond Cookie (e.g. CSRF token), those must be in your `extract`/`apply` rules too. - **Distinguishes authenticated from unauthenticated** — the validation logic is: How sigcli decides "authenticated" (in order): 1. If `validateRule` exists → evaluate it (overrides everything below) 2. Status 401/403/406/429 → **invalid** 3. Status 3xx (redirect): - With explicit `validateUrl` → **any redirect = invalid** (strict) - Without `validateUrl` (entryUrl fallback) → only invalid if redirect goes to `/login`, `/signin`, `/auth`, `/sso` 4. Body < 4KB with JS redirect (`window.location=`, ``) → **invalid** 5. Otherwise → **valid** **Best validateUrl candidates** (in order of preference): 1. A page that **redirects to login** when unauthenticated — e.g. `/notifications`, `/settings`, `/account`, `/prefs/friends`. This is the cleanest: any 3xx = invalid. 2. An API that **returns 401/403** when unauthenticated — e.g. `/api/me`, `/api/v4/me`, `/voyager/api/me`. 3. An API that returns 200 always but **different body** — needs `validateRule` (last resort). Common patterns that work as validateUrl: | Pattern | Why it works | |---------|-------------| | `/notifications` | Redirects to login without auth (V2EX, Xiaohongshu) | | `/account`, `/settings`, `/prefs/friends` | Redirects to login without auth (YouTube, Reddit) | | `/api/me`, `/api/v4/me`, `/voyager/api/me` | Returns 401 without auth (Zhihu, LinkedIn) | | `/i/api/2/notifications/all.json` | Returns 401/403 without auth (X — but needs csrf header) | If the API needs extra headers (e.g. CSRF token), extract them: ```yaml extract: - from: cookies as: cookie match: '*' - from: cookies as: csrf_token match: 'csrf_token_cookie_name' apply: - in: header name: Cookie value: '${cookie}' - in: header name: x-csrf-token value: '${csrf_token}' ``` Some APIs need a hardcoded app-level token (e.g. X's public Bearer token): ```yaml apply: - in: header name: authorization value: 'Bearer AAAAAA...' # hardcoded public app token ``` **Step 4: If validateUrl always returns 200 (rare), add validateRule** This only happens when the endpoint returns 200 for both authenticated and unauthenticated but with different body content. Compare: ```bash # With auth sig request https://new-website.com/api/check # Without auth (raw curl) curl https://new-website.com/api/check ``` Write a rule based on the difference. The rule sandbox has: - `res.status` — HTTP status (number) - `res.body` — auto-parsed JSON if valid, otherwise raw string - `res.headers` — response headers object ```yaml # Douyin: returns {status_code: 0} when authenticated, {status_code: -1} otherwise validateRule: "res.body.status_code === 0" # Reddit /api/me.json: returns {} when not logged in, {name: "user"} when logged in validateRule: "typeof res.body.name === 'string'" ``` Common pitfall: `res.body && res.body.name` — empty objects `{}` are truthy! Always check a specific field value. ### Step 3: Handle special extraction **Extract specific cookies** (when you need individual values): ```yaml extract: - from: cookies as: cookie match: '*' # full cookie string - from: cookies as: csrf_token match: 'csrf_token' # single cookie by name ``` **Extract from localStorage** (for SPA tokens): ```yaml extract: - from: localStorage as: access_token match: 'auth_key_pattern' jsonPath: token # if the value is JSON, extract a field ``` ### Step 4: Test ```bash sig login my-provider # opens browser, log in sig status my-provider # should show valid: true sig get my-provider --no-redaction # should show actual credentials ``` If `sig status` shows `valid: false` after login: - The `validateUrl` is wrong (try a different endpoint) - Or add `validateRule` if the endpoint returns 200 regardless Debug with: `sig login my-provider --mode visible --verbose` ## Provider Config Schema ### Valid top-level fields for a provider ```yaml my-provider: name: 'Display Name' # optional domains: [example.com] # required: list of domains entryUrl: https://example.com/ # required for browser/prompt; optional for oauth2 strategy: browser # required: browser | prompt | oauth2 ttl: 2h # optional: credential lifetime validateUrl: https://... # optional: URL to check auth (must 401/403 when unauthenticated) validateRule: 'res.body.ok' # optional: JS expression when validateUrl returns 200 regardless networkProxy: socks5://... # optional: proxy for this provider loginMode: visible # optional: auto | headless | visible loginUrlPatterns: [/login, /auth] # optional: URL substrings to detect login pages extract: [...] # required for browser/prompt: what to capture apply: [...] # required: how to use captured values oauth2: # only for strategy: oauth2 tokenUrl: https://... scopes: ['scope1', 'scope2'] ``` Note: `headlessTimeout` and `visibleTimeout` are browser-level settings (under `browser:` in config root), NOT provider-level. ### Fields that DO NOT EXIST (never use these) `required`, `cookiePaths`, `requiredCookies`, `cookies`, `headers`, `loginUrl`, `authUrl`, `token`, `credentials`, `session`, `headlessTimeout`, `visibleTimeout`, `waitUntil` ## Troubleshooting | Symptom | Cause | Fix | | ----------------------------- | ---------------------------- | ------------------------------------------- | | `sig get` returns `****` | Missing `--no-redaction` | Add `--no-redaction` flag | | `valid: false` after login | Wrong/missing validateUrl | Find an API endpoint that 401s without auth | | `configured: false` | Provider not in config.yaml | Add provider config first, then login | | Browser opens but login fails | Site needs visible mode | Use `--mode visible` | | `sig run` env vars empty | Provider credentials expired | Run `sig login ` first | | `command not found: sig` | Not installed globally | `npm install -g @sigcli/cli` | ## Self-Test ```bash # 1. sig is installed sig --help 2>&1 | head -1 # Expected: "sig — authenticate once, use everywhere" # 2. Config exists cat ~/.sig/config.yaml | head -3 # Expected: "version: 2" or similar # 3. Check a provider status sig status 2>&1 | head -5 ```