How the Agent-Reach Configure Command Handles Different Cookie Formats: A Complete Guide

The agent-reach configure command normalizes three distinct cookie input styles—space-separated tokens, JSON payloads, and header strings—before storing them securely in the user-wide configuration directory ~/.agent-reach.

The configure subcommand in Agent-Reach serves as the primary CLI entry point for authenticating with platforms like Twitter, XiaoHongShu, Xueqiu, and Bilibili. Understanding how the configure command handles different cookie formats ensures you can supply credentials correctly regardless of whether you have browser devtools data, exported JSON, or simple copy-pasted headers.

Supported Cookie Input Formats

Twitter: Space-Separated Values or Header Strings

For Twitter authentication, the system accepts two distinct input patterns through the twitter-cookies subcommand. The helper function _parse_twitter_cookie_input in agent_reach/cli.py implements a fallback parsing strategy:

1. Whitespace split attempt: If you provide two space-separated values (e.g., auth_token_value ct0_value), the function splits on whitespace and assigns the first token to auth_token and the second to ct0.
2. Regex extraction fallback: If the whitespace split produces anything other than exactly two parts, the code falls back to a regular-expression scan that extracts auth_token and ct0 values from a standard "key=value; ..." header format.

Both branches validate that the required keys are present and raise clear CLI errors with usage hints if parsing fails. The extracted values are stored in the YAML configuration under the keys twitter_auth_token and twitter_ct0.

# Method 1: Space-separated tokens

agent-reach configure twitter-cookies abcdef123 ghijkl456

# Method 2: Full cookie header string

agent-reach configure twitter-cookies "auth_token=abcdef123; ct0=ghijkl456"

XiaoHongShu: JSON Arrays or Raw Headers

XiaoHongShu configuration supports platform-specific cookie extraction via the _configure_xhs_cookies function in agent_reach/cli.py. This handler recognizes two input types:

• JSON payload: A JSON array or object describing cookies (e.g., [{"name":"web_session","value":"xyz"}])
• Raw header string: A semicolon-delimited cookie header (e.g., "web_session=xyz; other=123")

The implementation attempts json.loads first. If successful, the JSON writes directly to ~/.agent-reach/xhs-cookies.json. If JSON parsing fails, the string splits on ; and each name=value pair converts into a JSON object before storage.

Security enforcement occurs through _owner_only and _owner_only_dir helpers (verified in tests/test_cookie_extract_perms.py), which tighten file permissions to 0o600 and the parent directory to 0o700 before writing.

# Method 1: JSON array (preserved as-is)

agent-reach configure xhs-cookies '[{"name":"web_session","value":"secret"}]'

# Method 2: Header string (converted to JSON internally)

agent-reach configure xhs-cookies "web_session=secret; other=val"

Other Platforms: Direct Header Forwarding

Platforms like Xueqiu and Bilibili use a generic manual configuration path within cli._cmd_configure. When you run agent-reach configure xueqiu-cookies or bilibili-cookies, the command forwards the raw cookie header string directly to config.set(...).

Channel-specific extraction logic in agent_reach/channels/xueqiu.py and agent_reach/channels/bilibili.py later parses these stored strings at runtime. This architecture keeps the CLI layer agnostic while allowing each channel to implement its own cookie validation logic.

# Direct header string storage

agent-reach configure bilibili-cookies "SESSDATA=abc; bili_jct=def"

Automatic Browser Extraction

The --from-browser flag triggers automatic cookie harvesting via configure_from_browser in agent_reach/cookie_extract.py. This routine reads authentication data from Chrome, Firefox, or other supported browsers and builds a dictionary mapping platforms to cookie strings.

Rather than creating a separate storage path, the extraction output feeds into the same config.set logic used for manual entries. This ensures uniform storage regardless of whether cookies come from user input or browser introspection.

# Extract all supported platform cookies from Chrome

agent-reach configure --from-browser chrome

Security Implementation and File Permissions

When writing sensitive cookie data—particularly for XiaoHongShu—the CLI enforces strict filesystem permissions. As implemented in agent_reach/cli.py and verified by test_configure_xhs_cookies_tightens_local_fallback_file in tests/test_cookie_extract_perms.py:

• Cookie files receive chmod 0o600 (owner read/write only)
• The configuration directory (~/.agent-reach) receives chmod 0o700 (owner full control only)

This permission model prevents other system users from accessing authentication tokens, satisfying security requirements for credentials stored in the user-wide configuration directory.

Practical Implementation Flow

Regardless of input format, the configure command normalizes data into uniform storage:

1. Input parsing: Platform-specific parsers (_parse_twitter_cookie_input, _configure_xhs_cookies) handle format detection
2. Validation: Required keys must exist before storage proceeds
3. Permission hardening: Files written to disk receive owner-only permissions via _owner_only
4. Uniform consumption: Channel classes read via config.get(key) without needing to know the original input format

Summary

• Twitter: Accepts two space-separated tokens or a full header string via _parse_twitter_cookie_input, storing to YAML keys twitter_auth_token and twitter_ct0
• XiaoHongShu: Accepts JSON arrays or header strings via _configure_xhs_cookies, writing to xhs-cookies.json with 0o600 permissions enforced by _owner_only
• Generic platforms: Forward raw header strings directly to config.set(...) for later parsing by channel classes like xueqiu.py and bilibili.py
• Browser extraction: Uses configure_from_browser in cookie_extract.py to populate the same configuration keys used by manual entry

Frequently Asked Questions

What happens if I provide Twitter cookies in the wrong format?

The agent_reach/cli.py implementation raises a clear error with usage hints. If _parse_twitter_cookie_input cannot find auth_token and ct0 via either whitespace splitting or regex extraction, it prints a message like Usage: agent-reach configure twitter-cookies AUTH_TOKEN CT0 and exits without modifying the configuration.

Why does XiaoHongShu use a JSON file while other platforms use YAML?

XiaoHongShu's API requires structured cookie metadata (name/value pairs) rather than simple header strings. The _configure_xhs_cookies function writes to xhs-cookies.json to preserve this structure when provided via JSON input, or to convert header strings into the required object format. Other platforms consume raw header strings directly, so they store efficiently in the central YAML configuration.

How secure are the stored cookie files?

All cookie files receive restrictive permissions. Specifically, XiaoHongShu's JSON storage and the configuration directory are set to 0o600 and 0o700 respectively via _owner_only and _owner_only_dir, ensuring only the owning user can read or modify authentication data. This is validated by the test suite in tests/test_cookie_extract_perms.py.

Can I mix manual configuration with browser extraction?

Yes. The --from-browser flag in configure_from_browser populates the same configuration keys (twitter_auth_token, xhs-cookies.json, etc.) that manual configuration uses. You can override specific platforms manually after running browser extraction, or vice versa, since both paths call identical config.set(...) methods with the same key naming conventions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}