# Optima Scout CLI

AI-powered Amazon product research and 1688 supplier sourcing tool for Claude Code and LLMs.

## Installation

```bash
npm install -g @optima-chat/scout-cli
```

## Quick Start

```bash
# Initialize Claude Code skills
scout init

# Search Amazon products
scout search "coffee maker"

# Get product details
scout product B01GJOMWVA

# Search 1688 suppliers
scout supplier-search "咖啡机"

# Search TikTok Shop products
scout tiktok "wireless earbuds"
```

## Commands

### `scout init`

Initialize Optima Scout skills for Claude Code.

**Options:**
- `-f, --force` - Overwrite existing skills

### `scout search <query>`

Search Amazon products with structured JSON output.

**Options:**
- `-d, --domain <domain>` - Amazon domain (default: `amazon.com`)
- `-l, --limit <number>` - Result limit (default: `10`)
- `-f, --format <format>` - Output: `json` | `text`

**Example:**
```bash
scout search "wireless mouse" --limit 5 --format json
```

### `scout product <asin>`

Get detailed product information.

**Options:**
- `-d, --domain <domain>` - Amazon domain (default: `amazon.com`)
- `-f, --format <format>` - Output: `json` | `text`

**Example:**
```bash
scout product B004YAVF8I --domain amazon.com
```

### `scout supplier-search <keyword>`

Search for suppliers on 1688.com.

**Options:**
- `-l, --limit <number>` - Result limit (default: `20`, max: `100`)
- `-f, --format <format>` - Output: `json` | `text`

**Example:**
```bash
scout supplier-search "咖啡机" --limit 10
scout supplier-search "蓝牙耳机" --format json
```

### `scout tiktok <keyword>`

Search TikTok Shop products with actual sales data.

**Options:**
- `-l, --limit <number>` - Result limit (default: `20`, max: `50`)
- `-f, --format <format>` - Output: `json` | `text`

**Features:**
- ✅ Real sales numbers (not estimates)
- ✅ Actual prices and GMV
- ✅ Product ratings and reviews
- ✅ Shop information
- ✅ Direct product links

**Example:**
```bash
# Text format for quick review
scout tiktok "coffee maker" --limit 10 --format text

# JSON format for LLM processing
scout tiktok "wireless earbuds" --limit 20 --format json
```

**Data Source:** ScrapeCreators API - $0.002/request

## Configuration

Set API endpoint via environment variable:

```bash
export API_URL=http://dev.optima.sh:7290
```

Or create `.env` file:

```env
API_URL=http://localhost:7290
```

## Features

- **JSON-first**: Structured output optimized for LLM parsing
- **Non-interactive**: No spinners, prompts, or colors
- **Fast**: Backend caching for quick responses
- **Claude Code integration**: Auto-discovery via skills

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Link locally
npm link
```

## License

MIT

---

## 技能市场发布 (Skill marketplace publishing)

本仓库同时将 11 个调研/平台技能（`cli/.claude/skills/<slug>/`）发布到 Optima
技能市场，通过两条解耦的发布流程：

- **CLI 发布**（已有）：`git tag cli-v* && git push --tags` → `release-cli.yml` → npm publish
- **Skill 发布**（新增）：`git tag release-v* && git push --tags` → `skill-publish.yml` → 市场发布

每个技能的版本独立管理，记录在各自 `cli/.claude/skills/<slug>/SKILL.md` 的
`version:` frontmatter 中。`release-v*` 标签的数字后缀是 release 序号
（不严格保证连续递增；rollback 后可能跳号），**不是** per-skill 版本号。

Stage 发布（手动）：GitHub Actions → `Publish skills` → 选择 `environment: stage`。

设计文档：[`docs/specs/2026-05-05-c3-scout-design.md`](../docs/specs/2026-05-05-c3-scout-design.md).