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.
Files changed (62) hide show
  1. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/PKG-INFO +25 -3
  2. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/README.md +24 -2
  3. ytstudio_cli-0.4.0/docs/agent-skill.md +52 -0
  4. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/docs/analytics.md +12 -4
  5. ytstudio_cli-0.4.0/docs/api-quota.md +51 -0
  6. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/docs/comments.md +15 -2
  7. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/docs/index.md +4 -1
  8. ytstudio_cli-0.4.0/docs/playlists.md +110 -0
  9. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/docs/videos.md +1 -0
  10. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/mkdocs.yml +2 -0
  11. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/pyproject.toml +1 -1
  12. ytstudio_cli-0.4.0/scripts/build_skill_reference.py +62 -0
  13. ytstudio_cli-0.4.0/skills/ytstudio/SKILL.md +238 -0
  14. ytstudio_cli-0.4.0/skills/ytstudio/assets/upload-sidecar.example.yaml +30 -0
  15. ytstudio_cli-0.4.0/skills/ytstudio/references/reference.md +951 -0
  16. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/commands/analytics.py +84 -7
  17. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/commands/comments.py +31 -0
  18. ytstudio_cli-0.4.0/src/ytstudio/commands/playlists.py +919 -0
  19. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/main.py +2 -1
  20. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/tests/conftest.py +71 -0
  21. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/tests/test_analytics.py +106 -0
  22. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/tests/test_comments.py +27 -0
  23. ytstudio_cli-0.4.0/tests/test_playlists.py +705 -0
  24. ytstudio_cli-0.4.0/tests/test_skill_reference.py +31 -0
  25. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/uv.lock +1 -1
  26. ytstudio_cli-0.3.1/docs/api-quota.md +0 -44
  27. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/.editorconfig +0 -0
  28. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/.github/workflows/ci.yml +0 -0
  29. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/.github/workflows/docs.yml +0 -0
  30. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/.gitignore +0 -0
  31. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/.pre-commit-config.yaml +0 -0
  32. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/.python-version +0 -0
  33. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/LICENSE +0 -0
  34. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/ascii.png +0 -0
  35. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/docs/installation.md +0 -0
  36. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/docs/livestreams.md +0 -0
  37. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/docs/profiles.md +0 -0
  38. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/docs/setup.md +0 -0
  39. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/docs/stylesheets/extra.css +0 -0
  40. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/scripts/build_docs_reference.py +0 -0
  41. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/__init__.py +0 -0
  42. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/api.py +0 -0
  43. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/commands/__init__.py +0 -0
  44. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/commands/livestreams.py +0 -0
  45. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/commands/profile.py +0 -0
  46. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/commands/upload.py +0 -0
  47. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/commands/videos.py +0 -0
  48. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/config.py +0 -0
  49. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/registry.py +0 -0
  50. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/services.py +0 -0
  51. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/ui.py +0 -0
  52. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/upload_pipeline.py +0 -0
  53. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/src/ytstudio/version.py +0 -0
  54. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/tests/__init__.py +0 -0
  55. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/tests/test_api.py +0 -0
  56. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/tests/test_config.py +0 -0
  57. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/tests/test_livestreams.py +0 -0
  58. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/tests/test_profile.py +0 -0
  59. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/tests/test_registry.py +0 -0
  60. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/tests/test_upload_command.py +0 -0
  61. {ytstudio_cli-0.3.1 → ytstudio_cli-0.4.0}/tests/test_upload_pipeline.py +0 -0
  62. {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.1
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 moderate from the CLI.
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 moderate from the CLI.
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 '.rows[0]'
65
+ ytstudio analytics overview -o json | jq '.pct_change'
59
66
  ```
60
67
 
61
68
  ## Quota
62
69
 
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.
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` costs about 50 quota units per call. For
46
- larger moderation runs, see [API quota](api-quota.md).
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, and live broadcast control.
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:
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "ytstudio-cli"
3
- version = "0.3.1"
3
+ version = "0.4.0"
4
4
  description = "Manage and analyze your YouTube channel from the terminal. Designed for humans and AI agents."
5
5
  readme = "README.md"
6
6
  license = { text = "MIT" }
@@ -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()