Metadata-Version: 2.5
Name: flashdata-youtube-metadata
Version: 0.1.0
Summary: Inspect video metadata and chapters before ingestion with the FlashData JSON CLI
Project-URL: Homepage, https://flashdata.dev/docs/sources/youtube_metadata
Project-URL: Documentation, https://flashdata.dev/docs/sources/youtube_metadata
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-metadata
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 Metadata CLI — FlashData

Inspect video metadata and chapters before ingestion. This command calls the `youtube_metadata` API and returns JSON for your
shell script, data pipeline or agent tool runner. It does not invoke a language model.

Metadata is not media download. Chapters and optional fields may be absent.

## Install and run

Requires Python 3.10 or newer. [uv installation](https://docs.astral.sh/uv/getting-started/installation/)
provides `uvx`, which runs this package in an isolated environment.

1. [Create a FlashData account](https://flashdata.dev/signup), obtain an API Key and fund Credits.
2. Set `FLASHDATA_API_KEY` using your shell or secret manager. The CLI does not accept a key flag
   or persist credentials. [Authentication and source documentation](https://flashdata.dev/docs/sources/youtube_metadata).
3. Run this example after reviewing the input and cost:

```sh
uvx flashdata-youtube-metadata@0.1.0 --video-id dQw4w9WgXcQ --options-json '{"include_formats": false, "include_chapters": true}' --output result.json
```

`--output` creates a new file with owner-only permissions where supported and refuses existing
files before making a paid request. Without it, the full JSON response goes to stdout. Errors
go to stderr. Exit 0 means the response was exported, 2 means local input/configuration failure,
and 1 means request or output failure. For downloads, exit 0 can describe an unfinished job.

For repeated use, install `uv tool install flashdata-youtube-metadata==0.1.0`; the command name is `flashdata-youtube-metadata`.
Alternatively use `python -m pip install flashdata-youtube-metadata==0.1.0` in your virtual environment.

## Inputs and output

Use `--video-id` for the primary input. Additional options use
`--options-json` as a JSON object, with strict field/type/range validation. Source is fixed by
this package. Google count and locale options remain omitted unless supplied.

| Option | Meaning |
| --- | --- |
| `include_chapters` | Include available video chapters. Default: `true`. |
| `include_formats` | Include available format metadata. Default: `true`. |

Run `uvx flashdata-youtube-metadata@0.1.0 --schema` to inspect all fields, nested filters, allowed values and
defaults without a Key or an API call. `--help` and `--version` are also local-only.

The JSON output preserves the API result envelope and optional fields: results[]: videoId, title, channel, duration and other available metadata; usage.credits.
Missing fields remain missing; empty results remain empty. No article text, translated captions,
model conclusions, rights grants or keyword volumes are invented. Exact source contracts are
documented [here](https://flashdata.dev/docs/sources/youtube_metadata).

## Fees and failure handling

This MIT-licensed CLI is free to install. FlashData API requests consume paid Credits;
[current pricing](https://flashdata.dev/pricing) applies. Extended YouTube Search has a separate
rate. Media delivery is billed by delivered volume, and your cloud-storage costs are separate.
There is no automatic pagination, retry, polling, scheduled execution or model call.

Each HTTP request has a 120-second network timeout (15-second connect timeout) and a 20-MiB response
limit. A timeout or failure may occur after a paid request has been accepted. Check Jobs in
the [FlashData console](https://flashdata.dev) before resubmitting. HTTP 401 means check the Key;
402 means insufficient Credits; 429 means rate/quota limit. A partial output file is retained
on failure. Do not retry a paid query just because output handling failed.

Input values and your API Key are sent to FlashData to perform the request. A completed
download-result read may fetch a signed JSON object from the result origin returned by
FlashData; the API Key is never sent to that object URL. Only process data appropriate for
your output destination. [Privacy policy](https://flashdata.dev/legal/privacy).

Source and MIT license are included in the source distribution.

[Source documentation](https://flashdata.dev/docs/sources/youtube_metadata) ·
[Pricing](https://flashdata.dev/pricing) · [Sign up](https://flashdata.dev/signup)
