Metadata-Version: 2.5
Name: flashdata-youtube-search
Version: 0.1.1
Summary: Search YouTube from the command line and get video details as JSON, with filters and up to 20 requested results.
Project-URL: Homepage, https://flashdata.dev/docs/sources/youtube_search
Project-URL: Documentation, https://flashdata.dev/docs/sources/youtube_search
Project-URL: Pricing, https://flashdata.dev/pricing
Project-URL: Support, https://flashdata.dev
Project-URL: Source, https://github.com/rocosen/flashdata-mcp/tree/main/packages/python-cli
Author-email: FlashData <support@flashdata.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,flashdata,json,uvx,youtube-search
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.28.1
Requires-Dist: jsonschema<5,>=4.23
Requires-Dist: pydantic<3,>=2.7.4
Description-Content-Type: text/markdown

# YouTube Search CLI

Search YouTube from the command line and get video details as JSON, with filters and up to 20 requested results.

Uses the [FlashData YouTube Search API](https://flashdata.dev/docs/sources/youtube_search).

## Installation

Requires Python 3.10 or newer:

```sh
python -m pip install flashdata-youtube-search==0.1.1
```

Or run it without a persistent install using [uvx](https://docs.astral.sh/uv/guides/tools/),
as in the examples below. The installed command is `flashdata-youtube-search`.

## Quick start

Create a [FlashData API key](https://flashdata.dev/app/api-keys) with `youtube_search` access,
then set `FLASHDATA_API_KEY` in your environment or secret manager. API calls use your
FlashData Credits.

```sh
export FLASHDATA_API_KEY='YOUR_API_KEY'
uvx flashdata-youtube-search@0.1.1 --query 'RAG evaluation tutorials' --options-json '{"max_results": 5}' --output result.json
```

Omit `--output` to write JSON to stdout. An output file must not already exist; the CLI
checks this before making a request. API keys are read from the environment, not command flags.

## Inputs

Use `--query` for the primary input. Pass additional fields through
`--options-json`. Options are validated against this package's source schema.

| Option | Meaning |
| --- | --- |
| `max_results` | Requested number of videos. Default: `10`. |
| `filters` | Source-specific option; see --schema. Default: `null`. |

Inspect all fields, nested filters and defaults locally:

```sh
uvx flashdata-youtube-search@0.1.1 --schema
```

`--schema`, `--help` and `--version` do not require an API key or make an API call.

## Output and limits

The JSON response preserves the API envelope and available fields: results[].results: video search records; totalResults and query; usage.credits.

The requested count is a ceiling, not a guaranteed result count. This CLI defaults to 10 requested results (maximum 20).

## Pricing and errors

This MIT-licensed CLI is free to install. API calls use your own
[FlashData Credits](https://flashdata.dev/pricing).

Requests are not automatically retried. A timeout can occur after a request is accepted;
check your FlashData query history before resubmitting. Each HTTP request has a 120-second
network timeout, a 15-second connect timeout and a 20-MiB response limit.

Errors go to stderr. Exit codes: `0` for exported output, `2` for local input/configuration
errors, and `1` for request/output errors.
A partial output file is retained on failure; check the request before retrying because of
an output error. HTTP `401` indicates an API key issue, `402` insufficient Credits, and
`429` a rate or quota limit.

[API reference](https://flashdata.dev/docs/sources/youtube_search) ·
[Privacy policy](https://flashdata.dev/legal/privacy) ·
[Source code](https://github.com/rocosen/flashdata-mcp/tree/main/packages/python-cli)
