Metadata-Version: 2.5
Name: flashdata-youtube-cloud-storage
Version: 0.1.1
Summary: Download YouTube video, audio or clips to your cloud storage, with command-line job tracking and JSON file details.
Project-URL: Homepage, https://flashdata.dev/docs/sources/youtube_download
Project-URL: Documentation, https://flashdata.dev/docs/sources/youtube_download
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-download
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 Download to Cloud Storage CLI

Download YouTube video, audio or clips to your cloud storage, with command-line job tracking and JSON file details.

Uses the [FlashData YouTube Download to Cloud Storage API](https://flashdata.dev/docs/sources/youtube_download).

## Installation

Requires Python 3.10 or newer:

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

## Quick start

Create a [FlashData API key](https://flashdata.dev/app/api-keys) with `youtube_download` 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-cloud-storage@0.1.1 --operation result --job-id job_YOUR_SAVED_ID --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

For a new delivery, use `--video-id` with `--operation submit --allow-submit`. For status or results, use only `--job-id` and omit submission fields. Pass additional fields through
`--options-json`. Options are validated against this package's source schema.

| Option | Meaning |
| --- | --- |
| `download_type` | Source-specific option; see --schema. Default: `"audio_video"`. |
| `video_quality` | Source-specific option; see --schema. Default: `null`. |
| `fps` | Source-specific option; see --schema. Default: `null`. |
| `audio_language` | Source-specific option; see --schema. Default: `null`. |
| `audio_quality` | Source-specific option; see --schema. Default: `null`. |
| `yt_dlp_format` | Source-specific option; see --schema. Default: `null`. |
| `upload_metadata` | Source-specific option; see --schema. Default: `false`. |
| `output_format` | Source-specific option; see --schema. Default: `null`. |
| `start_at` | Source-specific option; see --schema. Default: `null`. |
| `end_at` | Source-specific option; see --schema. Default: `null`. |

Inspect all fields, nested filters and defaults locally:

```sh
uvx flashdata-youtube-cloud-storage@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: submit: id/status receipt; reads: job lifecycle; completed result: output JSON delivery manifest.

Paid asynchronous job. Requires customer storage. Save the receipt; never submit again to poll. Result JSON expires after 24 hours; media retention depends on storage.

## Submit once and keep the job ID

The default operation is `status`. Status and result accept only a saved job ID,
and never submit a paid query. A pending/running response does not mean delivery is complete.

For a new delivery, supply your own authorized video and storage configuration:

```sh
uvx flashdata-youtube-cloud-storage@0.1.1 --operation submit --allow-submit \
  --video-id YOUR_VIDEO_ID \
  --options-json '{"download_type":"audio","output_format":"m4a"}' \
  --output delivery-receipt.json
```

Set `FLASHDATA_DOWNLOAD_STORAGE` through your secret manager, containing the documented
storage JSON. Never paste it into command arguments or source code. The supported providers
are s3, s3_compatible, gcs, azure, oss, bos, cos and tos. Use your own bucket/container,
optional object_prefix, and the provider-specific credentials. S3-compatible endpoints must
use HTTPS. [Storage fields and examples](https://flashdata.dev/docs/sources/youtube_download).

Keep the returned `id`. Read that same job with `--operation status --job-id ID` or
`--operation result --job-id ID`. Omit submission inputs when resuming. There is no automatic
polling or resubmission. Only the lifecycle receipt and delivery JSON are exported; media is
written by FlashData to your storage. Result JSON expires after 24 hours. Delivery manifests
can contain signed private URLs; protect the output file. Storage credentials from job params
are excluded from CLI output. Completed result reads may fetch signed JSON from the
FlashData result origin; the API key is never sent to that object URL.

## Pricing and errors

This MIT-licensed CLI is free to install. API calls use your own
[FlashData Credits](https://flashdata.dev/pricing). Downloads are billed by delivered volume; your cloud-storage and transfer costs are separate. A submission receipt is not the final usage charge.

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. For downloads, exit 0 can describe an unfinished job.
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_download) ·
[Privacy policy](https://flashdata.dev/legal/privacy) ·
[Source code](https://github.com/rocosen/flashdata-mcp/tree/main/packages/python-cli)
