tail-fin-cli 0.2.0

# tail-fin

Multi-site browser automation CLI. Attaches to your existing Chrome — or auto-launches a stealth browser — to interact with websites using your active login sessions.

## Supported Sites

| Site | Commands | Mode |
|------|----------|------|
| [Twitter/X](docs/sites/twitter.md) | `timeline`, `search`, `profile`, `bookmarks`, `likes`, `thread`, `post`, `like`, `follow`, `unfollow`, `delete`, `block`, `unblock`, `bookmark`, `unbookmark`, `reply`, `trending`, `followers`, `following`, `notifications`, `download`, `hide-reply`, `article`, `lists`, `reply-dm`, `accept` | Browser or `--cookies` |
| [Reddit](docs/sites/reddit.md) | `hot`, `frontpage`, `popular`, `search`, `subreddit`, `read`, `user`, `user-posts`, `user-comments`, `saved`, `upvoted`, `upvote`, `save`, `comment`, `subscribe` | Browser |
| [Bloomberg](docs/sites/bloomberg.md) | `main`, `markets`, `economics`, `industries`, `tech`, `politics`, `businessweek`, `feeds`, `news` | RSS / `news` needs browser |
| [Coupang](docs/sites/coupang.md) | `search`, `detail`, `cart`, `add-to-cart` | Auto-launch stealth |
| [PCC 政府採購](docs/sites/pcc.md) | `info`, `search`, `search-company`, `search-id`, `search-budget`, `budgets`, `date`, `units`, `unit`, `tender` | Auto-launch stealth (Cloudflare bypass) |
| [Instagram](docs/sites/instagram.md) | `profile`, `search`, `user`, `explore`, `followers`, `following`, `saved`, `like`, `unlike`, `follow`, `unfollow`, `save`, `unsave`, `comment` | Browser |
| [Grok](docs/sites/grok.md) | `ask`, `conversations` | Browser |
| [YouTube](docs/sites/youtube.md) | `search`, `video`, `channel`, `comments`, `trending`, `transcript`, `subscriptions` | Browser |
| [SeekingAlpha](docs/sites/sa.md) | `income-statement`, `balance-sheet`, `cash-flow`, `quote`, `news`, `analysis`, `article` | Browser or `--cookies` |
| [Xiaohongshu](docs/sites/xhs.md) | `search`, `note`, `user-notes`, `comments`, `feed`, `notifications`, `media` | Browser |
| [591 Taiwan Rentals](docs/sites/591.md) | `regions`, `hot`, `community`, `price-history`, `sales`, `search`, `crawl` | Partial (some public) |
| [Any site](docs/gen.md) | `gen generate` + `run` — auto-generate CLI adapters | Browser |

## Quick Start

```sh
# 1. Install
cargo install --path crates/tail-fin-cli

# 2. Some adapters auto-launch a stealth browser (no Chrome setup needed)
tail-fin coupang search "耳機" --limit 5
tail-fin pcc search "電腦"

# 3. For sites that need your login, start Chrome with remote debugging
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# 4. Log in to the sites you want, then run commands
tail-fin --connect 127.0.0.1:9222 twitter timeline
tail-fin --connect 127.0.0.1:9222 reddit hot --limit 10
tail-fin --connect 127.0.0.1:9222 instagram profile natgeo
tail-fin --connect 127.0.0.1:9222 youtube search "rust programming"

# 5. Bloomberg RSS works without any browser
tail-fin bloomberg markets --limit 5

# 6. Auto-generate a CLI for any site
tail-fin --connect 127.0.0.1:9222 gen generate https://news.ycombinator.com
tail-fin --connect 127.0.0.1:9222 run hackernews hot
```

## Global Flags

| Flag | Default | Description |
|------|---------|-------------|
| `--connect <host:port>` | — | Chrome remote debugging address |
| `--cookies [path]` | — | Use saved cookies (twitter, sa) |
| `--headed` | `false` | Run browser in headed (visible) mode |

## Output

All commands output JSON to stdout. Errors go to stderr.

## Selective Install

Each adapter is a Cargo feature. Install only what you need:

```sh
# All adapters (default, ~10MB release binary)
cargo install --path crates/tail-fin-cli

# Only Twitter + Reddit (~8.6MB)
cargo install --path crates/tail-fin-cli --no-default-features --features twitter,reddit

# Only Bloomberg (RSS, minimal)
cargo install --path crates/tail-fin-cli --no-default-features --features bloomberg
```

Available features: `twitter`, `reddit`, `bloomberg`, `coupang`, `pcc`, `instagram`, `xhs`, `youtube`, `grok`, `sa`, `s591`, `gen`

## Documentation

- [Getting Started](docs/getting-started.md) — prerequisites, installation, basic usage
- [Architecture](docs/architecture.md) — crate structure, adapter pattern, dependency graph
- [Cloudflare](docs/cloudflare.md) — Turnstile vs JS Challenge
- [Gen — Auto CLI Generation](docs/gen.md) — explore, synthesize, generate, run

## Development

```sh
cargo build           # build all crates
cargo test            # run all tests (304 unit tests)
cargo test -- --ignored  # run live tests (hits real APIs)
cargo clippy          # lint
cargo fmt             # format
```

## License

[MIT](LICENSE)