# CLI Commands Reference

## gsearch [search] "query"

Default command. Search Google with AI Overview and organic results.

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| --max-results | -n | 10 | Max organic results |
| --json | | false | JSON output |
| --no-ai | | false | Skip AI Overview |
| --lang | | en | Search language (hl param) |
| --region | | auto | Search region (gl param, e.g., US, CA, GB) |
| --time | | none | Time filter: hour, 1h, 12h, day, 24h, week, 7d, month, year |
| --after | | none | Results after date (YYYY-MM-DD) |
| --before | | none | Results before date (YYYY-MM-DD) |
| --timeout | | 30 | Timeout in seconds |

**Examples:**
```bash
gsearch "what is kubernetes"                         # default search
gsearch "AI news" --time day                         # last 24 hours
gsearch "breaking news" --time 12h                   # last 12 hours
gsearch "earnings" --after 2026-01-01 --before 2026-03-31
gsearch "python tutorial" -n 5 --lang fr --json
```

## gsearch ai "query"

Google AI Mode (g.ai) synthesized search.

| Flag | Default | Description |
|------|---------|-------------|
| --json | false | JSON output |
| --lang | en | Search language |
| --region | auto | Search region |
| --time | none | Time filter: hour, 1h, 12h, day, 24h, week, 7d, month, year |
| --after | none | Results after date (YYYY-MM-DD) |
| --before | none | Results before date (YYYY-MM-DD) |
| --timeout | 30 | Timeout |

**Examples:**
```bash
gsearch ai "explain kubernetes architecture"
gsearch ai "latest AI developments" --time week --json
```

## gsearch fetch "url"

Fetch a URL and convert to clean Markdown.

| Flag | Default | Description |
|------|---------|-------------|
| --raw | false | Plain text output (no Markdown) |
| --json | false | JSON with metadata (title, content, word_count) |
| --browser | auto | Browser mode: auto, always (JS-heavy sites), never (faster) |
| --timeout | 30 | Timeout |

**Examples:**
```bash
gsearch fetch "https://kubernetes.io/docs/"
gsearch fetch "https://example.com" --raw
gsearch fetch "https://spa-app.com" --browser always
```

## gsearch setup

Profile warmup and MCP server configuration.

### gsearch setup (default)

Run browser profile warmup (~8 seconds, one-time).

| Flag | Description |
|------|-------------|
| --reset | Delete existing profile and re-warmup from scratch |
| --check | Verify profile is warmed up and ready |

### gsearch setup add TOOL

Configure gsearch-mcp as an MCP server for an AI tool.

| Tool | Description |
|------|-------------|
| claude-code | Anthropic Claude Code CLI |
| gemini-cli | Google Gemini CLI |
| cursor | Cursor AI editor |
| windsurf | Codeium Windsurf editor |
| cline | Cline CLI terminal agent |
| antigravity | Google Antigravity AI IDE |
| codex | OpenAI Codex CLI |
| opencode | OpenCode terminal assistant |
| json | Print JSON config snippet (copies to clipboard on macOS) |
| all | Interactive setup for multiple tools |

**Examples:**
```bash
gsearch setup add cursor
gsearch setup add claude-code
gsearch setup add json
```

### gsearch setup remove TOOL

Remove gsearch-mcp from a tool's MCP configuration.

### gsearch setup list

List all supported MCP setup targets.

## gsearch config

Configuration management.

| Subcommand | Description |
|------------|-------------|
| show | Show all settings as a table |
| set KEY VALUE | Set a config value |
| get KEY | Get a config value |

**Config keys:**

| Key | Default | Description |
|-----|---------|-------------|
| browser | auto | Preferred browser (auto/chrome/brave/edge/chromium/vivaldi/opera) |
| lang | en | Default search language |
| region | (none) | Default search region |
| max_results | 10 | Default max results |
| json_output | false | Always output JSON |
| rate_limit | 2.0 | Min seconds between searches |
| max_tabs | 5 | Max concurrent browser tabs |
| timeout | 30 | Default timeout (seconds) |

**Examples:**
```bash
gsearch config show
gsearch config set browser brave
gsearch config set rate_limit 1.0
gsearch config set lang fr
```

## gsearch doctor

Run diagnostic checks on browser, profile, config, and connectivity.

| Flag | Description |
|------|-------------|
| --verbose | Show detailed diagnostic output |

**Checks performed:**
- Browser found (name + path)
- Profile directory exists
- Profile warmed up
- Config file valid

## gsearch skill

Skill installer for AI tools.

### gsearch skill list

Show all install targets with status (installed/not installed).

### gsearch skill install TARGET

Install SKILL.md and references to the target tool's skill directory.

| Flag | Description |
|------|-------------|
| --project | Install to project-local path instead of user path |

**Targets:**

| Target | User Path |
|--------|-----------|
| claude-code | ~/.claude/skills/gsearch-mcp |
| cursor | ~/.cursor/skills/gsearch-mcp |
| agents | ~/.agents/skills/gsearch-mcp |
| codex | ~/.agents/skills/gsearch-mcp |
| gemini-cli | ~/.agents/skills/gsearch-mcp |
| opencode | ~/.config/opencode/skills/gsearch-mcp |
| antigravity | ~/.gemini/antigravity/skills/gsearch-mcp |
| cline | ~/.cline/skills/gsearch-mcp |
| openclaw | ~/.openclaw/workspace/skills/gsearch-mcp |
| cc-claw | ~/.cc-claw/workspace/skills/gsearch-mcp |
| other | ./gsearch-mcp-skill-export (export for manual install) |

**Examples:**
```bash
gsearch skill install cursor
gsearch skill install cc-claw
gsearch skill install other          # export all files
gsearch skill install cursor --project  # project-local
```

### gsearch skill update

Update all installed skills with the latest version.

## Global Flags

| Flag | Description |
|------|-------------|
| --version | Print version and exit |
| --ai | Print AI-optimized documentation (for LLM agents) |
| --verbose | Enable debug logging |
| --help | Show help |

## Time Filter Reference

| Value | Meaning | Google tbs Parameter |
|-------|---------|---------------------|
| hour / 1h | Last hour | qdr:h |
| 12h | Last 12 hours | qdr:h12 |
| day / 24h / 1d | Last 24 hours | qdr:d |
| week / 7d / 1w | Last week | qdr:w |
| month / 1m | Last month | qdr:m |
| year / 1y | Last year | qdr:y |
| Nh (e.g., 6h) | Last N hours | qdr:hN |
| --after/--before | Custom date range | cdr:1,cd_min:...,cd_max:... |
