# How to Format XHS API Output Using the Agent-Reach CLI

> Format XHS API output for LLMs with Agent-Reach CLI. Clean raw JSON using stdin and extract essential fields for token-friendly processing.

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

---

**The `agent_reach format --platform xhs` command sanitizes raw XiaoHongShu JSON payloads into a compact, token-friendly structure by reading from STDIN and extracting only essential fields for LLM processing.**

The Agent-Reach repository provides a specialized CLI tool for preprocessing social media API responses. When you need to format XHS API output for downstream language model processing, the `format` sub-command offers a streamlined solution that strips redundant metadata while preserving critical content fields.

## How the Format Command Processes XHS Data

The CLI entry point in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) orchestrates the formatting pipeline. When you execute the command with the `--platform xhs` flag, the tool expects raw JSON input from STDIN and delegates the transformation to a platform-specific handler.

The workflow follows these steps:

1. **Reads raw JSON from STDIN** – The command accepts complete XHS API responses via pipes or redirects.
2. **Parses the payload** – Uses `json.loads` to convert the stream into Python objects.
3. **Dispatches to the formatter** – Calls `format_xhs_result` defined in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) (lines 9-30).
4. **Serializes clean output** – Returns pretty-printed JSON to STDOUT with unnecessary fields removed.

### Deep Cleaning with `format_xhs_result`

The heavy lifting occurs in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) within the `format_xhs_result` function. This implementation performs a deep clean that normalizes both single objects and list-based responses, including the `{"items": ...}` wrapper common in XHS search endpoints.

The formatter extracts only high-value fields while stripping token-heavy noise:

- **Preserved fields**: `id`, `title`, `desc`, `type`, `xsec_token`, author `nickname` and `user_id`, interaction metrics (`liked_count`, `collected_count`, `comment_count`, `share_count`), image URLs, and tag names.
- **Removed fields**: Avatar URLs, internal user IDs, extra metadata, and redundant nested structures.

This architecture isolates platform-specific logic from the CLI interface, enabling the same `format` entry point to support additional platforms through matching formatter functions.

## Practical Usage Examples

The command accepts input exclusively through STDIN, making it compatible with Unix pipes and here-documents for testing.

### Piping a File

Send an existing raw response through the formatter:

```bash
cat raw_xhs.json | python -m agent_reach.cli format --platform xhs

```

### Using a Here-Document

For quick testing without creating intermediate files:

```bash
python -m agent_reach.cli format --platform xhs <<'EOF'
{
  "id": "abc123",
  "title": "测试笔记",
  "desc": "这是正文内容",
  "type": "normal",
  "xsec_token": "tok_xxx",
  "user": {
    "nickname": "小红",
    "user_id": "u123",
    "avatar": "https://example.com/avatar.jpg",
    "extra_field": "should be dropped"
  },
  "interact_info": {
    "liked_count": "100",
    "collected_count": "50",
    "comment_count": "20",
    "share_count": "10"
  },
  "image_list": [
    {"url": "https://img.example.com/1.jpg"},
    {"url": "https://img.example.com/2.jpg"}
  ],
  "tag_list": [
    {"name": "旅行"},
    {"name": "美食"}
  ]
}
EOF

```

## Transformed Output Structure

The sanitized output preserves only LLM-relevant fields while dramatically reducing token consumption. Instead of nested objects, the formatter produces a flat, predictable structure.

**Key transformations:**

- **Interaction metrics** are flattened from `interact_info` to top-level keys
- **Image URLs** are extracted from `image_list` into a simple `images` array
- **Tags** are converted from objects to string arrays
- **User objects** are stripped to only `nickname` and `user_id`

```json
{
  "id": "abc123",
  "title": "测试笔记",
  "desc": "这是正文内容",
  "type": "normal",
  "xsec_token": "tok_xxx",
  "user": {
    "nickname": "小红",
    "user_id": "u123"
  },
  "liked_count": "100",
  "collected_count": "50",
  "comment_count": "20",
  "share_count": "10",
  "images": [
    "https://img.example.com/1.jpg",
    "https://img.example.com/2.jpg"
  ],
  "tags": [
    "旅行",
    "美食"
  ]
}

```

The expected behavior is validated in [`tests/test_xhs_format.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_xhs_format.py) (lines 58-71), ensuring consistent field extraction across different XHS endpoint variations.

## Summary

- The `agent_reach format --platform xhs` command reads raw JSON from STDIN and outputs sanitized, token-efficient JSON suitable for LLM ingestion
- Core logic resides in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py), specifically the `format_xhs_result` function (lines 9-30)
- The formatter handles both single items and list responses, including `{"items": ...}` wrappers from search endpoints
- Output flattens interaction metrics, extracts image URLs into arrays, and strips redundant user metadata like avatars
- This architecture isolates platform-specific formatting logic from the CLI interface, enabling easy extension to other platforms

## Frequently Asked Questions

### What fields does the XHS formatter preserve?

The `format_xhs_result` function preserves `id`, `title`, `desc`, `type`, `xsec_token`, author `nickname` and `user_id`, interaction counts (liked, collected, comment, share), image URLs, and tag names. It removes avatar URLs, internal IDs, and other noisy attributes that consume tokens without adding value to LLM processing.

### Can I format multiple XHS posts at once?

Yes. The formatter handles both individual dictionary objects and list-based responses, including the `{"items": [...]}` wrapper returned by XHS search endpoints. When processing a list, it applies the cleaning logic to each item in the collection automatically.

### How do I handle authentication tokens in the output?

The formatter preserves the `xsec_token` field in the root object as it may be required for subsequent API calls, but strips other internal authentication artifacts. According to the test suite in [`tests/test_xhs_format.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_xhs_format.py), the output maintains only the necessary identifiers for content reference while removing sensitive session data.

### Why does the command use STDIN instead of file arguments?

The STDIN-based design follows Unix philosophy for composability, allowing you to pipe output directly from `curl` requests or other tools without intermediate files. This approach keeps the CLI interface minimal while supporting flexible workflows like `curl -s "https://api.example.com/xhs" | agent_reach format --platform xhs`.