tavily-cli 0.1.7__tar.gz → 0.2.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 (36) hide show
  1. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/PKG-INFO +237 -31
  2. tavily_cli-0.2.0/README.md +566 -0
  3. tavily_cli-0.2.0/install.sh +194 -0
  4. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/pyproject.toml +1 -1
  5. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/tavily_cli/cli.py +9 -1
  6. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/tavily_cli/commands/crawl.py +6 -2
  7. tavily_cli-0.2.0/tavily_cli/commands/defaults.py +256 -0
  8. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/tavily_cli/commands/extract.py +7 -1
  9. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/tavily_cli/commands/init.py +6 -2
  10. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/tavily_cli/commands/map_cmd.py +6 -2
  11. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/tavily_cli/commands/research.py +5 -3
  12. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/tavily_cli/commands/search.py +59 -11
  13. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/tavily_cli/commands/update.py +28 -2
  14. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/tavily_cli/common.py +43 -10
  15. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/tavily_cli/init_skills.py +96 -26
  16. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/tavily_cli/output.py +106 -8
  17. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/tavily_cli/repl.py +11 -6
  18. tavily_cli-0.2.0/tests/test_cli.py +47 -0
  19. tavily_cli-0.2.0/tests/test_defaults.py +141 -0
  20. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/tests/test_init.py +81 -6
  21. tavily_cli-0.2.0/tests/test_install_sh.py +459 -0
  22. tavily_cli-0.2.0/tests/test_output.py +141 -0
  23. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/tests/test_update.py +93 -1
  24. tavily_cli-0.1.7/README.md +0 -360
  25. tavily_cli-0.1.7/install.sh +0 -93
  26. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/.gitignore +0 -0
  27. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/LICENSE +0 -0
  28. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/tavily_cli/__init__.py +0 -0
  29. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/tavily_cli/commands/__init__.py +0 -0
  30. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/tavily_cli/commands/auth.py +0 -0
  31. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/tavily_cli/config.py +0 -0
  32. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/tavily_cli/keyless.py +0 -0
  33. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/tavily_cli/mcp_client.py +0 -0
  34. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/tavily_cli/oauth.py +0 -0
  35. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/tavily_cli/theme.py +0 -0
  36. {tavily_cli-0.1.7 → tavily_cli-0.2.0}/tests/test_oauth.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: tavily-cli
3
- Version: 0.1.7
3
+ Version: 0.2.0
4
4
  Summary: CLI and agent tools for the Tavily API — search, extract, crawl, map, and research from the command line.
5
5
  Project-URL: Homepage, https://tavily.com
6
6
  Project-URL: Documentation, https://docs.tavily.com
@@ -44,8 +44,9 @@ CLI and agent tools for the [Tavily API](https://docs.tavily.com) — search, ex
44
44
 
45
45
  ## Features
46
46
 
47
+ - **One-Command Setup** — Authenticate, install Tavily skills for supported agents, and verify a live search
47
48
  - **Interactive REPL** — Run `tvly` with no arguments for a chat-like shell experience
48
- - **CLI for Humans & AI Agents** — Rich-formatted output for humans, `--json` for agents
49
+ - **CLI for Humans & AI Agents** — Rich-formatted output in a terminal, plain text when piped or run by an agent, and `--json` for structured output
49
50
  - **Web Search** — LLM-optimized search with domain/date filtering and relevance scoring
50
51
  - **Content Extraction** — Extract clean markdown from any URL
51
52
  - **Website Crawling** — Crawl sites with depth/breadth control and path filtering
@@ -57,10 +58,34 @@ CLI and agent tools for the [Tavily API](https://docs.tavily.com) — search, ex
57
58
 
58
59
  Requires **Python 3.10+**.
59
60
 
61
+ ### Guided installer
62
+
60
63
  ```bash
64
+ curl -fsSL https://raw.githubusercontent.com/tavily-ai/tavily-cli/main/install.sh | sh
65
+ ```
66
+
67
+ On a fresh interactive desktop installation, the installer starts `tvly init`
68
+ to guide authentication, agent detection, skill installation, and verification.
69
+ In CI, SSH/headless, and other non-interactive environments, run `tvly init`
70
+ separately with the [appropriate setup options](#non-interactive-mode-for-ai-agents--scripts).
71
+
72
+ ### Package manager
73
+
74
+ Choose the package manager you use:
75
+
76
+ ```bash
77
+ # uv
78
+ uv tool install tavily-cli
79
+
80
+ # pipx
81
+ pipx install tavily-cli
82
+
83
+ # pip (inside a virtual environment)
61
84
  pip install tavily-cli
62
85
  ```
63
86
 
87
+ Then run `tvly init` to complete setup.
88
+
64
89
  ### From source
65
90
 
66
91
  ```bash
@@ -83,26 +108,77 @@ Source and direct-URL installations are detected and must be updated from their
83
108
 
84
109
  ## Quick Start
85
110
 
86
- ### Keyless mode
111
+ ### Initialize Tavily
87
112
 
88
- `tvly search` and `tvly extract` work without an API key — try them right
89
- after installing. A fair-use rate-limit cap applies; when reached, the CLI
90
- prints a clear message with sign-up and continuation options. All other
91
- commands (`crawl`, `map`, `research`) require a key.
113
+ The guided installer starts setup automatically on a fresh interactive desktop
114
+ installation. After a package-manager, source, or non-interactive install, run:
115
+
116
+ ```bash
117
+ tvly init
118
+ tvly search "latest AI trends"
119
+ ```
120
+
121
+ `tvly init` guides you through:
122
+
123
+ 1. **Authentication:** reuse an existing credential or sign in through browser OAuth.
124
+ 2. **Agent setup:** detect Claude Code, Codex, and Cursor and install Tavily's eight core agent skills.
125
+ 3. **Verification:** check the CLI and installed skills, then run a live search.
126
+
127
+ When Node.js is available, skills are installed with the
128
+ [skills.sh CLI](https://skills.sh) (`npx skills add tavily-ai/skills`). Without
129
+ Node.js, `tvly init` installs the skills pinned to your CLI release instead.
130
+ Restart your agent after new skills are installed.
131
+
132
+ ```bash
133
+ # Set up one or more supported agents
134
+ tvly init --agent codex
135
+ tvly init --agent claude-code --agent cursor
136
+
137
+ # Set up every detected agent without the agent-selection prompt
138
+ tvly init --all --yes
139
+
140
+ # Authenticate with an API key instead of OAuth
141
+ tvly init --api-key tvly-YOUR_KEY
142
+
143
+ # Install skills and verify keyless search if no credential is configured
144
+ tvly init --skip-auth
145
+
146
+ # Authenticate and verify the CLI without installing agent skills
147
+ tvly init --skip-skills
148
+ ```
149
+
150
+ Skills are installed in `~/.agents/skills`, which Codex and Cursor load
151
+ directly; Claude Code gets links in `~/.claude/skills`. If no supported agent
152
+ is detected, setup still installs the shared skills.
153
+ Rerunning `tvly init` updates existing skills to the latest published version
154
+ (or, without Node.js, to the version pinned by your CLI release). You can also
155
+ run `npx skills update` at any time.
156
+
157
+ ### Try search and extract without signing in
158
+
159
+ You can skip setup and run `tvly search` or `tvly extract` immediately after
160
+ installation. When no credential is configured, these commands use keyless
161
+ access with a fair-use rate-limit cap.
92
162
 
93
163
  ```bash
94
- pip install tavily-cli
95
164
  tvly search "latest AI trends"
96
165
  tvly extract https://example.com
97
166
  ```
98
167
 
99
- ### 1. Authenticate
168
+ If you reach the cap, the CLI prints continuation options. Run `tvly login`
169
+ to authenticate, then retry your command. `crawl`, `map`, and `research`
170
+ require authentication.
171
+
172
+ ### Manage authentication
173
+
174
+ Use `tvly login` when you only want to manage authentication without running
175
+ the full setup and agent-skill installation:
100
176
 
101
177
  ```bash
102
178
  # Browser OAuth (no Node.js required)
103
179
  tvly login
104
180
 
105
- # Headless / SSH: print the URL instead of opening a browser
181
+ # Print the OAuth URL and wait for authorization
106
182
  tvly login --no-browser
107
183
 
108
184
  # Or set API key directly
@@ -113,9 +189,24 @@ export TAVILY_API_KEY=tvly-YOUR_KEY
113
189
 
114
190
  # Check auth status
115
191
  tvly auth
192
+
193
+ # Revoke stored OAuth tokens and clear saved credentials
194
+ tvly logout
116
195
  ```
117
196
 
118
- ### 2. Interactive Mode
197
+ `--no-browser` is also available on `tvly init`. It prints the login URL but
198
+ still waits for a callback to `127.0.0.1` on the machine running the CLI.
199
+ For SSH sessions, arrange port forwarding or use an API key; for CI, supply
200
+ `TAVILY_API_KEY` through your secret manager. `tvly logout` cannot unset an
201
+ environment variable, so unset `TAVILY_API_KEY` separately if needed.
202
+
203
+ For the full API option set, use API-key authentication. Browser OAuth uses
204
+ Tavily's MCP endpoint, where some CLI options and research operations have
205
+ [known compatibility gaps](https://github.com/tavily-ai/tavily-cli/issues/24).
206
+
207
+ ## Examples
208
+
209
+ ### Interactive Mode
119
210
 
120
211
  ```bash
121
212
  # Launch the interactive REPL
@@ -130,7 +221,7 @@ This opens a chat-like shell where you can run commands without the `tvly` prefi
130
221
  ❯ help
131
222
  ```
132
223
 
133
- ### 3. Search the Web
224
+ ### Search the Web
134
225
 
135
226
  ```bash
136
227
  # Basic search
@@ -142,14 +233,20 @@ tvly search "quantum computing" --depth advanced --max-results 10 --time-range w
142
233
  # Search specific domains
143
234
  tvly search "SEC filings for Apple" --include-domains sec.gov,reuters.com
144
235
 
145
- # JSON output for agents
236
+ # Several queries at once, run in parallel with the same options
237
+ tvly search "Rust 2024 edition release date" "Rust 1.85 release notes" --depth advanced
238
+
239
+ # Longer snippets (0 prints each result's content whole)
240
+ tvly search "AI news" --max-chars 1500
241
+
242
+ # JSON output
146
243
  tvly search "AI news" --json
147
244
 
148
245
  # Set client_name for attribution
149
246
  tvly search "latest AI news" --client-name x
150
247
  ```
151
248
 
152
- ### 4. Extract Content from URLs
249
+ ### Extract Content from URLs
153
250
 
154
251
  ```bash
155
252
  # Extract a single URL
@@ -162,7 +259,7 @@ tvly extract https://example.com https://other.com --query "pricing information"
162
259
  tvly extract https://spa-app.com --extract-depth advanced
163
260
  ```
164
261
 
165
- ### 5. Crawl a Website
262
+ ### Crawl a Website
166
263
 
167
264
  ```bash
168
265
  # Basic crawl
@@ -171,14 +268,14 @@ tvly crawl https://docs.example.com
171
268
  # Deep crawl with filters
172
269
  tvly crawl https://docs.example.com --max-depth 2 --limit 100 --select-paths "/api/.*,/guides/.*"
173
270
 
174
- # Semantic focus
271
+ # Semantic focus with per-page chunks (API-key authentication)
175
272
  tvly crawl https://docs.example.com --instructions "Find authentication docs" --chunks-per-source 3
176
273
 
177
274
  # Save pages as markdown files
178
275
  tvly crawl https://docs.example.com --output-dir ./docs
179
276
  ```
180
277
 
181
- ### 6. Map URLs
278
+ ### Map URLs
182
279
 
183
280
  ```bash
184
281
  # Discover all URLs on a site
@@ -188,7 +285,10 @@ tvly map https://example.com
188
285
  tvly map https://example.com --select-paths "/blog/.*" --limit 500
189
286
  ```
190
287
 
191
- ### 7. Deep Research
288
+ ### Deep Research
289
+
290
+ Use API-key authentication for streaming, structured output, and async
291
+ research. Replace `REQUEST_ID` with the ID returned by your research request.
192
292
 
193
293
  ```bash
194
294
  # Run research and wait for results
@@ -202,18 +302,56 @@ tvly research "AI market trends" --stream
202
302
 
203
303
  # Async: start and poll separately
204
304
  tvly research "topic" --no-wait --json # returns request_id
205
- tvly research status <request_id> --json # check status
206
- tvly research poll <request_id> --json # wait and get result
305
+ tvly research status REQUEST_ID --json # check status
306
+ tvly research poll REQUEST_ID --json # wait and get result
207
307
 
208
308
  # Structured output
209
309
  tvly research "AI market size" --output-schema schema.json --json
210
310
  ```
211
311
 
312
+ ### Output in Pipes and Agent Shells
313
+
314
+ When stdout is not a terminal, such as in a pipe, a redirect or a coding agent's
315
+ shell, commands print plain text with no styling or line wrapping:
316
+
317
+ - `search` prints each result's title, full URL and the first 600 characters of
318
+ its content on one line. `--max-chars` changes the length, and `0` prints the
319
+ content whole. Several queries in one command share the 600 characters.
320
+ - `extract` and `crawl` print each page in full, as `# <url>` followed by its
321
+ content, with links kept.
322
+ - `map` prints one URL per line, and `research` prints the report followed by
323
+ its sources.
324
+
325
+ `--json` output is unchanged.
326
+
327
+ ### Save Results
328
+
329
+ `--output` writes the structured JSON response, regardless of the filename
330
+ extension, and creates the folder if it doesn't exist. With no value, `-o`
331
+ saves under `.tavily/` with a generated name, such as
332
+ `.tavily/search-ai-news-142310-3f9a1c.json`, and prints the path. A new `.tavily/`
333
+ folder gets its own `.gitignore`, so saved results stay out of git. Nothing is
334
+ saved without `-o`. When stdout is not
335
+ a terminal, `search --output` still prints the results, so you can skim them and
336
+ read the saved file for more. For extraction, `--format markdown` controls the
337
+ content inside that response; it does not turn the output file into plain
338
+ Markdown.
339
+
340
+ ```bash
341
+ tvly search "AI news" -o
342
+ tvly search "AI news" --output results/ai-news.json
343
+ tvly extract https://example.com --format markdown --output extracted.json
344
+
345
+ # Save individual crawled pages as Markdown files
346
+ tvly crawl https://docs.example.com --output-dir ./docs
347
+ ```
348
+
212
349
  ## CLI Overview
213
350
 
214
351
  ```
215
352
  tvly
216
353
  ├── (no command) # Interactive REPL
354
+ ├── init # Guided auth, agent skills, and verification
217
355
  ├── login # Authenticate (OAuth or API key)
218
356
  ├── logout # Clear stored credentials
219
357
  ├── auth # Check authentication status
@@ -222,15 +360,34 @@ tvly
222
360
  ├── crawl <url> # Crawl a website
223
361
  ├── map <url> # Discover URLs (no content)
224
362
  ├── update # Check for or install CLI updates
225
- └── research <query> # Deep research (async)
226
- ├── run <query> # Start a research task (same as above)
227
- ├── status <id> # Check task status
228
- └── poll <id> # Poll until completion
363
+ ├── set-default # Disable built-in web search in Claude Code/Codex
364
+ ├── unset-default # Restore built-in web search in Claude Code/Codex
365
+ ├── research <query> # Deep research (async)
366
+ │ ├── run <query> # Start a research task (same as above)
367
+ │ ├── status <id> # Check task status
368
+ │ └── poll <id> # Poll until completion
229
369
  ```
230
370
 
231
371
  ## Non-Interactive Mode (for AI Agents & Scripts)
232
372
 
233
- All commands support `--json` output and can be fully controlled via CLI arguments.
373
+ Use `--json` for structured output. For unattended setup, provide a credential
374
+ through `TAVILY_API_KEY` or choose `--skip-auth` for keyless search and extract.
375
+ `--yes` accepts agent selection; it does not complete browser authentication.
376
+
377
+ ```bash
378
+ # With TAVILY_API_KEY already supplied by your environment
379
+ tvly init --all --yes --json
380
+
381
+ # Keyless setup for Codex when no credential is configured
382
+ tvly init --agent codex --skip-auth --yes --json
383
+
384
+ # Verify the CLI without installing skills (uses existing credentials, if any)
385
+ tvly init --skip-auth --skip-skills --json
386
+ ```
387
+
388
+ Setup JSON includes `ok`, `mode`, `auth`, `skills`, and `verification`. On
389
+ failure, `error.stage` identifies the failed step. Setup always performs a
390
+ live search, so it needs network access even with `--skip-skills`.
234
391
 
235
392
  ```bash
236
393
  # Every command supports --json for structured output
@@ -245,8 +402,8 @@ echo "Research question" | tvly research - --json
245
402
 
246
403
  # Async research: launch then poll separately
247
404
  tvly research "question" --no-wait --json # returns request_id
248
- tvly research status <id> --json # check status
249
- tvly research poll <id> --json # wait and get result
405
+ tvly research status REQUEST_ID --json # check status
406
+ tvly research poll REQUEST_ID --json # wait and get result
250
407
 
251
408
  # Global options
252
409
  tvly --version # show version
@@ -261,11 +418,31 @@ tvly --status --json # structured status
261
418
  | 0 | Success |
262
419
  | 1 | Local setup or update error |
263
420
  | 2 | Invalid input / usage error |
264
- | 3 | Authentication error |
265
- | 4 | API or update-check error |
421
+ | 3 | Authentication failure, keyless rate-limit cap, or handled API usage/plan limit |
422
+ | 4 | API error, setup live-search failure, or update-check error |
266
423
 
267
424
  ## Command Reference
268
425
 
426
+ ### `tvly init`
427
+
428
+ Run first-time setup, install or update the Tavily skills (through
429
+ `npx skills` when Node.js is available), and verify the CLI with a live search.
430
+
431
+ | Option | Description |
432
+ |--------|-------------|
433
+ | `--agent` | Install skills for `claude-code`, `codex`, or `cursor`; repeat to select more than one |
434
+ | `--all` | Install skills for every detected agent |
435
+ | `--yes` | Accept detected agents without prompting |
436
+ | `--skip-auth` | Skip login when no credential is configured; existing credentials are still used |
437
+ | `--skip-skills` | Skip agent-skill installation and updates |
438
+ | `--api-key` | Authenticate with an API key instead of OAuth |
439
+ | `--browser` / `--no-browser` | Open OAuth in a browser or print the URL; both require the local callback |
440
+ | `--json` | Return structured setup and verification results |
441
+
442
+ Use either `--all` or `--agent`. `--skip-auth` and `--api-key` cannot be
443
+ combined. `--json` selects detected agents without prompting, but does not
444
+ skip authentication.
445
+
269
446
  ### `tvly search`
270
447
 
271
448
  | Option | Description |
@@ -282,10 +459,17 @@ tvly --status --json # structured status
282
459
  | `--include-answer` | Include AI answer (`basic` or `advanced`) |
283
460
  | `--include-raw-content` | Include full page (`markdown` or `text`) |
284
461
  | `--include-images` | Include image results |
462
+ | `--include-image-descriptions` | Include AI image descriptions |
285
463
  | `--chunks-per-source` | Chunks per source (advanced/fast depth only) |
286
- | `-o` / `--output` | Save output to file |
464
+ | `--max-chars` | Characters of each result's content to print (default 600, shared across queries; `0` for all) |
465
+ | `-o` / `--output` | Save the full JSON response to file; with no value, under `.tavily/` |
287
466
  | `--client-name` | Set optional `client_name` for request attribution |
288
467
 
468
+ `tvly search` accepts up to 5 queries and runs them in parallel with the same
469
+ options. Each query's results print under its own `=== [i/n] <query>` header;
470
+ with `--json`, the output is a list of responses in query order. A query that
471
+ fails reports its error without stopping the others.
472
+
289
473
  ### `tvly update`
290
474
 
291
475
  Check PyPI for the latest Tavily CLI release and update through the package
@@ -298,7 +482,8 @@ tvly update --check --json
298
482
  ```
299
483
 
300
484
  `--check` is read-only. Source/direct-URL installations are reported without
301
- being modified.
485
+ being modified. JSON output includes `can_update` and `blocked_reason` so
486
+ automation can distinguish an available release from a supported self-update.
302
487
 
303
488
  ### `tvly extract`
304
489
 
@@ -345,6 +530,8 @@ being modified.
345
530
  | `--instructions` | Natural language guidance |
346
531
  | `--select-paths` | Regex patterns for paths to include |
347
532
  | `--exclude-paths` | Regex patterns for paths to exclude |
533
+ | `--select-domains` | Regex patterns for domains to include |
534
+ | `--exclude-domains` | Regex patterns for domains to exclude |
348
535
  | `--allow-external` | Include external links |
349
536
  | `--timeout` | Max wait (10-150 seconds) |
350
537
  | `-o` / `--output` | Save output to file |
@@ -372,6 +559,25 @@ Check research task status by request ID. Supports `--client-name`.
372
559
 
373
560
  Poll until completion and return results. Same `--poll-interval`, `--timeout`, `-o`, and `--client-name` options as `run`.
374
561
 
562
+ ### `tvly set-default` / `tvly unset-default`
563
+
564
+ Make Tavily the default web tool for your coding agents by disabling their
565
+ built-in web search. Without flags, you are prompted for each agent.
566
+ `unset-default` undoes `set-default`, but doesn't restore values you had set
567
+ yourself for these settings before running it.
568
+
569
+ | Option | Description |
570
+ |--------|-------------|
571
+ | `--claude` | Add `WebSearch` and `WebFetch` to `permissions.deny` in `~/.claude/settings.json` (or `$CLAUDE_CONFIG_DIR`) |
572
+ | `--codex` | Set `web_search = "disabled"` in `~/.codex/config.toml` (or `$CODEX_HOME`) |
573
+ | `--project` | Apply to the current directory instead: `.claude/settings.local.json` and `.codex/config.toml` (Codex reads project config only in trusted projects) |
574
+
575
+ ```bash
576
+ tvly set-default --claude --codex
577
+ tvly unset-default --codex
578
+ tvly set-default --claude --project
579
+ ```
580
+
375
581
  ## Environment Variables
376
582
 
377
583
  | Variable | Description |