tavily-cli 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (19) hide show
  1. tavily_cli-0.1.0/.gitignore +30 -0
  2. tavily_cli-0.1.0/PKG-INFO +330 -0
  3. tavily_cli-0.1.0/README.md +299 -0
  4. tavily_cli-0.1.0/pyproject.toml +60 -0
  5. tavily_cli-0.1.0/tavily_cli/__init__.py +3 -0
  6. tavily_cli-0.1.0/tavily_cli/cli.py +161 -0
  7. tavily_cli-0.1.0/tavily_cli/commands/__init__.py +0 -0
  8. tavily_cli-0.1.0/tavily_cli/commands/auth.py +174 -0
  9. tavily_cli-0.1.0/tavily_cli/commands/crawl.py +96 -0
  10. tavily_cli-0.1.0/tavily_cli/commands/extract.py +66 -0
  11. tavily_cli-0.1.0/tavily_cli/commands/map_cmd.py +78 -0
  12. tavily_cli-0.1.0/tavily_cli/commands/research.py +335 -0
  13. tavily_cli-0.1.0/tavily_cli/commands/search.py +101 -0
  14. tavily_cli-0.1.0/tavily_cli/common.py +56 -0
  15. tavily_cli-0.1.0/tavily_cli/config.py +142 -0
  16. tavily_cli-0.1.0/tavily_cli/mcp_client.py +115 -0
  17. tavily_cli-0.1.0/tavily_cli/output.py +310 -0
  18. tavily_cli-0.1.0/tavily_cli/repl.py +159 -0
  19. tavily_cli-0.1.0/tavily_cli/theme.py +66 -0
tavily_cli-0.1.0/.gitignore ADDED
@@ -0,0 +1,30 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+ *.so
6
+
7
+ # Distribution / packaging
8
+ build/
9
+ dist/
10
+ *.egg-info/
11
+ *.egg
12
+
13
+ # Virtual environments
14
+ .venv/
15
+ venv/
16
+ env/
17
+
18
+ # IDE
19
+ .idea/
20
+ .vscode/
21
+ *.swp
22
+ *.swo
23
+
24
+ # Environment variables
25
+ .env
26
+ .env.local
27
+
28
+ # OS
29
+ .DS_Store
30
+ Thumbs.db
tavily_cli-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,330 @@
1
+ Metadata-Version: 2.4
2
+ Name: tavily-cli
3
+ Version: 0.1.0
4
+ Summary: CLI and agent tools for the Tavily API — search, extract, crawl, map, and research from the command line.
5
+ Project-URL: Homepage, https://tavily.com
6
+ Project-URL: Documentation, https://docs.tavily.com
7
+ Project-URL: Repository, https://github.com/tavily-ai/tavily-cli
8
+ Project-URL: Issues, https://github.com/tavily-ai/tavily-cli/issues
9
+ Author-email: Tavily <dean.sacoransky@tavily.com>
10
+ License-Expression: MIT
11
+ Keywords: agents,ai,crawl,extract,llm,rag,research,tavily,web-search
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
22
+ Requires-Python: >=3.10
23
+ Requires-Dist: click>=8.1.0
24
+ Requires-Dist: httpx>=0.27.0
25
+ Requires-Dist: rich>=13.0.0
26
+ Requires-Dist: tavily-python>=0.7.0
27
+ Provides-Extra: dev
28
+ Requires-Dist: pytest>=8.0.0; extra == 'dev'
29
+ Requires-Dist: ruff>=0.4.0; extra == 'dev'
30
+ Description-Content-Type: text/markdown
31
+
32
+ # Tavily CLI
33
+
34
+ CLI and agent tools for the [Tavily API](https://docs.tavily.com) — search, extract, crawl, map, and research from the command line.
35
+
36
+ > **Note:** This package provides the `tvly` command-line tool. It depends on
37
+ > [`tavily-python`](https://pypi.org/project/tavily-python/), the official Tavily Python SDK.
38
+
39
+ ## Features
40
+
41
+ - **Interactive REPL** — Run `tvly` with no arguments for a chat-like shell experience
42
+ - **CLI for Humans & AI Agents** — Rich-formatted output for humans, `--json` for agents
43
+ - **Web Search** — LLM-optimized search with domain/date filtering and relevance scoring
44
+ - **Content Extraction** — Extract clean markdown from any URL
45
+ - **Website Crawling** — Crawl sites with depth/breadth control and path filtering
46
+ - **URL Discovery** — Map all URLs on a site without content extraction
47
+ - **Deep Research** — AI-powered research with citations and structured output
48
+
49
+ ## Installation
50
+
51
+ Requires **Python 3.10+**.
52
+
53
+ ```bash
54
+ pip install tavily-cli
55
+ ```
56
+
57
+ ### From source
58
+
59
+ ```bash
60
+ git clone https://github.com/tavily-ai/tavily-cli.git
61
+ cd tavily-cli
62
+ pip install -e .
63
+ ```
64
+
65
+ ## Quick Start
66
+
67
+ ### 1. Authenticate
68
+
69
+ ```bash
70
+ # Set API key directly
71
+ tvly login --api-key tvly-YOUR_KEY
72
+
73
+ # Or use environment variable
74
+ export TAVILY_API_KEY=tvly-YOUR_KEY
75
+
76
+ # Or OAuth (opens browser)
77
+ tvly login
78
+
79
+ # Check auth status
80
+ tvly auth
81
+ ```
82
+
83
+ ### 2. Interactive Mode
84
+
85
+ ```bash
86
+ # Launch the interactive REPL
87
+ tvly
88
+ ```
89
+
90
+ This opens a chat-like shell where you can run commands without the `tvly` prefix:
91
+
92
+ ```
93
+ ❯ search "latest AI trends"
94
+ ❯ extract https://example.com
95
+ ❯ help
96
+ ```
97
+
98
+ ### 3. Search the Web
99
+
100
+ ```bash
101
+ # Basic search
102
+ tvly search "latest AI trends"
103
+
104
+ # Advanced search with filters
105
+ tvly search "quantum computing" --depth advanced --max-results 10 --time-range week
106
+
107
+ # Search specific domains
108
+ tvly search "SEC filings for Apple" --include-domains sec.gov,reuters.com
109
+
110
+ # JSON output for agents
111
+ tvly search "AI news" --json
112
+ ```
113
+
114
+ ### 4. Extract Content from URLs
115
+
116
+ ```bash
117
+ # Extract a single URL
118
+ tvly extract https://example.com/article
119
+
120
+ # Extract multiple URLs with a focus query
121
+ tvly extract https://example.com https://other.com --query "pricing information"
122
+
123
+ # Advanced extraction for JS-heavy pages
124
+ tvly extract https://spa-app.com --extract-depth advanced
125
+ ```
126
+
127
+ ### 5. Crawl a Website
128
+
129
+ ```bash
130
+ # Basic crawl
131
+ tvly crawl https://docs.example.com
132
+
133
+ # Deep crawl with filters
134
+ tvly crawl https://docs.example.com --max-depth 2 --limit 100 --select-paths "/api/.*,/guides/.*"
135
+
136
+ # Semantic focus
137
+ tvly crawl https://docs.example.com --instructions "Find authentication docs" --chunks-per-source 3
138
+
139
+ # Save pages as markdown files
140
+ tvly crawl https://docs.example.com --output-dir ./docs
141
+ ```
142
+
143
+ ### 6. Map URLs
144
+
145
+ ```bash
146
+ # Discover all URLs on a site
147
+ tvly map https://example.com
148
+
149
+ # Filter by path
150
+ tvly map https://example.com --select-paths "/blog/.*" --limit 500
151
+ ```
152
+
153
+ ### 7. Deep Research
154
+
155
+ ```bash
156
+ # Run research and wait for results
157
+ tvly research "Competitive landscape of AI code assistants"
158
+
159
+ # Use pro model for comprehensive analysis
160
+ tvly research "Electric vehicle market analysis" --model pro
161
+
162
+ # Stream results in real-time
163
+ tvly research "AI market trends" --stream
164
+
165
+ # Async: start and poll separately
166
+ tvly research "topic" --no-wait --json # returns request_id
167
+ tvly research status <request_id> --json # check status
168
+ tvly research poll <request_id> --json # wait and get result
169
+
170
+ # Structured output
171
+ tvly research "AI market size" --output-schema schema.json --json
172
+ ```
173
+
174
+ ## CLI Overview
175
+
176
+ ```
177
+ tvly
178
+ ├── (no command) # Interactive REPL
179
+ ├── login # Authenticate (OAuth or API key)
180
+ ├── logout # Clear stored credentials
181
+ ├── auth # Check authentication status
182
+ ├── search <query> # Web search
183
+ ├── extract <urls...> # Extract content from URLs
184
+ ├── crawl <url> # Crawl a website
185
+ ├── map <url> # Discover URLs (no content)
186
+ └── research <query> # Deep research (async)
187
+ ├── run <query> # Start a research task (same as above)
188
+ ├── status <id> # Check task status
189
+ └── poll <id> # Poll until completion
190
+ ```
191
+
192
+ ## Non-Interactive Mode (for AI Agents & Scripts)
193
+
194
+ All commands support `--json` output and can be fully controlled via CLI arguments.
195
+
196
+ **Auto-detection:** JSON output is automatically enabled when stdout is piped (e.g., called from Claude Code, scripts, or piped to `jq`). No need to pass `--json` explicitly.
197
+
198
+ ```bash
199
+ # Every command supports --json for structured output
200
+ tvly search "query" --json
201
+ tvly auth --json
202
+ tvly extract https://example.com --json
203
+
204
+ # Read input from stdin with "-"
205
+ echo "What is the latest funding for Anthropic?" | tvly search - --json
206
+ echo "Research question" | tvly research - --json
207
+
208
+ # Async research: launch then poll separately
209
+ tvly research "question" --no-wait --json # returns request_id
210
+ tvly research status <id> --json # check status
211
+ tvly research poll <id> --json # wait and get result
212
+
213
+ # Global options
214
+ tvly --version # show version
215
+ tvly --status # show version + auth status
216
+ tvly --status --json # structured status
217
+ ```
218
+
219
+ ### Exit Codes
220
+
221
+ | Code | Meaning |
222
+ |------|---------|
223
+ | 0 | Success |
224
+ | 2 | Invalid input / usage error |
225
+ | 3 | Authentication error |
226
+ | 4 | API error |
227
+
228
+ ## Command Reference
229
+
230
+ ### `tvly search`
231
+
232
+ | Option | Description |
233
+ |--------|-------------|
234
+ | `--depth` | `ultra-fast`, `fast`, `basic` (default), `advanced` |
235
+ | `--max-results` | Maximum results, 0-20 (default: 5) |
236
+ | `--topic` | `general` (default), `news`, `finance` |
237
+ | `--time-range` | `day`, `week`, `month`, `year` |
238
+ | `--start-date` | Results after date (YYYY-MM-DD) |
239
+ | `--end-date` | Results before date (YYYY-MM-DD) |
240
+ | `--include-domains` | Comma-separated domains to include |
241
+ | `--exclude-domains` | Comma-separated domains to exclude |
242
+ | `--country` | Boost results from country |
243
+ | `--include-answer` | Include AI answer (`basic` or `advanced`) |
244
+ | `--include-raw-content` | Include full page (`markdown` or `text`) |
245
+ | `--include-images` | Include image results |
246
+ | `--chunks-per-source` | Chunks per source (advanced/fast depth only) |
247
+ | `-o` / `--output` | Save output to file |
248
+
249
+ ### `tvly extract`
250
+
251
+ | Option | Description |
252
+ |--------|-------------|
253
+ | `--query` | Rerank chunks by relevance |
254
+ | `--chunks-per-source` | Chunks per source (1-5, requires `--query`) |
255
+ | `--extract-depth` | `basic` (default) or `advanced` |
256
+ | `--format` | `markdown` (default) or `text` |
257
+ | `--include-images` | Include image URLs |
258
+ | `--timeout` | Max wait (1-60 seconds) |
259
+ | `-o` / `--output` | Save output to file |
260
+
261
+ ### `tvly crawl`
262
+
263
+ | Option | Description |
264
+ |--------|-------------|
265
+ | `--max-depth` | Levels deep (1-5, default: 1) |
266
+ | `--max-breadth` | Links per page (default: 20) |
267
+ | `--limit` | Total pages cap (default: 50) |
268
+ | `--instructions` | Natural language guidance |
269
+ | `--chunks-per-source` | Chunks per page (1-5, requires `--instructions`) |
270
+ | `--extract-depth` | `basic` or `advanced` |
271
+ | `--format` | `markdown` or `text` |
272
+ | `--select-paths` | Regex patterns for paths to include |
273
+ | `--exclude-paths` | Regex patterns for paths to exclude |
274
+ | `--select-domains` | Regex for domains to include |
275
+ | `--exclude-domains` | Regex for domains to exclude |
276
+ | `--allow-external` | Include external links (default: true) |
277
+ | `--include-images` | Include images |
278
+ | `--timeout` | Max wait (10-150 seconds) |
279
+ | `-o` / `--output` | Save JSON to file |
280
+ | `--output-dir` | Save each page as .md file in directory |
281
+
282
+ ### `tvly map`
283
+
284
+ | Option | Description |
285
+ |--------|-------------|
286
+ | `--max-depth` | Levels deep (1-5, default: 1) |
287
+ | `--max-breadth` | Links per page (default: 20) |
288
+ | `--limit` | Max URLs to discover (default: 50) |
289
+ | `--instructions` | Natural language guidance |
290
+ | `--select-paths` | Regex patterns for paths to include |
291
+ | `--exclude-paths` | Regex patterns for paths to exclude |
292
+ | `--allow-external` | Include external links |
293
+ | `--timeout` | Max wait (10-150 seconds) |
294
+ | `-o` / `--output` | Save output to file |
295
+
296
+ ### `tvly research <query>` / `tvly research run <query>`
297
+
298
+ | Option | Description |
299
+ |--------|-------------|
300
+ | `--model` | `mini`, `pro`, or `auto` (default) |
301
+ | `--no-wait` | Return request_id immediately |
302
+ | `--stream` | Stream results in real-time |
303
+ | `--output-schema` | Path to JSON schema file |
304
+ | `--citation-format` | `numbered`, `mla`, `apa`, `chicago` |
305
+ | `--poll-interval` | Seconds between checks (default: 10) |
306
+ | `--timeout` | Max wait seconds (default: 600) |
307
+ | `-o` / `--output` | Save output to file |
308
+
309
+ ### `tvly research status`
310
+
311
+ Check research task status by request ID.
312
+
313
+ ### `tvly research poll`
314
+
315
+ Poll until completion and return results. Same `--poll-interval`, `--timeout`, `-o` options as `run`.
316
+
317
+ ## Environment Variables
318
+
319
+ | Variable | Description |
320
+ |----------|-------------|
321
+ | `TAVILY_API_KEY` | API key (highest priority, no login needed) |
322
+
323
+ ## Related
324
+
325
+ - [`tavily-python`](https://pypi.org/project/tavily-python/) — Official Tavily Python SDK
326
+ - [Tavily Docs](https://docs.tavily.com) — Full API documentation
327
+
328
+ ## License
329
+
330
+ MIT
tavily_cli-0.1.0/README.md ADDED
@@ -0,0 +1,299 @@
1
+ # Tavily CLI
2
+
3
+ CLI and agent tools for the [Tavily API](https://docs.tavily.com) — search, extract, crawl, map, and research from the command line.
4
+
5
+ > **Note:** This package provides the `tvly` command-line tool. It depends on
6
+ > [`tavily-python`](https://pypi.org/project/tavily-python/), the official Tavily Python SDK.
7
+
8
+ ## Features
9
+
10
+ - **Interactive REPL** — Run `tvly` with no arguments for a chat-like shell experience
11
+ - **CLI for Humans & AI Agents** — Rich-formatted output for humans, `--json` for agents
12
+ - **Web Search** — LLM-optimized search with domain/date filtering and relevance scoring
13
+ - **Content Extraction** — Extract clean markdown from any URL
14
+ - **Website Crawling** — Crawl sites with depth/breadth control and path filtering
15
+ - **URL Discovery** — Map all URLs on a site without content extraction
16
+ - **Deep Research** — AI-powered research with citations and structured output
17
+
18
+ ## Installation
19
+
20
+ Requires **Python 3.10+**.
21
+
22
+ ```bash
23
+ pip install tavily-cli
24
+ ```
25
+
26
+ ### From source
27
+
28
+ ```bash
29
+ git clone https://github.com/tavily-ai/tavily-cli.git
30
+ cd tavily-cli
31
+ pip install -e .
32
+ ```
33
+
34
+ ## Quick Start
35
+
36
+ ### 1. Authenticate
37
+
38
+ ```bash
39
+ # Set API key directly
40
+ tvly login --api-key tvly-YOUR_KEY
41
+
42
+ # Or use environment variable
43
+ export TAVILY_API_KEY=tvly-YOUR_KEY
44
+
45
+ # Or OAuth (opens browser)
46
+ tvly login
47
+
48
+ # Check auth status
49
+ tvly auth
50
+ ```
51
+
52
+ ### 2. Interactive Mode
53
+
54
+ ```bash
55
+ # Launch the interactive REPL
56
+ tvly
57
+ ```
58
+
59
+ This opens a chat-like shell where you can run commands without the `tvly` prefix:
60
+
61
+ ```
62
+ ❯ search "latest AI trends"
63
+ ❯ extract https://example.com
64
+ ❯ help
65
+ ```
66
+
67
+ ### 3. Search the Web
68
+
69
+ ```bash
70
+ # Basic search
71
+ tvly search "latest AI trends"
72
+
73
+ # Advanced search with filters
74
+ tvly search "quantum computing" --depth advanced --max-results 10 --time-range week
75
+
76
+ # Search specific domains
77
+ tvly search "SEC filings for Apple" --include-domains sec.gov,reuters.com
78
+
79
+ # JSON output for agents
80
+ tvly search "AI news" --json
81
+ ```
82
+
83
+ ### 4. Extract Content from URLs
84
+
85
+ ```bash
86
+ # Extract a single URL
87
+ tvly extract https://example.com/article
88
+
89
+ # Extract multiple URLs with a focus query
90
+ tvly extract https://example.com https://other.com --query "pricing information"
91
+
92
+ # Advanced extraction for JS-heavy pages
93
+ tvly extract https://spa-app.com --extract-depth advanced
94
+ ```
95
+
96
+ ### 5. Crawl a Website
97
+
98
+ ```bash
99
+ # Basic crawl
100
+ tvly crawl https://docs.example.com
101
+
102
+ # Deep crawl with filters
103
+ tvly crawl https://docs.example.com --max-depth 2 --limit 100 --select-paths "/api/.*,/guides/.*"
104
+
105
+ # Semantic focus
106
+ tvly crawl https://docs.example.com --instructions "Find authentication docs" --chunks-per-source 3
107
+
108
+ # Save pages as markdown files
109
+ tvly crawl https://docs.example.com --output-dir ./docs
110
+ ```
111
+
112
+ ### 6. Map URLs
113
+
114
+ ```bash
115
+ # Discover all URLs on a site
116
+ tvly map https://example.com
117
+
118
+ # Filter by path
119
+ tvly map https://example.com --select-paths "/blog/.*" --limit 500
120
+ ```
121
+
122
+ ### 7. Deep Research
123
+
124
+ ```bash
125
+ # Run research and wait for results
126
+ tvly research "Competitive landscape of AI code assistants"
127
+
128
+ # Use pro model for comprehensive analysis
129
+ tvly research "Electric vehicle market analysis" --model pro
130
+
131
+ # Stream results in real-time
132
+ tvly research "AI market trends" --stream
133
+
134
+ # Async: start and poll separately
135
+ tvly research "topic" --no-wait --json # returns request_id
136
+ tvly research status <request_id> --json # check status
137
+ tvly research poll <request_id> --json # wait and get result
138
+
139
+ # Structured output
140
+ tvly research "AI market size" --output-schema schema.json --json
141
+ ```
142
+
143
+ ## CLI Overview
144
+
145
+ ```
146
+ tvly
147
+ ├── (no command) # Interactive REPL
148
+ ├── login # Authenticate (OAuth or API key)
149
+ ├── logout # Clear stored credentials
150
+ ├── auth # Check authentication status
151
+ ├── search <query> # Web search
152
+ ├── extract <urls...> # Extract content from URLs
153
+ ├── crawl <url> # Crawl a website
154
+ ├── map <url> # Discover URLs (no content)
155
+ └── research <query> # Deep research (async)
156
+ ├── run <query> # Start a research task (same as above)
157
+ ├── status <id> # Check task status
158
+ └── poll <id> # Poll until completion
159
+ ```
160
+
161
+ ## Non-Interactive Mode (for AI Agents & Scripts)
162
+
163
+ All commands support `--json` output and can be fully controlled via CLI arguments.
164
+
165
+ **Auto-detection:** JSON output is automatically enabled when stdout is piped (e.g., called from Claude Code, scripts, or piped to `jq`). No need to pass `--json` explicitly.
166
+
167
+ ```bash
168
+ # Every command supports --json for structured output
169
+ tvly search "query" --json
170
+ tvly auth --json
171
+ tvly extract https://example.com --json
172
+
173
+ # Read input from stdin with "-"
174
+ echo "What is the latest funding for Anthropic?" | tvly search - --json
175
+ echo "Research question" | tvly research - --json
176
+
177
+ # Async research: launch then poll separately
178
+ tvly research "question" --no-wait --json # returns request_id
179
+ tvly research status <id> --json # check status
180
+ tvly research poll <id> --json # wait and get result
181
+
182
+ # Global options
183
+ tvly --version # show version
184
+ tvly --status # show version + auth status
185
+ tvly --status --json # structured status
186
+ ```
187
+
188
+ ### Exit Codes
189
+
190
+ | Code | Meaning |
191
+ |------|---------|
192
+ | 0 | Success |
193
+ | 2 | Invalid input / usage error |
194
+ | 3 | Authentication error |
195
+ | 4 | API error |
196
+
197
+ ## Command Reference
198
+
199
+ ### `tvly search`
200
+
201
+ | Option | Description |
202
+ |--------|-------------|
203
+ | `--depth` | `ultra-fast`, `fast`, `basic` (default), `advanced` |
204
+ | `--max-results` | Maximum results, 0-20 (default: 5) |
205
+ | `--topic` | `general` (default), `news`, `finance` |
206
+ | `--time-range` | `day`, `week`, `month`, `year` |
207
+ | `--start-date` | Results after date (YYYY-MM-DD) |
208
+ | `--end-date` | Results before date (YYYY-MM-DD) |
209
+ | `--include-domains` | Comma-separated domains to include |
210
+ | `--exclude-domains` | Comma-separated domains to exclude |
211
+ | `--country` | Boost results from country |
212
+ | `--include-answer` | Include AI answer (`basic` or `advanced`) |
213
+ | `--include-raw-content` | Include full page (`markdown` or `text`) |
214
+ | `--include-images` | Include image results |
215
+ | `--chunks-per-source` | Chunks per source (advanced/fast depth only) |
216
+ | `-o` / `--output` | Save output to file |
217
+
218
+ ### `tvly extract`
219
+
220
+ | Option | Description |
221
+ |--------|-------------|
222
+ | `--query` | Rerank chunks by relevance |
223
+ | `--chunks-per-source` | Chunks per source (1-5, requires `--query`) |
224
+ | `--extract-depth` | `basic` (default) or `advanced` |
225
+ | `--format` | `markdown` (default) or `text` |
226
+ | `--include-images` | Include image URLs |
227
+ | `--timeout` | Max wait (1-60 seconds) |
228
+ | `-o` / `--output` | Save output to file |
229
+
230
+ ### `tvly crawl`
231
+
232
+ | Option | Description |
233
+ |--------|-------------|
234
+ | `--max-depth` | Levels deep (1-5, default: 1) |
235
+ | `--max-breadth` | Links per page (default: 20) |
236
+ | `--limit` | Total pages cap (default: 50) |
237
+ | `--instructions` | Natural language guidance |
238
+ | `--chunks-per-source` | Chunks per page (1-5, requires `--instructions`) |
239
+ | `--extract-depth` | `basic` or `advanced` |
240
+ | `--format` | `markdown` or `text` |
241
+ | `--select-paths` | Regex patterns for paths to include |
242
+ | `--exclude-paths` | Regex patterns for paths to exclude |
243
+ | `--select-domains` | Regex for domains to include |
244
+ | `--exclude-domains` | Regex for domains to exclude |
245
+ | `--allow-external` | Include external links (default: true) |
246
+ | `--include-images` | Include images |
247
+ | `--timeout` | Max wait (10-150 seconds) |
248
+ | `-o` / `--output` | Save JSON to file |
249
+ | `--output-dir` | Save each page as .md file in directory |
250
+
251
+ ### `tvly map`
252
+
253
+ | Option | Description |
254
+ |--------|-------------|
255
+ | `--max-depth` | Levels deep (1-5, default: 1) |
256
+ | `--max-breadth` | Links per page (default: 20) |
257
+ | `--limit` | Max URLs to discover (default: 50) |
258
+ | `--instructions` | Natural language guidance |
259
+ | `--select-paths` | Regex patterns for paths to include |
260
+ | `--exclude-paths` | Regex patterns for paths to exclude |
261
+ | `--allow-external` | Include external links |
262
+ | `--timeout` | Max wait (10-150 seconds) |
263
+ | `-o` / `--output` | Save output to file |
264
+
265
+ ### `tvly research <query>` / `tvly research run <query>`
266
+
267
+ | Option | Description |
268
+ |--------|-------------|
269
+ | `--model` | `mini`, `pro`, or `auto` (default) |
270
+ | `--no-wait` | Return request_id immediately |
271
+ | `--stream` | Stream results in real-time |
272
+ | `--output-schema` | Path to JSON schema file |
273
+ | `--citation-format` | `numbered`, `mla`, `apa`, `chicago` |
274
+ | `--poll-interval` | Seconds between checks (default: 10) |
275
+ | `--timeout` | Max wait seconds (default: 600) |
276
+ | `-o` / `--output` | Save output to file |
277
+
278
+ ### `tvly research status`
279
+
280
+ Check research task status by request ID.
281
+
282
+ ### `tvly research poll`
283
+
284
+ Poll until completion and return results. Same `--poll-interval`, `--timeout`, `-o` options as `run`.
285
+
286
+ ## Environment Variables
287
+
288
+ | Variable | Description |
289
+ |----------|-------------|
290
+ | `TAVILY_API_KEY` | API key (highest priority, no login needed) |
291
+
292
+ ## Related
293
+
294
+ - [`tavily-python`](https://pypi.org/project/tavily-python/) — Official Tavily Python SDK
295
+ - [Tavily Docs](https://docs.tavily.com) — Full API documentation
296
+
297
+ ## License
298
+
299
+ MIT