tavily-cli 0.1.8__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 (34) hide show
  1. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/PKG-INFO +223 -31
  2. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/README.md +222 -30
  3. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/pyproject.toml +1 -1
  4. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tavily_cli/cli.py +3 -0
  5. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tavily_cli/commands/crawl.py +6 -2
  6. tavily_cli-0.2.0/tavily_cli/commands/defaults.py +256 -0
  7. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tavily_cli/commands/extract.py +7 -1
  8. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tavily_cli/commands/init.py +6 -2
  9. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tavily_cli/commands/map_cmd.py +6 -2
  10. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tavily_cli/commands/research.py +5 -3
  11. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tavily_cli/commands/search.py +59 -11
  12. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tavily_cli/common.py +43 -10
  13. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tavily_cli/init_skills.py +96 -26
  14. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tavily_cli/output.py +106 -8
  15. tavily_cli-0.2.0/tests/test_defaults.py +141 -0
  16. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tests/test_init.py +81 -6
  17. tavily_cli-0.2.0/tests/test_output.py +141 -0
  18. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/.gitignore +0 -0
  19. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/LICENSE +0 -0
  20. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/install.sh +0 -0
  21. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tavily_cli/__init__.py +0 -0
  22. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tavily_cli/commands/__init__.py +0 -0
  23. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tavily_cli/commands/auth.py +0 -0
  24. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tavily_cli/commands/update.py +0 -0
  25. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tavily_cli/config.py +0 -0
  26. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tavily_cli/keyless.py +0 -0
  27. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tavily_cli/mcp_client.py +0 -0
  28. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tavily_cli/oauth.py +0 -0
  29. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tavily_cli/repl.py +0 -0
  30. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tavily_cli/theme.py +0 -0
  31. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tests/test_cli.py +0 -0
  32. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tests/test_install_sh.py +0 -0
  33. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tests/test_oauth.py +0 -0
  34. {tavily_cli-0.1.8 → tavily_cli-0.2.0}/tests/test_update.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: tavily-cli
3
- Version: 0.1.8
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
@@ -66,14 +67,25 @@ curl -fsSL https://raw.githubusercontent.com/tavily-ai/tavily-cli/main/install.s
66
67
  On a fresh interactive desktop installation, the installer starts `tvly init`
67
68
  to guide authentication, agent detection, skill installation, and verification.
68
69
  In CI, SSH/headless, and other non-interactive environments, run `tvly init`
69
- separately after installation.
70
+ separately with the [appropriate setup options](#non-interactive-mode-for-ai-agents--scripts).
70
71
 
71
72
  ### Package manager
72
73
 
74
+ Choose the package manager you use:
75
+
73
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)
74
84
  pip install tavily-cli
75
85
  ```
76
86
 
87
+ Then run `tvly init` to complete setup.
88
+
77
89
  ### From source
78
90
 
79
91
  ```bash
@@ -96,26 +108,77 @@ Source and direct-URL installations are detected and must be updated from their
96
108
 
97
109
  ## Quick Start
98
110
 
99
- ### Keyless mode
111
+ ### Initialize Tavily
100
112
 
101
- `tvly search` and `tvly extract` work without an API key — try them right
102
- after installing. A fair-use rate-limit cap applies; when reached, the CLI
103
- prints a clear message with sign-up and continuation options. All other
104
- 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.
105
162
 
106
163
  ```bash
107
- pip install tavily-cli
108
164
  tvly search "latest AI trends"
109
165
  tvly extract https://example.com
110
166
  ```
111
167
 
112
- ### 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:
113
176
 
114
177
  ```bash
115
178
  # Browser OAuth (no Node.js required)
116
179
  tvly login
117
180
 
118
- # Headless / SSH: print the URL instead of opening a browser
181
+ # Print the OAuth URL and wait for authorization
119
182
  tvly login --no-browser
120
183
 
121
184
  # Or set API key directly
@@ -126,9 +189,24 @@ export TAVILY_API_KEY=tvly-YOUR_KEY
126
189
 
127
190
  # Check auth status
128
191
  tvly auth
192
+
193
+ # Revoke stored OAuth tokens and clear saved credentials
194
+ tvly logout
129
195
  ```
130
196
 
131
- ### 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
132
210
 
133
211
  ```bash
134
212
  # Launch the interactive REPL
@@ -143,7 +221,7 @@ This opens a chat-like shell where you can run commands without the `tvly` prefi
143
221
  ❯ help
144
222
  ```
145
223
 
146
- ### 3. Search the Web
224
+ ### Search the Web
147
225
 
148
226
  ```bash
149
227
  # Basic search
@@ -155,14 +233,20 @@ tvly search "quantum computing" --depth advanced --max-results 10 --time-range w
155
233
  # Search specific domains
156
234
  tvly search "SEC filings for Apple" --include-domains sec.gov,reuters.com
157
235
 
158
- # 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
159
243
  tvly search "AI news" --json
160
244
 
161
245
  # Set client_name for attribution
162
246
  tvly search "latest AI news" --client-name x
163
247
  ```
164
248
 
165
- ### 4. Extract Content from URLs
249
+ ### Extract Content from URLs
166
250
 
167
251
  ```bash
168
252
  # Extract a single URL
@@ -175,7 +259,7 @@ tvly extract https://example.com https://other.com --query "pricing information"
175
259
  tvly extract https://spa-app.com --extract-depth advanced
176
260
  ```
177
261
 
178
- ### 5. Crawl a Website
262
+ ### Crawl a Website
179
263
 
180
264
  ```bash
181
265
  # Basic crawl
@@ -184,14 +268,14 @@ tvly crawl https://docs.example.com
184
268
  # Deep crawl with filters
185
269
  tvly crawl https://docs.example.com --max-depth 2 --limit 100 --select-paths "/api/.*,/guides/.*"
186
270
 
187
- # Semantic focus
271
+ # Semantic focus with per-page chunks (API-key authentication)
188
272
  tvly crawl https://docs.example.com --instructions "Find authentication docs" --chunks-per-source 3
189
273
 
190
274
  # Save pages as markdown files
191
275
  tvly crawl https://docs.example.com --output-dir ./docs
192
276
  ```
193
277
 
194
- ### 6. Map URLs
278
+ ### Map URLs
195
279
 
196
280
  ```bash
197
281
  # Discover all URLs on a site
@@ -201,7 +285,10 @@ tvly map https://example.com
201
285
  tvly map https://example.com --select-paths "/blog/.*" --limit 500
202
286
  ```
203
287
 
204
- ### 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.
205
292
 
206
293
  ```bash
207
294
  # Run research and wait for results
@@ -215,18 +302,56 @@ tvly research "AI market trends" --stream
215
302
 
216
303
  # Async: start and poll separately
217
304
  tvly research "topic" --no-wait --json # returns request_id
218
- tvly research status <request_id> --json # check status
219
- 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
220
307
 
221
308
  # Structured output
222
309
  tvly research "AI market size" --output-schema schema.json --json
223
310
  ```
224
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
+
225
349
  ## CLI Overview
226
350
 
227
351
  ```
228
352
  tvly
229
353
  ├── (no command) # Interactive REPL
354
+ ├── init # Guided auth, agent skills, and verification
230
355
  ├── login # Authenticate (OAuth or API key)
231
356
  ├── logout # Clear stored credentials
232
357
  ├── auth # Check authentication status
@@ -235,15 +360,34 @@ tvly
235
360
  ├── crawl <url> # Crawl a website
236
361
  ├── map <url> # Discover URLs (no content)
237
362
  ├── update # Check for or install CLI updates
238
- └── research <query> # Deep research (async)
239
- ├── run <query> # Start a research task (same as above)
240
- ├── status <id> # Check task status
241
- └── 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
242
369
  ```
243
370
 
244
371
  ## Non-Interactive Mode (for AI Agents & Scripts)
245
372
 
246
- 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`.
247
391
 
248
392
  ```bash
249
393
  # Every command supports --json for structured output
@@ -258,8 +402,8 @@ echo "Research question" | tvly research - --json
258
402
 
259
403
  # Async research: launch then poll separately
260
404
  tvly research "question" --no-wait --json # returns request_id
261
- tvly research status <id> --json # check status
262
- 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
263
407
 
264
408
  # Global options
265
409
  tvly --version # show version
@@ -274,11 +418,31 @@ tvly --status --json # structured status
274
418
  | 0 | Success |
275
419
  | 1 | Local setup or update error |
276
420
  | 2 | Invalid input / usage error |
277
- | 3 | Authentication error |
278
- | 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 |
279
423
 
280
424
  ## Command Reference
281
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
+
282
446
  ### `tvly search`
283
447
 
284
448
  | Option | Description |
@@ -295,10 +459,17 @@ tvly --status --json # structured status
295
459
  | `--include-answer` | Include AI answer (`basic` or `advanced`) |
296
460
  | `--include-raw-content` | Include full page (`markdown` or `text`) |
297
461
  | `--include-images` | Include image results |
462
+ | `--include-image-descriptions` | Include AI image descriptions |
298
463
  | `--chunks-per-source` | Chunks per source (advanced/fast depth only) |
299
- | `-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/` |
300
466
  | `--client-name` | Set optional `client_name` for request attribution |
301
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
+
302
473
  ### `tvly update`
303
474
 
304
475
  Check PyPI for the latest Tavily CLI release and update through the package
@@ -359,6 +530,8 @@ automation can distinguish an available release from a supported self-update.
359
530
  | `--instructions` | Natural language guidance |
360
531
  | `--select-paths` | Regex patterns for paths to include |
361
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 |
362
535
  | `--allow-external` | Include external links |
363
536
  | `--timeout` | Max wait (10-150 seconds) |
364
537
  | `-o` / `--output` | Save output to file |
@@ -386,6 +559,25 @@ Check research task status by request ID. Supports `--client-name`.
386
559
 
387
560
  Poll until completion and return results. Same `--poll-interval`, `--timeout`, `-o`, and `--client-name` options as `run`.
388
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
+
389
581
  ## Environment Variables
390
582
 
391
583
  | Variable | Description |