npm package: @soshilabs/research
Description: AI-powered research CLI: web search, scraping, briefs, academic search, SEO audits, and more. Powered by Google Gemini and Firecrawl.
Latest version: 1.1.1

# Research Client

AI-powered research CLI and web UI for market research, competitive intelligence, web scraping, SEO audits, academic search, and automated briefing generation.

Powered by **Google Gemini 2.5 Pro** and **Firecrawl**.

[![npm version](https://img.shields.io/npm/v/research-client.svg)](https://www.npmjs.com/package/research-client)

## Install

```bash
npm install -g research-client
```

Or run without installing:

```bash
npx research-client
```

## Quick Start

```bash
# Initialize config and set up your Google AI API key
research init

# Start an interactive AI chat
research chat

# Search the web
research scrape search "agent harness architecture"

# Scrape a URL to markdown
research scrape url https://example.com

# Ask a research question
research research-query ask "What is the current state of AI regulation?"

# Launch the web UI
research ui -p 3000
```

## Commands

### Setup & Auth

| Command | Description |
|---------|-------------|
| `research init` | Initialize config directories and API key |
| `research login` | Authenticate with Google AI (browser or paste key) |
| `research config` | View current configuration |
| `research config get <key>` | Get a specific config value |
| `research ui -p <port>` | Launch the Next.js web UI |

### Interactive Chat

| Command | Description |
|---------|-------------|
| `research chat` | Start an AI chat session in terminal |
| `research chat -m <model>` | Use a specific Gemini model |
| `research chat -s <prompt>` | Use a custom system prompt |

### Briefs (Research Reports)

Briefs are structured research reports that can be scheduled to auto-refresh.

| Command | Description |
|---------|-------------|
| `research briefs list` | List all briefs |
| `research briefs show <id>` | Show full brief details |
| `research briefs create <title>` | Create a new brief |
| `research briefs update <id>` | Update title, topic, summary, or status |
| `research briefs delete <id>` | Delete a brief |
| `research briefs settings <id>` | View/update brief settings |
| `research briefs schedule <id>` | View/set schedule (hourly/daily/weekly) |
| `research briefs add-source <briefId> <sourceId>` | Add a source with weight |
| `research briefs remove-source <briefId> <sourceId>` | Remove a source |
| `research briefs sources <briefId>` | List sources with weights |
| `research briefs set-weight <briefId> <sourceId> <weight>` | Set source weight (0-5) |
| `research briefs add-peer-repo <briefId> <name> <url>` | Add academic peer review repo |
| `research briefs remove-peer-repo <briefId> <repoId>` | Remove peer review repo |
| `research briefs peer-repos <briefId>` | List peer review repos |
| `research briefs export <id>` | Export brief as markdown |
| `research briefs export <id> -o file.md` | Export to file |
| `research briefs runs <briefId>` | List scheduled runs |
| `research briefs run-show <runId>` | Show full run content |

### Sources

| Command | Description |
|---------|-------------|
| `research sources list` | List all sources |
| `research sources add <url>` | Add a source URL |
| `research sources remove <id>` | Remove a source |
| `research sources scrape <id>` | Scrape a source via Firecrawl |

### Spaces

| Command | Description |
|---------|-------------|
| `research spaces list` | List research spaces |
| `research spaces create <name> -f <areas...>` | Create with focus areas |
| `research spaces remove <id>` | Remove a space |

### Trends

| Command | Description |
|---------|-------------|
| `research trends list` | List trend monitors |
| `research trends add <keyword>` | Add a trend monitor |
| `research trends remove <id>` | Remove a trend |

### Web Scraping

| Command | Description |
|---------|-------------|
| `research scrape url <url>` | Scrape a URL to markdown |
| `research scrape url <url> --json` | Output raw JSON |
| `research scrape search <query>` | Search the web via Firecrawl |
| `research scrape search <query> --scrape` | Search + scrape top results |
| `research scrape crawl <url> -l <limit>` | Crawl a domain |

### AI Research Queries

| Command | Description |
|---------|-------------|
| `research research-query ask <question>` | AI-powered research question |
| `research research-query company <name>` | Company analysis |
| `research research-query market <topic>` | Market analysis |

### SEO Audits

| Command | Description |
|---------|-------------|
| `research seo audit <url>` | AI-powered SEO audit |
| `research seo lighthouse <url>` | Full Lighthouse audit (local Chrome) |
| `research seo robots <url>` | Check robots.txt |
| `research seo sitemap <url>` | Parse sitemap.xml |

### Academic Search

| Command | Description |
|---------|-------------|
| `research academic search <query>` | Search Semantic Scholar, CrossRef, PubMed |
| `research academic search <query> --source pubmed` | Search single database |
| `research academic paper <doi>` | Get paper details by DOI |

### Scheduling

| Command | Description |
|---------|-------------|
| `research cron run` | Manually trigger brief scheduler |
| `research cron status` | Check scheduled brief status |

## API Keys

| Key | Required | Purpose |
|-----|----------|---------|
| `GOOGLE_GENERATIVE_AI_API_KEY` | Yes | Powers AI chat, research queries, and brief generation |
| `FIRECRAWL_API_KEY` | Recommended | Web search, scraping, and crawling |

Get your keys:
- Google AI: [aistudio.google.com/apikey](https://aistudio.google.com/apikey)
- Firecrawl: [firecrawl.dev/app/api-keys](https://firecrawl.dev/app/api-keys)

Keys are stored in `~/.research/.env`.

## Web UI

The research client includes a full Next.js web UI with:

- AI chat with 40+ tools (scraping, research, SEO, academic, briefs)
- Brief management with scheduled auto-refresh
- Source library and trend monitoring
- SEO audit dashboard
- Academic peer review matching

```bash
research ui -p 3000
```

## Data Storage

All data is stored locally in `~/.research/data/` as JSON files:

- `briefs.json` — Research briefs
- `brief-runs.json` — Scheduled brief outputs
- `sources.json` — Source URLs and excerpts
- `spaces.json` — Research workspaces
- `trends.json` — Trend monitors
- `chat.json` — Chat history
- `settings.json` — Preferences

## Tech Stack

- **CLI**: Commander.js, Chalk, Inquirer
- **AI**: Google Gemini 2.5 Pro via `@ai-sdk/google`
- **Scraping**: Firecrawl API
- **Academic**: Semantic Scholar, CrossRef, PubMed
- **SEO**: Google PageSpeed Insights, Lighthouse
- **Web UI**: Next.js 15, React 19, Tailwind CSS, Vercel AI SDK

## License

MIT