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.
- {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/.editorconfig +1 -1
- ytstudio_cli-0.3.0/.github/workflows/docs.yml +65 -0
- {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/.gitignore +4 -1
- {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/.pre-commit-config.yaml +1 -0
- ytstudio_cli-0.3.0/PKG-INFO +106 -0
- ytstudio_cli-0.3.0/README.md +78 -0
- ytstudio_cli-0.3.0/ascii.png +0 -0
- ytstudio_cli-0.3.0/docs/analytics.md +65 -0
- ytstudio_cli-0.3.0/docs/api-quota.md +44 -0
- ytstudio_cli-0.3.0/docs/comments.md +46 -0
- ytstudio_cli-0.3.0/docs/index.md +62 -0
- ytstudio_cli-0.3.0/docs/installation.md +44 -0
- ytstudio_cli-0.3.0/docs/livestreams.md +87 -0
- ytstudio_cli-0.3.0/docs/profiles.md +54 -0
- ytstudio_cli-0.3.0/docs/setup.md +75 -0
- ytstudio_cli-0.3.0/docs/stylesheets/extra.css +67 -0
- ytstudio_cli-0.3.0/docs/videos.md +127 -0
- ytstudio_cli-0.3.0/mkdocs.yml +102 -0
- {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/pyproject.toml +10 -2
- ytstudio_cli-0.3.0/scripts/build_docs_reference.py +51 -0
- {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/src/ytstudio/api.py +120 -29
- ytstudio_cli-0.3.0/src/ytstudio/commands/livestreams.py +694 -0
- ytstudio_cli-0.3.0/src/ytstudio/commands/profile.py +96 -0
- ytstudio_cli-0.3.0/src/ytstudio/commands/upload.py +155 -0
- {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/src/ytstudio/commands/videos.py +22 -0
- ytstudio_cli-0.3.0/src/ytstudio/config.py +262 -0
- {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/src/ytstudio/main.py +14 -4
- ytstudio_cli-0.3.0/src/ytstudio/services.py +9 -0
- ytstudio_cli-0.3.0/src/ytstudio/upload_pipeline.py +245 -0
- {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/tests/conftest.py +1 -1
- {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/tests/test_analytics.py +56 -35
- ytstudio_cli-0.3.0/tests/test_api.py +188 -0
- ytstudio_cli-0.3.0/tests/test_config.py +208 -0
- ytstudio_cli-0.3.0/tests/test_livestreams.py +460 -0
- ytstudio_cli-0.3.0/tests/test_profile.py +126 -0
- ytstudio_cli-0.3.0/tests/test_upload_command.py +147 -0
- ytstudio_cli-0.3.0/tests/test_upload_pipeline.py +355 -0
- {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/tests/test_videos.py +61 -0
- {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/uv.lock +433 -6
- ytstudio_cli-0.1.1/PKG-INFO +0 -95
- ytstudio_cli-0.1.1/README.md +0 -69
- ytstudio_cli-0.1.1/demo.gif +0 -0
- ytstudio_cli-0.1.1/src/ytstudio/config.py +0 -74
- ytstudio_cli-0.1.1/src/ytstudio/demo.py +0 -189
- ytstudio_cli-0.1.1/src/ytstudio/demo_data/analytics_metrics.json +0 -103
- ytstudio_cli-0.1.1/src/ytstudio/demo_data/channel.json +0 -21
- ytstudio_cli-0.1.1/src/ytstudio/demo_data/comments.json +0 -284
- ytstudio_cli-0.1.1/src/ytstudio/demo_data/playlist_items.json +0 -26
- ytstudio_cli-0.1.1/src/ytstudio/demo_data/videos.json +0 -451
- ytstudio_cli-0.1.1/src/ytstudio/services.py +0 -14
- ytstudio_cli-0.1.1/tests/test_api.py +0 -60
- ytstudio_cli-0.1.1/tests/test_config.py +0 -47
- {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/.github/workflows/ci.yml +0 -0
- {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/.python-version +0 -0
- {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/LICENSE +0 -0
- {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/src/ytstudio/__init__.py +0 -0
- {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/src/ytstudio/commands/__init__.py +0 -0
- {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/src/ytstudio/commands/analytics.py +0 -0
- {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/src/ytstudio/commands/comments.py +0 -0
- {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/src/ytstudio/registry.py +0 -0
- {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/src/ytstudio/ui.py +0 -0
- {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/src/ytstudio/version.py +0 -0
- {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/tests/__init__.py +0 -0
- {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/tests/test_comments.py +0 -0
- {ytstudio_cli-0.1.1 → ytstudio_cli-0.3.0}/tests/test_registry.py +0 -0
|
@@ -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
|
|
@@ -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.
|