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