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

> Learn how agent-reach configure command handles space-separated tokens JSON payloads and header strings normalizing them for secure storage in ~/.agent-reach Configure your agent easily

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-07-05

---

**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](https://github.com/Panniantong/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`**.

```bash

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cookie_extract_perms.py)), which tighten file permissions to **`0o600`** and the parent directory to **`0o700`** before writing.

```bash

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xueqiu.py)** and **[`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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.

```bash

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.

```bash

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) and verified by `test_configure_xhs_cookies_tightens_local_fallback_file` in [`tests/test_cookie_extract_perms.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/xueqiu.py) and [`bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/bilibili.py)
- **Browser extraction**: Uses `configure_from_browser` in [`cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.