ytstudio-cli 0.3.1__tar.gz → 0.4.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.3.1 → ytstudio_cli-0.4.0}/PKG-INFO +25 -3
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/README.md +24 -2
- ytstudio_cli-0.4.0/docs/agent-skill.md +52 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/docs/analytics.md +12 -4
- ytstudio_cli-0.4.0/docs/api-quota.md +51 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/docs/comments.md +15 -2
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/docs/index.md +4 -1
- ytstudio_cli-0.4.0/docs/playlists.md +110 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/docs/videos.md +1 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/mkdocs.yml +2 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/pyproject.toml +1 -1
- ytstudio_cli-0.4.0/scripts/build_skill_reference.py +62 -0
- ytstudio_cli-0.4.0/skills/ytstudio/SKILL.md +238 -0
- ytstudio_cli-0.4.0/skills/ytstudio/assets/upload-sidecar.example.yaml +30 -0
- ytstudio_cli-0.4.0/skills/ytstudio/references/reference.md +951 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/commands/analytics.py +84 -7
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/commands/comments.py +31 -0
- ytstudio_cli-0.4.0/src/ytstudio/commands/playlists.py +919 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/main.py +2 -1
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/tests/conftest.py +71 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/tests/test_analytics.py +106 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/tests/test_comments.py +27 -0
- ytstudio_cli-0.4.0/tests/test_playlists.py +705 -0
- ytstudio_cli-0.4.0/tests/test_skill_reference.py +31 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/uv.lock +1 -1
- ytstudio_cli-0.3.1/docs/api-quota.md +0 -44
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/.editorconfig +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/.github/workflows/ci.yml +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/.github/workflows/docs.yml +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/.gitignore +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/.pre-commit-config.yaml +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/.python-version +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/LICENSE +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/ascii.png +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/docs/installation.md +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/docs/livestreams.md +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/docs/profiles.md +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/docs/setup.md +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/docs/stylesheets/extra.css +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/scripts/build_docs_reference.py +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/__init__.py +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/api.py +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/commands/__init__.py +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/commands/livestreams.py +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/commands/profile.py +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/commands/upload.py +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/commands/videos.py +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/config.py +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/registry.py +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/services.py +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/ui.py +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/upload_pipeline.py +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/version.py +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/tests/__init__.py +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/tests/test_api.py +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/tests/test_config.py +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/tests/test_livestreams.py +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/tests/test_profile.py +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/tests/test_registry.py +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/tests/test_upload_command.py +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/tests/test_upload_pipeline.py +0 -0
- {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/tests/test_videos.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: ytstudio-cli
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.4.0
|
|
4
4
|
Summary: Manage and analyze your YouTube channel from the terminal. Designed for humans and AI agents.
|
|
5
5
|
Project-URL: Homepage, https://github.com/jdwit/ytstudio-cli
|
|
6
6
|
Project-URL: Repository, https://github.com/jdwit/ytstudio-cli
|
|
@@ -33,7 +33,7 @@ Description-Content-Type: text/markdown
|
|
|
33
33
|
</p>
|
|
34
34
|
|
|
35
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>
|
|
36
|
+
<a href="https://github.com/jdwit/ytstudio-cli/actions/workflows/ci.yml"><img src="https://github.com/jdwit/ytstudio-cli/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
|
|
37
37
|
<a href="https://pypi.org/project/ytstudio-cli/"><img src="https://img.shields.io/pypi/v/ytstudio-cli" alt="PyPI"></a>
|
|
38
38
|
<a href="https://pypi.org/project/ytstudio-cli/"><img src="https://img.shields.io/pypi/pyversions/ytstudio-cli" alt="Python"></a>
|
|
39
39
|
</p>
|
|
@@ -60,13 +60,25 @@ command line.
|
|
|
60
60
|
- Upload videos from a directory using YAML sidecars for metadata and thumbnails.
|
|
61
61
|
- Schedule, start, stop, and update YouTube livestream broadcasts, including RTMP ingest details.
|
|
62
62
|
- Multi-channel profiles: manage several channels from one machine and switch per command.
|
|
63
|
-
- Comments moderation: list, reply, and
|
|
63
|
+
- Comments moderation: list, reply, approve, reject, and ban from the CLI.
|
|
64
64
|
- Channel analytics queries via the YouTube Analytics API.
|
|
65
|
+
- Playlists: bulk-add by search and reorder by views with one command.
|
|
65
66
|
|
|
66
67
|
## Documentation
|
|
67
68
|
|
|
68
69
|
See the [full documentation](https://jdwit.github.io/ytstudio-cli/) for installation, OAuth setup, and the command reference.
|
|
69
70
|
|
|
71
|
+
## Agent skill
|
|
72
|
+
|
|
73
|
+
ytstudio ships a harness-agnostic [agent skill](skills/ytstudio/SKILL.md) that
|
|
74
|
+
teaches any skill-aware AI agent to operate a channel through this CLI, following
|
|
75
|
+
the open [SKILL standard](https://agentskills.io). A public repo with a
|
|
76
|
+
`SKILL.md` is already a published skill, so point your agent runtime (or a
|
|
77
|
+
registry like [skills.sh](https://skills.sh)) at the `skills/ytstudio/` subpath.
|
|
78
|
+
The bundled command reference is generated from the CLI; see
|
|
79
|
+
[Agent skill](https://jdwit.github.io/ytstudio-cli/agent-skill/) for how to keep
|
|
80
|
+
it in sync.
|
|
81
|
+
|
|
70
82
|
## Development
|
|
71
83
|
|
|
72
84
|
Clone the repo, sync dev dependencies, and install the pre-commit hook so
|
|
@@ -93,6 +105,16 @@ operations (listing videos, comments, channel info) cost 1 unit, while write ope
|
|
|
93
105
|
updating video metadata or moderating comments cost 50 units each. Bulk updates can consume quota
|
|
94
106
|
quickly. When exceeded, the API returns a 403 error; quota resets at midnight Pacific Time.
|
|
95
107
|
|
|
108
|
+
| Action | Examples | Approx. cost |
|
|
109
|
+
|--------|----------|--------------|
|
|
110
|
+
| Read | list videos, comments, playlists; analytics queries | 1 unit |
|
|
111
|
+
| Write | update a video, moderate a comment, add or reorder playlist items, schedule a broadcast | 50 units |
|
|
112
|
+
| Search | `search.list`, used by `playlists add --from-search` | 100 units |
|
|
113
|
+
| Upload | `videos.insert` | ~1600 units |
|
|
114
|
+
|
|
115
|
+
A full per-operation breakdown lives in the
|
|
116
|
+
[API quota docs](https://jdwit.github.io/ytstudio-cli/api-quota/).
|
|
117
|
+
|
|
96
118
|
You can request a quota increase via **IAM & Admin** → **Quotas** in the
|
|
97
119
|
[Google Cloud Console](https://console.cloud.google.com/). See the
|
|
98
120
|
[official quota documentation](https://developers.google.com/youtube/v3/getting-started#quota) for
|
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
</p>
|
|
6
6
|
|
|
7
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>
|
|
8
|
+
<a href="https://github.com/jdwit/ytstudio-cli/actions/workflows/ci.yml"><img src="https://github.com/jdwit/ytstudio-cli/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
|
|
9
9
|
<a href="https://pypi.org/project/ytstudio-cli/"><img src="https://img.shields.io/pypi/v/ytstudio-cli" alt="PyPI"></a>
|
|
10
10
|
<a href="https://pypi.org/project/ytstudio-cli/"><img src="https://img.shields.io/pypi/pyversions/ytstudio-cli" alt="Python"></a>
|
|
11
11
|
</p>
|
|
@@ -32,13 +32,25 @@ command line.
|
|
|
32
32
|
- Upload videos from a directory using YAML sidecars for metadata and thumbnails.
|
|
33
33
|
- Schedule, start, stop, and update YouTube livestream broadcasts, including RTMP ingest details.
|
|
34
34
|
- Multi-channel profiles: manage several channels from one machine and switch per command.
|
|
35
|
-
- Comments moderation: list, reply, and
|
|
35
|
+
- Comments moderation: list, reply, approve, reject, and ban from the CLI.
|
|
36
36
|
- Channel analytics queries via the YouTube Analytics API.
|
|
37
|
+
- Playlists: bulk-add by search and reorder by views with one command.
|
|
37
38
|
|
|
38
39
|
## Documentation
|
|
39
40
|
|
|
40
41
|
See the [full documentation](https://jdwit.github.io/ytstudio-cli/) for installation, OAuth setup, and the command reference.
|
|
41
42
|
|
|
43
|
+
## Agent skill
|
|
44
|
+
|
|
45
|
+
ytstudio ships a harness-agnostic [agent skill](skills/ytstudio/SKILL.md) that
|
|
46
|
+
teaches any skill-aware AI agent to operate a channel through this CLI, following
|
|
47
|
+
the open [SKILL standard](https://agentskills.io). A public repo with a
|
|
48
|
+
`SKILL.md` is already a published skill, so point your agent runtime (or a
|
|
49
|
+
registry like [skills.sh](https://skills.sh)) at the `skills/ytstudio/` subpath.
|
|
50
|
+
The bundled command reference is generated from the CLI; see
|
|
51
|
+
[Agent skill](https://jdwit.github.io/ytstudio-cli/agent-skill/) for how to keep
|
|
52
|
+
it in sync.
|
|
53
|
+
|
|
42
54
|
## Development
|
|
43
55
|
|
|
44
56
|
Clone the repo, sync dev dependencies, and install the pre-commit hook so
|
|
@@ -65,6 +77,16 @@ operations (listing videos, comments, channel info) cost 1 unit, while write ope
|
|
|
65
77
|
updating video metadata or moderating comments cost 50 units each. Bulk updates can consume quota
|
|
66
78
|
quickly. When exceeded, the API returns a 403 error; quota resets at midnight Pacific Time.
|
|
67
79
|
|
|
80
|
+
| Action | Examples | Approx. cost |
|
|
81
|
+
|--------|----------|--------------|
|
|
82
|
+
| Read | list videos, comments, playlists; analytics queries | 1 unit |
|
|
83
|
+
| Write | update a video, moderate a comment, add or reorder playlist items, schedule a broadcast | 50 units |
|
|
84
|
+
| Search | `search.list`, used by `playlists add --from-search` | 100 units |
|
|
85
|
+
| Upload | `videos.insert` | ~1600 units |
|
|
86
|
+
|
|
87
|
+
A full per-operation breakdown lives in the
|
|
88
|
+
[API quota docs](https://jdwit.github.io/ytstudio-cli/api-quota/).
|
|
89
|
+
|
|
68
90
|
You can request a quota increase via **IAM & Admin** → **Quotas** in the
|
|
69
91
|
[Google Cloud Console](https://console.cloud.google.com/). See the
|
|
70
92
|
[official quota documentation](https://developers.google.com/youtube/v3/getting-started#quota) for
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# Agent skill
|
|
2
|
+
|
|
3
|
+
ytstudio ships a model- and harness-agnostic **agent skill** so any skill-aware
|
|
4
|
+
AI agent can operate a YouTube channel through the CLI. It follows the open
|
|
5
|
+
[SKILL standard](https://agentskills.io): a folder with a `SKILL.md` (YAML
|
|
6
|
+
frontmatter plus instructions) and optional bundled resources.
|
|
7
|
+
|
|
8
|
+
The skill lives in this repository at
|
|
9
|
+
[`skills/ytstudio/`](https://github.com/jdwit/ytstudio-cli/tree/main/skills/ytstudio):
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
skills/ytstudio/
|
|
13
|
+
├── SKILL.md # frontmatter + instructions
|
|
14
|
+
├── references/
|
|
15
|
+
│ └── reference.md # full command reference (generated)
|
|
16
|
+
└── assets/
|
|
17
|
+
└── upload-sidecar.example.yaml # example upload sidecar
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## Using it
|
|
21
|
+
|
|
22
|
+
A public GitHub repo containing a `SKILL.md` is already a published skill, so no
|
|
23
|
+
separate package or repo is needed. Point your agent runtime (or a registry such
|
|
24
|
+
as [skills.sh](https://skills.sh)) at the `skills/ytstudio/` subpath; monorepo
|
|
25
|
+
skills in a subfolder are supported by the spec.
|
|
26
|
+
|
|
27
|
+
The skill itself is vendor-neutral: every instruction is a shell command, with
|
|
28
|
+
no MCP server and nothing tied to a specific agent platform. It stresses the
|
|
29
|
+
rules that matter most when an agent drives the CLI: pass `-o json` for
|
|
30
|
+
parseable output, preview mutations that support `--execute`, and explicitly
|
|
31
|
+
confirm before immediate writes such as comment moderation/replies and
|
|
32
|
+
livestream start/stop.
|
|
33
|
+
|
|
34
|
+
## Keeping the reference in sync
|
|
35
|
+
|
|
36
|
+
`skills/ytstudio/references/reference.md` is the full command reference. Unlike
|
|
37
|
+
the site's [command reference](reference.md) (built on the fly by mkdocs and
|
|
38
|
+
git-ignored), the skill copy is checked into git because it travels with the
|
|
39
|
+
skill when installed from the repo, so it can drift from the CLI.
|
|
40
|
+
|
|
41
|
+
Two things keep it honest, both driven from the same typer app as the rest of
|
|
42
|
+
the docs:
|
|
43
|
+
|
|
44
|
+
- Regenerate it after any change to the CLI surface:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
uv run python scripts/build_skill_reference.py
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
- CI guards against drift: `tests/test_skill_reference.py` re-renders the
|
|
51
|
+
reference and fails if the committed copy is stale, pointing at the command
|
|
52
|
+
above.
|
|
@@ -10,10 +10,17 @@ scripting.
|
|
|
10
10
|
```bash
|
|
11
11
|
ytstudio analytics overview # channel summary for the last 28 days
|
|
12
12
|
ytstudio analytics overview --days 7 # rolling 7-day window
|
|
13
|
+
ytstudio analytics overview --no-compare # totals only, no growth deltas
|
|
13
14
|
ytstudio analytics video <video-id> # one video's recent performance
|
|
14
15
|
ytstudio analytics video <video-id> --days 90 # longer window for one video
|
|
15
16
|
```
|
|
16
17
|
|
|
18
|
+
By default `overview` also compares each metric to the previous equal-length
|
|
19
|
+
window and shows the percent change (green up, red down). Pass `--no-compare`
|
|
20
|
+
for plain totals. In JSON output the comparison is exposed as `previous`
|
|
21
|
+
(the prior window's metrics) and `pct_change` (percent change per metric,
|
|
22
|
+
`null` when there is no prior-window baseline).
|
|
23
|
+
|
|
17
24
|
## Custom queries
|
|
18
25
|
|
|
19
26
|
`analytics query` is a thin wrapper over the YouTube Analytics
|
|
@@ -55,11 +62,12 @@ Run `ytstudio analytics --help` (or open the
|
|
|
55
62
|
=== "JSON"
|
|
56
63
|
|
|
57
64
|
```bash
|
|
58
|
-
ytstudio analytics overview -o json | jq '.
|
|
65
|
+
ytstudio analytics overview -o json | jq '.pct_change'
|
|
59
66
|
```
|
|
60
67
|
|
|
61
68
|
## Quota
|
|
62
69
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
70
|
+
The YouTube Analytics API is a separate API from the YouTube Data API, with
|
|
71
|
+
its own query-cost based quota that is far more generous in practice, so
|
|
72
|
+
analytics reads do not consume your Data API budget. See
|
|
73
|
+
[API quota](api-quota.md) for the full picture.
|
|
@@ -0,0 +1,51 @@
|
|
|
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`, playlist
|
|
6
|
+
edits, `liveBroadcasts.insert`/`update`, and `comments.setModerationStatus`
|
|
7
|
+
cost about 50 units each. `search.list` (behind `playlists add --from-search`)
|
|
8
|
+
is the notable exception at 100 units per call.
|
|
9
|
+
|
|
10
|
+
When you exceed the quota, the API returns HTTP 403 with a
|
|
11
|
+
`quotaExceeded` reason. ytstudio surfaces a clear error and exits.
|
|
12
|
+
Quota resets at midnight Pacific Time.
|
|
13
|
+
|
|
14
|
+
The **YouTube Analytics API** is a separate API with its own quota model
|
|
15
|
+
(query-cost based, far more generous in practice), so analytics calls do
|
|
16
|
+
not eat into the table below.
|
|
17
|
+
|
|
18
|
+
## Data API cost cheatsheet
|
|
19
|
+
|
|
20
|
+
| Operation | Approx. quota cost |
|
|
21
|
+
|----------------------------------------------|--------------------|
|
|
22
|
+
| `videos.list` | 1 unit |
|
|
23
|
+
| `commentThreads.list` | 1 unit |
|
|
24
|
+
| `channels.list` | 1 unit |
|
|
25
|
+
| `liveBroadcasts.list` | 1 unit |
|
|
26
|
+
| `playlists.list` | 1 unit |
|
|
27
|
+
| `playlistItems.list` | 1 unit |
|
|
28
|
+
| `search.list` | 100 units |
|
|
29
|
+
| `videos.update` | 50 units |
|
|
30
|
+
| `comments.setModerationStatus` | 50 units |
|
|
31
|
+
| `comments.insert` (reply) | 50 units |
|
|
32
|
+
| `playlists.insert` / `update` / `delete` | 50 units |
|
|
33
|
+
| `playlistItems.insert` / `update` / `delete` | 50 units |
|
|
34
|
+
| `liveBroadcasts.insert` | 50 units |
|
|
35
|
+
| `liveBroadcasts.update` | 50 units |
|
|
36
|
+
| `liveBroadcasts.transition` | 50 units |
|
|
37
|
+
| `thumbnails.set` | 50 units |
|
|
38
|
+
| `videos.insert` (upload) | ~1600 units |
|
|
39
|
+
|
|
40
|
+
At ~1600 units per upload, the default 10 000-unit daily budget covers about
|
|
41
|
+
six new videos per day. Use `ytstudio videos upload --max N` to cap a run
|
|
42
|
+
and avoid burning the budget you need for the rest of the day.
|
|
43
|
+
|
|
44
|
+
## Increasing the quota
|
|
45
|
+
|
|
46
|
+
In the Google Cloud Console, go to **IAM & Admin** :material-arrow-right:
|
|
47
|
+
**Quotas** and file a quota increase request for the YouTube Data API.
|
|
48
|
+
Google's response time varies; expect a couple of days.
|
|
49
|
+
|
|
50
|
+
Reference:
|
|
51
|
+
[YouTube quota documentation](https://developers.google.com/youtube/v3/getting-started#quota).
|
|
@@ -40,7 +40,20 @@ ytstudio comments reject <comment-id> --ban # also ban the author
|
|
|
40
40
|
`reject` hides the comment from public view. Pass `--ban` to also ban the
|
|
41
41
|
author from the channel.
|
|
42
42
|
|
|
43
|
+
## Reply
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
ytstudio comments reply <comment-id> --text "Thanks for watching!"
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
`reply` posts a public reply to a comment and prints the new reply id.
|
|
50
|
+
Replies are flat on YouTube: `<comment-id>` must be a **top-level** comment
|
|
51
|
+
id (the `id` shown by `comments list`), not the id of another reply. Passing
|
|
52
|
+
a reply id (or an otherwise invalid id) returns a clear error. Like
|
|
53
|
+
`publish` and `reject`, `reply` executes immediately.
|
|
54
|
+
|
|
43
55
|
!!! note "Quota"
|
|
44
56
|
|
|
45
|
-
`comments.setModerationStatus`
|
|
46
|
-
larger moderation runs, see
|
|
57
|
+
`comments.setModerationStatus` and `comments.insert` (reply) each cost
|
|
58
|
+
about 50 quota units per call. For larger moderation runs, see
|
|
59
|
+
[API quota](api-quota.md).
|
|
@@ -9,7 +9,7 @@ A small CLI on top of the official
|
|
|
9
9
|
[YouTube Data API](https://developers.google.com/youtube/v3) and
|
|
10
10
|
[YouTube Analytics API](https://developers.google.com/youtube/analytics) that
|
|
11
11
|
allows for bulk video updates and uploads, scripted analytics queries,
|
|
12
|
-
comment moderation,
|
|
12
|
+
comment moderation, live broadcast control, and bulk playlist operations.
|
|
13
13
|
|
|
14
14
|
## Why it exists
|
|
15
15
|
|
|
@@ -35,6 +35,9 @@ and plug your channel into AI agent workflows.
|
|
|
35
35
|
See [Live broadcasts](livestreams.md).
|
|
36
36
|
- **Comment moderation** at the CLI:
|
|
37
37
|
approve, reject, or ban in bulk. See [Comments](comments.md).
|
|
38
|
+
- **Bulk playlist operations** including adding a search
|
|
39
|
+
query's worth of videos at once and reordering by views. See
|
|
40
|
+
[Playlists](playlists.md).
|
|
38
41
|
- **OAuth credentials live owner-only
|
|
39
42
|
(`0600`)** under `~/.config/ytstudio-cli/`. The `init` step is one-shot.
|
|
40
43
|
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# Playlists
|
|
2
|
+
|
|
3
|
+
Bulk operations on YouTube playlists from the terminal. YouTube Studio is fine
|
|
4
|
+
for tweaking one playlist; this set of commands is for the cases where you
|
|
5
|
+
want to add a search query's worth of videos at once, reorder by views, or
|
|
6
|
+
sync a manifest across many channels.
|
|
7
|
+
|
|
8
|
+
## List and inspect
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
ytstudio playlists list # your playlists
|
|
12
|
+
ytstudio playlists list -n 200 -o json # 200, JSON
|
|
13
|
+
ytstudio playlists list -o csv > playlists.csv # export
|
|
14
|
+
|
|
15
|
+
ytstudio playlists show PL_xxx # one playlist
|
|
16
|
+
ytstudio playlists show PL_xxx --items # plus the first 50 items
|
|
17
|
+
ytstudio playlists items PL_xxx # full item listing
|
|
18
|
+
ytstudio playlists items PL_xxx -n 500 -o csv # paginated CSV
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
`list` sorts locally with `--sort date|title|count`. `items` shows the
|
|
22
|
+
playlist item id (`PLPLI...`) you need for `remove --item` and `reorder`.
|
|
23
|
+
|
|
24
|
+
## Create, update, delete
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
ytstudio playlists create --title "Best of 2026" --privacy public --execute
|
|
28
|
+
ytstudio playlists update PL_xxx --title "Best of 2026 (final)" --execute
|
|
29
|
+
ytstudio playlists delete PL_xxx --execute # asks to confirm
|
|
30
|
+
ytstudio playlists delete PL_xxx --execute --yes # no prompt (CI / agents)
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Mutations are **dry-run by default**; add `--execute` to apply. `update` only
|
|
34
|
+
sends the fields you pass; everything else is re-specified from the current
|
|
35
|
+
snippet so YouTube does not silently nuke a field by omitting it.
|
|
36
|
+
|
|
37
|
+
The channel's auto-uploads playlist (`UU...` belonging to your channel) is
|
|
38
|
+
always refused. The check resolves the canonical uploads id via
|
|
39
|
+
`channels.list(mine=True).contentDetails.relatedPlaylists.uploads`, so a
|
|
40
|
+
random other playlist id that happens to start with `UU` is not blocked.
|
|
41
|
+
|
|
42
|
+
## Bulk add
|
|
43
|
+
|
|
44
|
+
`add` accepts explicit video ids, a search query, or both. The combined batch
|
|
45
|
+
is capped by `--limit`.
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
ytstudio playlists add PL_xxx -v vid_a -v vid_b --execute
|
|
49
|
+
ytstudio playlists add PL_xxx --from-search "shorts compilation" -n 20 --execute
|
|
50
|
+
ytstudio playlists add PL_xxx -v vid_a --from-search "topic" -n 10 --execute
|
|
51
|
+
ytstudio playlists add PL_xxx -v vid_a -v vid_b --position 5 --execute
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
`--from-search` calls `search.list(forMine=True, type=video, q=...)`.
|
|
55
|
+
`--position N` inserts the first video at position `N`, the second at `N+1`,
|
|
56
|
+
and so on, so the on-playlist order matches the CLI order. `--note "text"`
|
|
57
|
+
attaches a per-item note.
|
|
58
|
+
|
|
59
|
+
!!! warning "Quota cost"
|
|
60
|
+
|
|
61
|
+
`playlistItems.insert` costs 50 quota units per video. The default daily
|
|
62
|
+
quota (10 000 units) covers ~200 inserts. `search.list` costs an
|
|
63
|
+
additional 100 units per call. See [API quota](api-quota.md).
|
|
64
|
+
|
|
65
|
+
## Bulk remove
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
ytstudio playlists remove PL_xxx --item PLPLI_a --item PLPLI_b --execute
|
|
69
|
+
ytstudio playlists remove PL_xxx --video vid_a --execute
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
`--video` resolves to every playlist item for that video in the playlist and
|
|
73
|
+
removes all occurrences; pass the same id once even if it appears multiple
|
|
74
|
+
times.
|
|
75
|
+
|
|
76
|
+
## Reorder
|
|
77
|
+
|
|
78
|
+
`reorder` sorts the playlist by views, likes, publish date, or title.
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
ytstudio playlists reorder PL_xxx --by views --execute
|
|
82
|
+
ytstudio playlists reorder PL_xxx --by title --order asc --execute
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
The playlist must be set to **Manual** sort in YouTube Studio
|
|
86
|
+
(Settings -> Sort by -> Manual). If it is not, YouTube returns
|
|
87
|
+
`manualSortRequired` and the command stops with an actionable message.
|
|
88
|
+
|
|
89
|
+
Writes that become no-ops once earlier moves have shifted neighbouring items
|
|
90
|
+
are skipped, so a full reverse on N items costs at most `N - 1` writes
|
|
91
|
+
instead of `N`.
|
|
92
|
+
|
|
93
|
+
## Output formats
|
|
94
|
+
|
|
95
|
+
All read commands take `--output table|json|csv`. CSV uses Python's
|
|
96
|
+
`csv.writer`, so titles with commas, newlines, or quotes survive round-trips
|
|
97
|
+
through Excel and `pandas.read_csv`.
|
|
98
|
+
|
|
99
|
+
## Recipes
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
# Build a themed playlist from a search
|
|
103
|
+
ytstudio playlists add PL_rust --from-search "rust async" -n 30 --execute
|
|
104
|
+
|
|
105
|
+
# Move the all-time top by views to the front
|
|
106
|
+
ytstudio playlists reorder PL_pinned --by views --execute
|
|
107
|
+
|
|
108
|
+
# Promote a single video to the top of an existing playlist
|
|
109
|
+
ytstudio playlists add PL_pinned -v <video-id> --position 0 --execute
|
|
110
|
+
```
|
|
@@ -12,6 +12,7 @@ ytstudio videos list # most recent uploads
|
|
|
12
12
|
ytstudio videos list -n 100 -o json # 100 items, JSON
|
|
13
13
|
ytstudio videos list --scheduled # only videos scheduled for future publish
|
|
14
14
|
ytstudio videos show <video-id> # full metadata for one video
|
|
15
|
+
ytstudio videos categories # category ids you can assign to uploads
|
|
15
16
|
```
|
|
16
17
|
|
|
17
18
|
`--scheduled` filters to private videos with a future `publishAt`, which is
|
|
@@ -96,11 +96,13 @@ nav:
|
|
|
96
96
|
- Multi-channel profiles: profiles.md
|
|
97
97
|
- Live broadcasts: livestreams.md
|
|
98
98
|
- Videos (bulk update, upload): videos.md
|
|
99
|
+
- Playlists: playlists.md
|
|
99
100
|
- Analytics: analytics.md
|
|
100
101
|
- Comments: comments.md
|
|
101
102
|
- Reference:
|
|
102
103
|
- Commands: reference.md
|
|
103
104
|
- API quota: api-quota.md
|
|
105
|
+
- Agent skill: agent-skill.md
|
|
104
106
|
|
|
105
107
|
extra:
|
|
106
108
|
social:
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
"""Regenerate the agent skill's bundled command reference from the live typer app.
|
|
2
|
+
|
|
3
|
+
The skill at ``skills/ytstudio/`` ships a trimmed command reference so an agent
|
|
4
|
+
can read the full flag surface on demand without running ``--help`` for every
|
|
5
|
+
command. Unlike ``docs/reference.md`` (built on the fly by mkdocs and
|
|
6
|
+
git-ignored), this file is checked into git because it travels with the skill
|
|
7
|
+
when it is installed from the repo. It must therefore be kept in sync with the
|
|
8
|
+
CLI: ``tests/test_skill_reference.py`` fails if the committed file drifts.
|
|
9
|
+
|
|
10
|
+
Run after changing the CLI surface:
|
|
11
|
+
|
|
12
|
+
uv run python scripts/build_skill_reference.py
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
import subprocess
|
|
18
|
+
import sys
|
|
19
|
+
from pathlib import Path
|
|
20
|
+
|
|
21
|
+
REPO_ROOT = Path(__file__).resolve().parent.parent
|
|
22
|
+
REFERENCE = REPO_ROOT / "skills" / "ytstudio" / "references" / "reference.md"
|
|
23
|
+
|
|
24
|
+
BANNER = (
|
|
25
|
+
"<!-- Generated by scripts/build_skill_reference.py from the ytstudio CLI.\n"
|
|
26
|
+
" Do not edit by hand; run `uv run python scripts/build_skill_reference.py`. -->\n\n"
|
|
27
|
+
)
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def render() -> str:
|
|
31
|
+
"""Return the command reference markdown rendered from the typer app."""
|
|
32
|
+
# typer ships its own CLI; `python -m typer` avoids depending on a
|
|
33
|
+
# console-script being on PATH, mirroring scripts/build_docs_reference.py.
|
|
34
|
+
cmd = [
|
|
35
|
+
sys.executable,
|
|
36
|
+
"-m",
|
|
37
|
+
"typer",
|
|
38
|
+
"ytstudio.main",
|
|
39
|
+
"utils",
|
|
40
|
+
"docs",
|
|
41
|
+
"--name",
|
|
42
|
+
"ytstudio",
|
|
43
|
+
]
|
|
44
|
+
result = subprocess.run(cmd, capture_output=True, text=True, check=True)
|
|
45
|
+
|
|
46
|
+
text = result.stdout
|
|
47
|
+
# Lift the top-level heading so it reads as a reference, not a command name.
|
|
48
|
+
if text.lstrip().startswith("# `ytstudio`"):
|
|
49
|
+
text = text.replace("# `ytstudio`", "# Command reference", 1)
|
|
50
|
+
# Exactly one trailing newline, matching the end-of-file-fixer pre-commit hook
|
|
51
|
+
# so the committed file and a fresh render stay byte-identical.
|
|
52
|
+
return BANNER + text.strip() + "\n"
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def main() -> None:
|
|
56
|
+
REFERENCE.parent.mkdir(parents=True, exist_ok=True)
|
|
57
|
+
REFERENCE.write_text(render())
|
|
58
|
+
print(f"wrote {REFERENCE.relative_to(REPO_ROOT)}")
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
if __name__ == "__main__":
|
|
62
|
+
main()
|