How the Agent-Reach Configure Command Parses Different Cookie Formats: Twitter and XHS

The agent-reach configure command detects cookie formats by inspecting input strings for specific delimiters and structures, automatically extracting auth_token and ct0 for Twitter from either space-separated tokens or semicolon-delimited headers, while handling XiaoHongShu cookies via JSON array detection or header string parsing.

The agent-reach configure command in the Agent-Reach repository provides a user-friendly interface for persisting authentication credentials across different social platforms. It accepts multiple input formats for cookies, automatically normalizing them through dedicated helper functions in agent_reach/cli.py before storing extracted values in the local configuration file at ~/.agent-reach/config.yaml.

Twitter Cookie Parsing (_parse_twitter_cookie_input)

The agent-reach configure twitter-cookies command processes input through the _parse_twitter_cookie_input helper function located at lines 33–50 in agent_reach/cli.py. This function implements a two-stage detection cascade to identify whether the user provided separate tokens or a full cookie header string.

Separate Token Format

When the input string contains no = characters but splits into exactly two whitespace-separated tokens, the function interprets the first value as auth_token and the second as ct0. This format accepts simple space-separated credentials passed directly on the command line.

# Example: Two separate tokens

>>> _parse_twitter_cookie_input("AAA BBB")
('AAA', 'BBB')

Full Cookie Header Format

If the input contains both auth_token= and ct0= substrings, the function treats the string as a semicolon-delimited cookie header. It splits the string on ; or spaces, examines each part for the target key prefixes, and extracts the values following the = delimiter.

# Example: Full cookie header

>>> _parse_twitter_cookie_input("auth_token=AAA; ct0=BBB")
('AAA', 'BBB')

After successful parsing, the CLI stores the extracted values via config.set("twitter_auth_token", auth_token) and config.set("twitter_ct0", ct0), optionally injecting them into the environment for downstream twitter-cli consumption.

XiaoHongShu Cookie Handling (_configure_xhs_cookies)

For XiaoHongShu (XHS) authentication, the agent-reach configure xhs-cookies command utilizes the _configure_xhs_cookies function (lines 53–89 in agent_reach/cli.py). This helper prepares cookies for the xiaohongshu-mcp Docker container by detecting two distinct input formats.

Cookie-Editor JSON Export

When the input string starts with [, the function attempts json.loads parsing. It validates that the result is a non-empty list of dictionaries containing at least name and value keys. If validation succeeds, the original JSON is preserved or pretty-printed for storage.

Header String Conversion

If the input contains = characters but does not begin with [, the function treats it as a header-style string (e.g., token1=foo; token2=bar). It splits on ;, trims whitespace from each part, and constructs a list of cookie dictionaries with default domain and path values set to .xiaohongshu.com and / respectively.

# Header string example

>>> _configure_xhs_cookies('token1=foo; token2=bar')
Parsed 2 cookies from Header String format
Cookies saved to /home/user/.agent-reach/xhs-cookies.json

Upon successful parsing, the function either copies the resulting JSON into the running xiaohongshu-mcp container via docker cp or writes a local fallback file to ~/.agent-reach/xhs-cookies.json with strict 0600 permissions.

CLI Integration and Configuration Flow

The parsing helpers are invoked from _cmd_configure (the handler for the configure sub-command) around lines 50–70 in agent_reach/cli.py. The dispatch logic routes to the appropriate parser based on the configuration key:

elif args.key == "twitter-cookies":
    auth_token, ct0 = _parse_twitter_cookie_input(value)
    if auth_token and ct0:
        config.set("twitter_auth_token", auth_token)
        config.set("twitter_ct0", ct0)
        # … test the credentials …

elif args.key == "xhs-cookies":
    _configure_xhs_cookies(value)

This architecture hides format-specific complexity from users, providing clear error messages when inputs fail validation. The implementation includes comprehensive test coverage in tests/test_cli.py (verifying Twitter parsing paths) and tests/test_xhs_format.py (covering XiaoHongShu format handling).

Summary

• agent_reach/cli.py contains the core parsing logic at lines 33–50 for Twitter and lines 53–89 for XiaoHongShu cookies.
• Twitter accepts either space-separated tokens (AUTH_TOKEN CT0) or full semicolon-delimited headers (auth_token=xxx; ct0=yyy).
• XiaoHongShu accepts either JSON arrays from Cookie-Editor exports or header-style strings, converting both to a standardized JSON format.
• Parsed credentials persist to ~/.agent-reach/config.yaml or platform-specific JSON files with secure 0600 permissions.
• The command provides helpful usage hints when parsing fails, returning None values for invalid Twitter inputs or printing format-specific error messages for XHS.

Frequently Asked Questions

What cookie formats does the agent-reach configure command accept for Twitter?

The command accepts two distinct formats: space-separated token pairs where the first value is auth_token and the second is ct0, or full HTTP-style cookie headers using semicolon-delimited key-value pairs containing both auth_token and ct0 definitions.

How does the command handle XiaoHongShu cookie exports from browser extensions?

When the input starts with [, the function attempts to parse it as a JSON array conforming to the Cookie-Editor export format, validating that each object contains name and value properties. If validation succeeds, the JSON is preserved for the XiaoHongShu MCP container.

Where are parsed cookies stored after running the configuration command?

Twitter credentials are stored in ~/.agent-reach/config.yaml under the keys twitter_auth_token and twitter_ct0. XiaoHongShu cookies are either copied into the running Docker container or saved to ~/.agent-reach/xhs-cookies.json with restrictive permissions.

What happens if I provide an invalid cookie format?

For Twitter, the parser returns (None, None) when it cannot detect the expected patterns, triggering the CLI to display a usage hint. For XiaoHongShu, the function prints an explanatory error listing the accepted JSON and header string formats before exiting without modifying the configuration.

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