Metadata-Version: 2.5
Name: flashdata-youtube-metadata
Version: 0.1.1
Summary: Get YouTube video metadata, statistics and available chapters or format details as JSON from the command line.
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

Get YouTube video metadata, statistics and available chapters or format details as JSON from the command line.

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

## Installation

Requires Python 3.10 or newer:

```sh
python -m pip install flashdata-youtube-metadata==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-metadata`.

## Quick start

Create a [FlashData API key](https://flashdata.dev/app/api-keys) with `youtube_metadata` 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-metadata@0.1.1 --video-id dQw4w9WgXcQ --options-json '{"include_formats": false, "include_chapters": true}' --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 `--video-id` for the primary input. Pass additional fields through
`--options-json`. Options are validated against this package's source schema.

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

Inspect all fields, nested filters and defaults locally:

```sh
uvx flashdata-youtube-metadata@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[]: videoId, title, channel, duration and other available metadata; usage.credits.

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

## 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_metadata) ·
[Privacy policy](https://flashdata.dev/legal/privacy) ·
[Source code](https://github.com/rocosen/flashdata-mcp/tree/main/packages/python-cli)
