ytstudio-cli 0.1.1__tar.gz → 0.3.0__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 (65) hide show
  1. {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/.editorconfig +1 -1
  2. ytstudio_cli-0.3.0/.github/workflows/docs.yml +65 -0
  3. {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/.gitignore +4 -1
  4. {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/.pre-commit-config.yaml +1 -0
  5. ytstudio_cli-0.3.0/PKG-INFO +106 -0
  6. ytstudio_cli-0.3.0/README.md +78 -0
  7. ytstudio_cli-0.3.0/ascii.png +0 -0
  8. ytstudio_cli-0.3.0/docs/analytics.md +65 -0
  9. ytstudio_cli-0.3.0/docs/api-quota.md +44 -0
  10. ytstudio_cli-0.3.0/docs/comments.md +46 -0
  11. ytstudio_cli-0.3.0/docs/index.md +62 -0
  12. ytstudio_cli-0.3.0/docs/installation.md +44 -0
  13. ytstudio_cli-0.3.0/docs/livestreams.md +87 -0
  14. ytstudio_cli-0.3.0/docs/profiles.md +54 -0
  15. ytstudio_cli-0.3.0/docs/setup.md +75 -0
  16. ytstudio_cli-0.3.0/docs/stylesheets/extra.css +67 -0
  17. ytstudio_cli-0.3.0/docs/videos.md +127 -0
  18. ytstudio_cli-0.3.0/mkdocs.yml +102 -0
  19. {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/pyproject.toml +10 -2
  20. ytstudio_cli-0.3.0/scripts/build_docs_reference.py +51 -0
  21. {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/src/ytstudio/api.py +120 -29
  22. ytstudio_cli-0.3.0/src/ytstudio/commands/livestreams.py +694 -0
  23. ytstudio_cli-0.3.0/src/ytstudio/commands/profile.py +96 -0
  24. ytstudio_cli-0.3.0/src/ytstudio/commands/upload.py +155 -0
  25. {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/src/ytstudio/commands/videos.py +22 -0
  26. ytstudio_cli-0.3.0/src/ytstudio/config.py +262 -0
  27. {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/src/ytstudio/main.py +14 -4
  28. ytstudio_cli-0.3.0/src/ytstudio/services.py +9 -0
  29. ytstudio_cli-0.3.0/src/ytstudio/upload_pipeline.py +245 -0
  30. {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/tests/conftest.py +1 -1
  31. {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/tests/test_analytics.py +56 -35
  32. ytstudio_cli-0.3.0/tests/test_api.py +188 -0
  33. ytstudio_cli-0.3.0/tests/test_config.py +208 -0
  34. ytstudio_cli-0.3.0/tests/test_livestreams.py +460 -0
  35. ytstudio_cli-0.3.0/tests/test_profile.py +126 -0
  36. ytstudio_cli-0.3.0/tests/test_upload_command.py +147 -0
  37. ytstudio_cli-0.3.0/tests/test_upload_pipeline.py +355 -0
  38. {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/tests/test_videos.py +61 -0
  39. {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/uv.lock +433 -6
  40. ytstudio_cli-0.1.1/PKG-INFO +0 -95
  41. ytstudio_cli-0.1.1/README.md +0 -69
  42. ytstudio_cli-0.1.1/demo.gif +0 -0
  43. ytstudio_cli-0.1.1/src/ytstudio/config.py +0 -74
  44. ytstudio_cli-0.1.1/src/ytstudio/demo.py +0 -189
  45. ytstudio_cli-0.1.1/src/ytstudio/demo_data/analytics_metrics.json +0 -103
  46. ytstudio_cli-0.1.1/src/ytstudio/demo_data/channel.json +0 -21
  47. ytstudio_cli-0.1.1/src/ytstudio/demo_data/comments.json +0 -284
  48. ytstudio_cli-0.1.1/src/ytstudio/demo_data/playlist_items.json +0 -26
  49. ytstudio_cli-0.1.1/src/ytstudio/demo_data/videos.json +0 -451
  50. ytstudio_cli-0.1.1/src/ytstudio/services.py +0 -14
  51. ytstudio_cli-0.1.1/tests/test_api.py +0 -60
  52. ytstudio_cli-0.1.1/tests/test_config.py +0 -47
  53. {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/.github/workflows/ci.yml +0 -0
  54. {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/.python-version +0 -0
  55. {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/LICENSE +0 -0
  56. {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/src/ytstudio/__init__.py +0 -0
  57. {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/src/ytstudio/commands/__init__.py +0 -0
  58. {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/src/ytstudio/commands/analytics.py +0 -0
  59. {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/src/ytstudio/commands/comments.py +0 -0
  60. {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/src/ytstudio/registry.py +0 -0
  61. {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/src/ytstudio/ui.py +0 -0
  62. {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/src/ytstudio/version.py +0 -0
  63. {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/tests/__init__.py +0 -0
  64. {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/tests/test_comments.py +0 -0
  65. {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/tests/test_registry.py +0 -0
@@ -12,4 +12,4 @@ insert_final_newline = true
12
12
  max_line_length = 100
13
13
 
14
14
  [*.{yml,yaml,toml}]
15
- indent_size = 2
15
+ indent_size = 2
@@ -0,0 +1,65 @@
1
+ name: Docs
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+ paths:
9
+ - docs/**
10
+ - mkdocs.yml
11
+ - scripts/build_docs_reference.py
12
+ - src/ytstudio/** # CLI surface feeds the auto-generated reference
13
+ - pyproject.toml
14
+ - uv.lock
15
+ - .github/workflows/docs.yml
16
+ workflow_dispatch:
17
+
18
+ permissions:
19
+ contents: read
20
+ pages: write
21
+ id-token: write
22
+
23
+ # Only one Pages deploy at a time; never cancel a running deploy.
24
+ concurrency:
25
+ group: pages
26
+ cancel-in-progress: false
27
+
28
+ jobs:
29
+ build:
30
+ runs-on: ubuntu-latest
31
+ steps:
32
+ - name: Checkout
33
+ uses: actions/checkout@v6
34
+ with:
35
+ fetch-depth: 0
36
+
37
+ - name: Install uv
38
+ uses: astral-sh/setup-uv@v7
39
+
40
+ - name: Set up Python
41
+ run: uv python install 3.12
42
+
43
+ - name: Install docs dependencies
44
+ run: uv sync --locked --group docs
45
+
46
+ - name: Build (strict)
47
+ run: uv run mkdocs build --strict
48
+
49
+ - name: Upload Pages artifact
50
+ if: github.event_name != 'pull_request'
51
+ uses: actions/upload-pages-artifact@v5
52
+ with:
53
+ path: site
54
+
55
+ deploy:
56
+ needs: build
57
+ if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
58
+ runs-on: ubuntu-latest
59
+ environment:
60
+ name: github-pages
61
+ url: ${{ steps.deployment.outputs.page_url }}
62
+ steps:
63
+ - name: Deploy to GitHub Pages
64
+ id: deployment
65
+ uses: actions/deploy-pages@v5
@@ -12,4 +12,7 @@ htmlcov/
12
12
  .idea/
13
13
  .vscode/
14
14
  .DS_Store
15
- demo/
15
+
16
+ # Docs build artefacts and generated content
17
+ site/
18
+ docs/reference.md
@@ -5,6 +5,7 @@ repos:
5
5
  - id: trailing-whitespace
6
6
  - id: end-of-file-fixer
7
7
  - id: check-yaml
8
+ args: ["--unsafe"]
8
9
  - id: check-added-large-files
9
10
  - id: check-merge-conflict
10
11
 
@@ -0,0 +1,106 @@
1
+ Metadata-Version: 2.4
2
+ Name: ytstudio-cli
3
+ Version: 0.3.0
4
+ Summary: Manage and analyze your YouTube channel from the terminal. Designed for humans and AI agents.
5
+ Project-URL: Homepage, https://github.com/jdwit/ytstudio-cli
6
+ Project-URL: Repository, https://github.com/jdwit/ytstudio-cli
7
+ Author-email: Jelmer de Wit <1598297+jdwit@users.noreply.github.com>
8
+ License: MIT
9
+ License-File: LICENSE
10
+ Keywords: analytics,cli,creator,video,youtube,youtube-studio
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Requires-Python: >=3.12
19
+ Requires-Dist: google-api-python-client>=2.0.0
20
+ Requires-Dist: google-auth-oauthlib>=1.0.0
21
+ Requires-Dist: google-auth>=2.0.0
22
+ Requires-Dist: packaging>=21.0
23
+ Requires-Dist: pydantic>=2.5
24
+ Requires-Dist: rich>=13.0.0
25
+ Requires-Dist: ruamel-yaml>=0.18
26
+ Requires-Dist: typer>=0.9.0
27
+ Description-Content-Type: text/markdown
28
+
29
+ <h1 align="center">YT Studio CLI</h1>
30
+
31
+ <p align="center">
32
+ <img src="ascii.png" alt="ascii">
33
+ </p>
34
+
35
+ <p align="center">
36
+ <a href="https://github.com/jdwit/ytstudio/actions/workflows/ci.yml"><img src="https://github.com/jdwit/ytstudio/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
37
+ <a href="https://pypi.org/project/ytstudio-cli/"><img src="https://img.shields.io/pypi/v/ytstudio-cli" alt="PyPI"></a>
38
+ <a href="https://pypi.org/project/ytstudio-cli/"><img src="https://img.shields.io/pypi/pyversions/ytstudio-cli" alt="Python"></a>
39
+ </p>
40
+
41
+ <p align="center">
42
+ Manage and analyze your YouTube channel from the terminal. Designed for humans and AI agents.
43
+ </p>
44
+
45
+ > [!NOTE]
46
+ > This is **not** an official Google product, see [disclaimer](#disclaimer).
47
+
48
+ ## Motivation
49
+
50
+ I built this because I needed to bulk update video titles for a YouTube channel I manage with 300+
51
+ videos. YouTube Studio does not support bulk search-replace operations, which made it a tedious
52
+ manual process. This tool uses the YouTube Data API to perform bulk operations on video metadata.
53
+ Furthermore, it provides features for analytics and comment moderation, all accessible from the
54
+ command line.
55
+
56
+ ## Features
57
+
58
+ - Bulk update video metadata across hundreds of videos in one pass (search-replace titles,
59
+ descriptions, tags).
60
+ - Upload videos from a directory using YAML sidecars for metadata and thumbnails.
61
+ - Schedule, start, stop, and update YouTube livestream broadcasts, including RTMP ingest details.
62
+ - Multi-channel profiles: manage several channels from one machine and switch per command.
63
+ - Comments moderation: list, reply, and moderate from the CLI.
64
+ - Channel analytics queries via the YouTube Analytics API.
65
+
66
+ ## Documentation
67
+
68
+ See the [full documentation](https://jdwit.github.io/ytstudio-cli/) for installation, OAuth setup, and the command reference.
69
+
70
+ ## Development
71
+
72
+ Clone the repo, sync dev dependencies, and install the pre-commit hook so
73
+ `ruff check` and `ruff format` run on every commit (same checks CI runs):
74
+
75
+ ```bash
76
+ uv sync --group dev
77
+ uv run pre-commit install
78
+ ```
79
+
80
+ Run the suite manually with `uv run pytest` and `uv run pre-commit run --all-files`.
81
+
82
+ To preview the docs site locally, install the `docs` group and serve with mkdocs:
83
+
84
+ ```bash
85
+ uv sync --group docs
86
+ uv run mkdocs serve # or: uv run mkdocs build
87
+ ```
88
+
89
+ ## API quota
90
+
91
+ The YouTube Data API enforces a default quota of 10_000 units per project per day. Most read
92
+ operations (listing videos, comments, channel info) cost 1 unit, while write operations like
93
+ updating video metadata or moderating comments cost 50 units each. Bulk updates can consume quota
94
+ quickly. When exceeded, the API returns a 403 error; quota resets at midnight Pacific Time.
95
+
96
+ You can request a quota increase via **IAM & Admin** → **Quotas** in the
97
+ [Google Cloud Console](https://console.cloud.google.com/). See the
98
+ [official quota documentation](https://developers.google.com/youtube/v3/getting-started#quota) for
99
+ full details.
100
+
101
+ ## Disclaimer
102
+
103
+ This is not an officially supported Google or YouTube product. YouTube and YouTube Studio are
104
+ trademarks of Google. All channel data is accessed exclusively through the official
105
+ [YouTube Data API](https://developers.google.com/youtube/v3) and
106
+ [YouTube Analytics API](https://developers.google.com/youtube/analytics).
@@ -0,0 +1,78 @@
1
+ <h1 align="center">YT Studio CLI</h1>
2
+
3
+ <p align="center">
4
+ <img src="ascii.png" alt="ascii">
5
+ </p>
6
+
7
+ <p align="center">
8
+ <a href="https://github.com/jdwit/ytstudio/actions/workflows/ci.yml"><img src="https://github.com/jdwit/ytstudio/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
9
+ <a href="https://pypi.org/project/ytstudio-cli/"><img src="https://img.shields.io/pypi/v/ytstudio-cli" alt="PyPI"></a>
10
+ <a href="https://pypi.org/project/ytstudio-cli/"><img src="https://img.shields.io/pypi/pyversions/ytstudio-cli" alt="Python"></a>
11
+ </p>
12
+
13
+ <p align="center">
14
+ Manage and analyze your YouTube channel from the terminal. Designed for humans and AI agents.
15
+ </p>
16
+
17
+ > [!NOTE]
18
+ > This is **not** an official Google product, see [disclaimer](#disclaimer).
19
+
20
+ ## Motivation
21
+
22
+ I built this because I needed to bulk update video titles for a YouTube channel I manage with 300+
23
+ videos. YouTube Studio does not support bulk search-replace operations, which made it a tedious
24
+ manual process. This tool uses the YouTube Data API to perform bulk operations on video metadata.
25
+ Furthermore, it provides features for analytics and comment moderation, all accessible from the
26
+ command line.
27
+
28
+ ## Features
29
+
30
+ - Bulk update video metadata across hundreds of videos in one pass (search-replace titles,
31
+ descriptions, tags).
32
+ - Upload videos from a directory using YAML sidecars for metadata and thumbnails.
33
+ - Schedule, start, stop, and update YouTube livestream broadcasts, including RTMP ingest details.
34
+ - Multi-channel profiles: manage several channels from one machine and switch per command.
35
+ - Comments moderation: list, reply, and moderate from the CLI.
36
+ - Channel analytics queries via the YouTube Analytics API.
37
+
38
+ ## Documentation
39
+
40
+ See the [full documentation](https://jdwit.github.io/ytstudio-cli/) for installation, OAuth setup, and the command reference.
41
+
42
+ ## Development
43
+
44
+ Clone the repo, sync dev dependencies, and install the pre-commit hook so
45
+ `ruff check` and `ruff format` run on every commit (same checks CI runs):
46
+
47
+ ```bash
48
+ uv sync --group dev
49
+ uv run pre-commit install
50
+ ```
51
+
52
+ Run the suite manually with `uv run pytest` and `uv run pre-commit run --all-files`.
53
+
54
+ To preview the docs site locally, install the `docs` group and serve with mkdocs:
55
+
56
+ ```bash
57
+ uv sync --group docs
58
+ uv run mkdocs serve # or: uv run mkdocs build
59
+ ```
60
+
61
+ ## API quota
62
+
63
+ The YouTube Data API enforces a default quota of 10_000 units per project per day. Most read
64
+ operations (listing videos, comments, channel info) cost 1 unit, while write operations like
65
+ updating video metadata or moderating comments cost 50 units each. Bulk updates can consume quota
66
+ quickly. When exceeded, the API returns a 403 error; quota resets at midnight Pacific Time.
67
+
68
+ You can request a quota increase via **IAM & Admin** → **Quotas** in the
69
+ [Google Cloud Console](https://console.cloud.google.com/). See the
70
+ [official quota documentation](https://developers.google.com/youtube/v3/getting-started#quota) for
71
+ full details.
72
+
73
+ ## Disclaimer
74
+
75
+ This is not an officially supported Google or YouTube product. YouTube and YouTube Studio are
76
+ trademarks of Google. All channel data is accessed exclusively through the official
77
+ [YouTube Data API](https://developers.google.com/youtube/v3) and
78
+ [YouTube Analytics API](https://developers.google.com/youtube/analytics).
Binary file
@@ -0,0 +1,65 @@
1
+ # Analytics
2
+
3
+ `ytstudio analytics` queries the YouTube Analytics API: channel-wide totals,
4
+ per-video performance, and ad-hoc queries against the full metric and
5
+ dimension catalogue. Output defaults to a Rich table; pass `-o json` for
6
+ scripting.
7
+
8
+ ## Common queries
9
+
10
+ ```bash
11
+ ytstudio analytics overview # channel summary for the last 28 days
12
+ ytstudio analytics overview --days 7 # rolling 7-day window
13
+ ytstudio analytics video <video-id> # one video's recent performance
14
+ ytstudio analytics video <video-id> --days 90 # longer window for one video
15
+ ```
16
+
17
+ ## Custom queries
18
+
19
+ `analytics query` is a thin wrapper over the YouTube Analytics
20
+ `reports.query` endpoint, so anything you can express against that API is
21
+ reachable from the CLI.
22
+
23
+ ```bash
24
+ ytstudio analytics query \
25
+ -m views,estimatedMinutesWatched,averageViewDuration \
26
+ -d day \
27
+ --start 2026-04-01 --end 2026-04-30
28
+
29
+ ytstudio analytics query \
30
+ -m views -d country \
31
+ --sort -views -n 10
32
+ ```
33
+
34
+ Sort fields take a `-` prefix for descending. Use `-f key==value` (repeatable)
35
+ to filter, for example `-f video==dMH0bHeiRNg`.
36
+
37
+ Discover what is available:
38
+
39
+ ```bash
40
+ ytstudio analytics metrics # list every metric the API exposes
41
+ ytstudio analytics dimensions # list every dimension the API exposes
42
+ ```
43
+
44
+ Run `ytstudio analytics --help` (or open the
45
+ [Command reference](reference.md)) for every flag.
46
+
47
+ ## Output
48
+
49
+ === "Table"
50
+
51
+ ```bash
52
+ ytstudio analytics overview
53
+ ```
54
+
55
+ === "JSON"
56
+
57
+ ```bash
58
+ ytstudio analytics overview -o json | jq '.rows[0]'
59
+ ```
60
+
61
+ ## Quota
62
+
63
+ Analytics reads are cheap (1 unit per call against the Data API quota); you
64
+ can hit them often without worrying. See [API quota](api-quota.md) for the
65
+ full picture.
@@ -0,0 +1,44 @@
1
+ # API quota
2
+
3
+ The YouTube Data API enforces a daily quota of **10 000 units per project**
4
+ by default. Most read operations (`videos.list`, `comments.list`, channel
5
+ info) cost 1 unit, while write operations like `videos.update`,
6
+ `liveBroadcasts.insert`/`update`, and `comments.setModerationStatus` cost
7
+ about 50 units each.
8
+
9
+ When you exceed the quota, the API returns HTTP 403 with a
10
+ `quotaExceeded` reason. ytstudio surfaces a clear error and exits.
11
+ Quota resets at midnight Pacific Time.
12
+
13
+ The **YouTube Analytics API** is a separate API with its own quota model
14
+ (query-cost based, far more generous in practice), so analytics calls do
15
+ not eat into the table below.
16
+
17
+ ## Data API cost cheatsheet
18
+
19
+ | Operation | Approx. quota cost |
20
+ |-------------------------------------|--------------------|
21
+ | `videos.list` | 1 unit |
22
+ | `commentThreads.list` | 1 unit |
23
+ | `channels.list` | 1 unit |
24
+ | `liveBroadcasts.list` | 1 unit |
25
+ | `videos.update` | 50 units |
26
+ | `comments.setModerationStatus` | 50 units |
27
+ | `liveBroadcasts.insert` | 50 units |
28
+ | `liveBroadcasts.update` | 50 units |
29
+ | `liveBroadcasts.transition` | 50 units |
30
+ | `videos.insert` (upload) | ~1600 units |
31
+ | `thumbnails.set` | 50 units |
32
+
33
+ At ~1600 units per upload, the default 10 000-unit daily budget covers about
34
+ six new videos per day. Use `ytstudio videos upload --max N` to cap a run
35
+ and avoid burning the budget you need for the rest of the day.
36
+
37
+ ## Increasing the quota
38
+
39
+ In the Google Cloud Console, go to **IAM & Admin** :material-arrow-right:
40
+ **Quotas** and file a quota increase request for the YouTube Data API.
41
+ Google's response time varies; expect a couple of days.
42
+
43
+ Reference:
44
+ [YouTube quota documentation](https://developers.google.com/youtube/v3/getting-started#quota).
@@ -0,0 +1,46 @@
1
+ # Comments
2
+
3
+ `ytstudio comments` lists comment threads and moderates them. It is built
4
+ for the scripted case where the YouTube Studio UI gets in the way:
5
+ filtering threads, approving or rejecting in bulk, exporting JSON for
6
+ downstream tooling.
7
+
8
+ ## List
9
+
10
+ ```bash
11
+ ytstudio comments list --video <video-id>
12
+ ytstudio comments list --video <video-id> -o json | jq
13
+
14
+ # Held queue, ordered chronologically
15
+ ytstudio comments list --video <video-id> --status held --sort time
16
+ ```
17
+
18
+ `--status` accepts `published`, `held`, or `spam` (mapped internally to
19
+ YouTube's `published`, `heldForReview`, and `likelySpam` values). `--sort`
20
+ accepts `time` or `relevance`; the YouTube API only honours `relevance` for
21
+ a single video, so `--sort relevance` requires `--video <id>`. Omit
22
+ `--video` to list across the channel (time-sorted only).
23
+
24
+ ## Approve held comments
25
+
26
+ ```bash
27
+ ytstudio comments publish <comment-id> [<comment-id> ...]
28
+ ```
29
+
30
+ `publish` takes one or more comment IDs and transitions each to
31
+ `published`.
32
+
33
+ ## Reject
34
+
35
+ ```bash
36
+ ytstudio comments reject <comment-id> [<comment-id> ...]
37
+ ytstudio comments reject <comment-id> --ban # also ban the author
38
+ ```
39
+
40
+ `reject` hides the comment from public view. Pass `--ban` to also ban the
41
+ author from the channel.
42
+
43
+ !!! note "Quota"
44
+
45
+ `comments.setModerationStatus` costs about 50 quota units per call. For
46
+ larger moderation runs, see [API quota](api-quota.md).
@@ -0,0 +1,62 @@
1
+ # ytstudio
2
+
3
+ Manage and analyze your YouTube channel from the terminal. Designed for
4
+ humans and AI agents.
5
+
6
+ ## What it is
7
+
8
+ A small CLI on top of the official
9
+ [YouTube Data API](https://developers.google.com/youtube/v3) and
10
+ [YouTube Analytics API](https://developers.google.com/youtube/analytics) that
11
+ allows for bulk video updates and uploads, scripted analytics queries,
12
+ comment moderation, and live broadcast control.
13
+
14
+ ## Why it exists
15
+
16
+ Managing a YouTube channel at scale feels like click-ops: the web UI has no
17
+ advanced features for bulk updates, and things become tedious very fast.
18
+ ytstudio gives you a programmable surface to automate administration tasks
19
+ and plug your channel into AI agent workflows.
20
+
21
+ ## Highlights
22
+
23
+ - **Multiple channels** in a single install, with
24
+ per-profile credential storage. See [Multi-channel profiles](profiles.md).
25
+ - **Bulk video updates** with search-and-replace on
26
+ titles or descriptions, plus per-video title/description/tag edits. See
27
+ [Bulk video updates](videos.md).
28
+ - **Batch upload** from a directory of YAML
29
+ sidecars with resumable, quota-aware behaviour. See
30
+ [Upload a batch from sidecars](videos.md#upload-a-batch-from-sidecars).
31
+ - **Scripted analytics** with table or JSON output.
32
+ See [Analytics](analytics.md).
33
+ - **Live broadcast control** for the full lifecycle:
34
+ schedule, start (testing or live), update, stop, with stream-key handling.
35
+ See [Live broadcasts](livestreams.md).
36
+ - **Comment moderation** at the CLI:
37
+ approve, reject, or ban in bulk. See [Comments](comments.md).
38
+ - **OAuth credentials live owner-only
39
+ (`0600`)** under `~/.config/ytstudio-cli/`. The `init` step is one-shot.
40
+
41
+ ## Quick start
42
+
43
+ ```bash
44
+ uv tool install ytstudio-cli
45
+ ytstudio init --client-secrets path/to/client_secret.json
46
+ ytstudio login
47
+ ytstudio videos list
48
+ ```
49
+
50
+ The CLI is installed as `ytstudio`; `yts` is a short alias for the same
51
+ entry point.
52
+
53
+ Continue with [Installation](installation.md) for the full setup or the
54
+ [Command reference](reference.md) for every flag.
55
+
56
+ ## Disclaimer
57
+
58
+ !!! warning
59
+ This is **not** an officially supported Google or YouTube product.
60
+
61
+ YouTube and YouTube Studio are trademarks of Google. All channel data is
62
+ accessed exclusively through the official YouTube Data and Analytics APIs.
@@ -0,0 +1,44 @@
1
+ # Installation
2
+
3
+ ytstudio is published on [PyPI](https://pypi.org/project/ytstudio-cli/) and
4
+ runs on Python 3.12 and 3.13.
5
+
6
+ ## With uv (recommended)
7
+
8
+ [uv](https://uv.io/) installs Python CLIs in isolated environments and keeps
9
+ them upgradable.
10
+
11
+ ```bash
12
+ uv tool install ytstudio-cli
13
+ ```
14
+
15
+ To upgrade later:
16
+
17
+ ```bash
18
+ uv tool upgrade ytstudio-cli
19
+ ```
20
+
21
+ ## With pipx
22
+
23
+ ```bash
24
+ pipx install ytstudio-cli
25
+ pipx upgrade ytstudio-cli
26
+ ```
27
+
28
+ ## With pip
29
+
30
+ ```bash
31
+ pip install --user ytstudio-cli
32
+ ```
33
+
34
+ ## Verify
35
+
36
+ Both names share the same entry point:
37
+
38
+ ```bash
39
+ ytstudio --version
40
+ yts --version
41
+ ```
42
+
43
+ If `--version` prints a version number, you are ready for
44
+ [OAuth setup](setup.md).
@@ -0,0 +1,87 @@
1
+ # Live broadcasts
2
+
3
+ `ytstudio livestreams` drives YouTube's `liveBroadcasts` API: schedule
4
+ broadcasts, transition them through testing/live/complete, update settings,
5
+ and surface the bound stream's RTMP ingest URLs. The actual video push to
6
+ YouTube still happens through your encoder (OBS, Streamlabs, etc.).
7
+
8
+ ## Lifecycle
9
+
10
+ ```mermaid
11
+ flowchart LR
12
+ A[schedule] --> B[ready]
13
+ B --> C[testing]
14
+ B --> D[live]
15
+ C --> D
16
+ D --> E[complete]
17
+ ```
18
+
19
+ ## Listing and showing
20
+
21
+ ```bash
22
+ ytstudio livestreams list --status upcoming # only what is scheduled
23
+ ytstudio livestreams list --status all -n 50 # everything, capped at 50
24
+ ytstudio livestreams list -o json # machine-readable
25
+ ytstudio livestreams show <broadcast-id> # details
26
+ ytstudio livestreams show <id> --ingest # also the bound stream's RTMP URLs
27
+ ytstudio livestreams show <id> --show-key # reveal the stream key
28
+ ```
29
+
30
+ !!! warning "Stream keys are credentials"
31
+
32
+ `--ingest` is safe to pipe into a script: the stream key is redacted to
33
+ its last four characters. Only pass `--show-key` when you need the
34
+ actual key for your encoder, and treat the printed line as a secret.
35
+
36
+ ## Scheduling
37
+
38
+ `schedule` is **dry-run by default**: it prints the body it would send and
39
+ exits. Pass `--execute` to actually create the broadcast.
40
+
41
+ ```bash
42
+ ytstudio livestreams schedule \
43
+ --title "Office hours" \
44
+ --scheduled-start 2026-06-01T19:00:00+02:00 \
45
+ --scheduled-end 2026-06-01T20:00:00+02:00 \
46
+ --privacy unlisted \
47
+ --not-made-for-kids
48
+ # review the preview, then:
49
+ ytstudio livestreams schedule \
50
+ --title "Office hours" \
51
+ --scheduled-start 2026-06-01T19:00:00+02:00 \
52
+ --privacy unlisted --execute
53
+ ```
54
+
55
+ !!! note "Quota"
56
+
57
+ `liveBroadcasts.insert` and `liveBroadcasts.update` cost roughly 50
58
+ quota units each. See [API quota](api-quota.md) for context.
59
+
60
+ ## Going live
61
+
62
+ The `start` command has a `--to` flag that picks the target state.
63
+
64
+ ```bash
65
+ ytstudio livestreams start <id> --to testing # monitor stream (preview)
66
+ ytstudio livestreams start <id> # default: --to live
67
+ ytstudio livestreams stop <id> # transition to complete
68
+ ```
69
+
70
+ Transitions are asynchronous; the CLI prints the current status and a hint
71
+ that it may take a moment to settle.
72
+
73
+ ## Updating
74
+
75
+ `update` accepts the same field flags as schedule plus the `contentDetails`
76
+ toggles. It is dry-run by default and only sends the parts that actually
77
+ changed, while preserving `contentDetails.monitorStream` (YouTube rejects
78
+ content-detail updates that omit it).
79
+
80
+ ```bash
81
+ ytstudio livestreams update <id> --privacy unlisted --no-dvr
82
+ ytstudio livestreams update <id> --latency low --auto-start --execute
83
+ ```
84
+
85
+ `update` does not expose the made-for-kids flag, because
86
+ `liveBroadcasts.update` only accepts `privacyStatus` under `status`. Set the
87
+ COPPA flag at schedule time.
@@ -0,0 +1,54 @@
1
+ # Multi-channel profiles
2
+
3
+ ytstudio stores each YouTube login under its own named profile, so one
4
+ install can drive multiple channels. Every command operates on the
5
+ **active** profile unless you override it for a single invocation.
6
+
7
+ ## Commands
8
+
9
+ ```bash
10
+ ytstudio profile add work # authenticate a new channel and make it active
11
+ ytstudio profile add personal # add another channel
12
+ ytstudio profile list # show profiles; the active one is marked with *
13
+ ytstudio profile use work # switch the active profile
14
+ ytstudio profile status work # auth status for one profile (defaults to active)
15
+ ytstudio profile remove personal
16
+ ```
17
+
18
+ ## Per-command override
19
+
20
+ Useful in scripts: switch channel for one command without changing global
21
+ state.
22
+
23
+ ```bash
24
+ YTSTUDIO_PROFILE=work ytstudio videos list
25
+ ```
26
+
27
+ ## Storage
28
+
29
+ ```
30
+ ~/.config/ytstudio-cli/
31
+ ├── client_secrets.json # shared OAuth client, written by init
32
+ ├── state.json # active profile pointer (atomic writes)
33
+ └── profiles/
34
+ ├── default/
35
+ │ ├── credentials.json # 0600
36
+ │ └── meta.json
37
+ └── work/
38
+ ├── credentials.json
39
+ └── meta.json
40
+ ```
41
+
42
+ Profile directories are `0700`; credential files are `0600`. State writes go
43
+ through an atomic temp + rename and are serialized under an `fcntl` lock, so
44
+ concurrent CLI invocations cannot leave the file partially written.
45
+
46
+ ## Migration from older installs
47
+
48
+ If you upgraded from a single-channel install, the existing
49
+ `~/.config/ytstudio-cli/credentials.json` is moved into the `default`
50
+ profile on the next CLI invocation. The migration is one-shot, locked
51
+ against concurrent first-run commands, and a no-op once profiles exist.
52
+
53
+ A plain `ytstudio login` (no `profile add`) authenticates the active
54
+ profile, which is `default` on a fresh setup.