ytstudio-cli 0.4.0__tar.gz → 0.4.2__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 (67) hide show
  1. ytstudio_cli-0.4.2/.github/workflows/ci.yml +22 -0
  2. ytstudio_cli-0.4.2/.github/workflows/release.yml +96 -0
  3. ytstudio_cli-0.4.2/.github/workflows/test.yml +76 -0
  4. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/PKG-INFO +4 -8
  5. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/README.md +3 -7
  6. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/docs/profiles.md +0 -10
  7. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/docs/setup.md +1 -2
  8. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/mkdocs.yml +0 -1
  9. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/pyproject.toml +4 -3
  10. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/skills/ytstudio/SKILL.md +50 -7
  11. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/skills/ytstudio/references/reference.md +2 -1
  12. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/api.py +19 -10
  13. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/commands/analytics.py +102 -3
  14. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/config.py +31 -4
  15. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/main.py +18 -1
  16. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/test_analytics.py +235 -0
  17. ytstudio_cli-0.4.2/tests/test_api.py +411 -0
  18. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/test_comments.py +25 -0
  19. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/test_config.py +43 -1
  20. ytstudio_cli-0.4.2/tests/test_main.py +45 -0
  21. ytstudio_cli-0.4.2/tests/test_version.py +84 -0
  22. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/uv.lock +1 -1
  23. ytstudio_cli-0.4.0/.github/workflows/ci.yml +0 -56
  24. ytstudio_cli-0.4.0/docs/agent-skill.md +0 -52
  25. ytstudio_cli-0.4.0/tests/test_api.py +0 -195
  26. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/.editorconfig +0 -0
  27. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/.github/workflows/docs.yml +0 -0
  28. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/.gitignore +0 -0
  29. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/.pre-commit-config.yaml +0 -0
  30. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/.python-version +0 -0
  31. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/LICENSE +0 -0
  32. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/ascii.png +0 -0
  33. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/docs/analytics.md +0 -0
  34. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/docs/api-quota.md +0 -0
  35. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/docs/comments.md +0 -0
  36. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/docs/index.md +0 -0
  37. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/docs/installation.md +0 -0
  38. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/docs/livestreams.md +0 -0
  39. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/docs/playlists.md +0 -0
  40. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/docs/stylesheets/extra.css +0 -0
  41. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/docs/videos.md +0 -0
  42. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/scripts/build_docs_reference.py +0 -0
  43. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/scripts/build_skill_reference.py +0 -0
  44. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/skills/ytstudio/assets/upload-sidecar.example.yaml +0 -0
  45. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/__init__.py +0 -0
  46. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/commands/__init__.py +0 -0
  47. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/commands/comments.py +0 -0
  48. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/commands/livestreams.py +0 -0
  49. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/commands/playlists.py +0 -0
  50. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/commands/profile.py +0 -0
  51. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/commands/upload.py +0 -0
  52. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/commands/videos.py +0 -0
  53. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/registry.py +0 -0
  54. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/services.py +0 -0
  55. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/ui.py +0 -0
  56. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/upload_pipeline.py +0 -0
  57. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/version.py +0 -0
  58. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/__init__.py +0 -0
  59. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/conftest.py +0 -0
  60. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/test_livestreams.py +0 -0
  61. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/test_playlists.py +0 -0
  62. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/test_profile.py +0 -0
  63. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/test_registry.py +0 -0
  64. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/test_skill_reference.py +0 -0
  65. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/test_upload_command.py +0 -0
  66. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/test_upload_pipeline.py +0 -0
  67. {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/test_videos.py +0 -0
@@ -0,0 +1,22 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+
9
+ concurrency:
10
+ group: ${{ github.workflow }}-${{ github.ref }}
11
+ cancel-in-progress: true
12
+
13
+ permissions:
14
+ contents: read
15
+
16
+ jobs:
17
+ test:
18
+ uses: ./.github/workflows/test.yml
19
+ with:
20
+ coverage: true
21
+ secrets:
22
+ codecov_token: ${{ secrets.CODECOV_TOKEN }}
@@ -0,0 +1,96 @@
1
+ name: Release
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ - "v*"
7
+
8
+ concurrency:
9
+ group: ${{ github.workflow }}-${{ github.ref }}
10
+ cancel-in-progress: false
11
+
12
+ permissions:
13
+ contents: read
14
+
15
+ jobs:
16
+ test:
17
+ uses: ./.github/workflows/test.yml
18
+
19
+ build:
20
+ needs: test
21
+ runs-on: ubuntu-latest
22
+
23
+ steps:
24
+ - uses: actions/checkout@v6
25
+
26
+ - name: Install uv
27
+ uses: astral-sh/setup-uv@v7
28
+ with:
29
+ enable-cache: true
30
+
31
+ - name: Set up Python
32
+ run: uv python install 3.12
33
+
34
+ - name: Verify version consistency
35
+ run: |
36
+ uv run python - <<'PY'
37
+ import os
38
+ import tomllib
39
+
40
+ with open("pyproject.toml", "rb") as f:
41
+ pyproject_version = tomllib.load(f)["project"]["version"]
42
+
43
+ with open("uv.lock", "rb") as f:
44
+ lock = tomllib.load(f)
45
+ lock_version = next(
46
+ package["version"]
47
+ for package in lock["package"]
48
+ if package["name"] == "ytstudio-cli"
49
+ )
50
+
51
+ tag = os.environ["GITHUB_REF"]
52
+ expected_tag = f"refs/tags/v{pyproject_version}"
53
+ if lock_version != pyproject_version:
54
+ raise SystemExit(
55
+ f"uv.lock version {lock_version} does not match "
56
+ f"pyproject.toml version {pyproject_version}"
57
+ )
58
+ if tag != expected_tag:
59
+ raise SystemExit(f"tag {tag} does not match package version {expected_tag}")
60
+ PY
61
+
62
+ - name: Build package
63
+ run: uv build
64
+
65
+ - name: Smoke test wheel
66
+ run: |
67
+ uv venv /tmp/ytstudio-smoke
68
+ uv pip install --python /tmp/ytstudio-smoke/bin/python dist/*.whl
69
+ /tmp/ytstudio-smoke/bin/ytstudio --version
70
+ /tmp/ytstudio-smoke/bin/yts --version
71
+ /tmp/ytstudio-smoke/bin/ytstudio --help
72
+ /tmp/ytstudio-smoke/bin/ytstudio videos --help
73
+
74
+ - name: Upload dist artifacts
75
+ uses: actions/upload-artifact@v4
76
+ with:
77
+ name: dist
78
+ path: dist/
79
+
80
+ publish:
81
+ needs: build
82
+ runs-on: ubuntu-latest
83
+ environment: pypi
84
+
85
+ permissions:
86
+ id-token: write
87
+
88
+ steps:
89
+ - name: Download dist artifacts
90
+ uses: actions/download-artifact@v4
91
+ with:
92
+ name: dist
93
+ path: dist/
94
+
95
+ - name: Publish to PyPI
96
+ uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,76 @@
1
+ name: Test
2
+
3
+ on:
4
+ workflow_call:
5
+ inputs:
6
+ coverage:
7
+ description: "Report and upload coverage (3.12 only)"
8
+ type: boolean
9
+ default: false
10
+ secrets:
11
+ codecov_token:
12
+ required: false
13
+
14
+ permissions:
15
+ contents: read
16
+
17
+ jobs:
18
+ test:
19
+ runs-on: ubuntu-latest
20
+ strategy:
21
+ matrix:
22
+ python-version: ["3.12", "3.13"]
23
+
24
+ steps:
25
+ - uses: actions/checkout@v6
26
+
27
+ - name: Install uv
28
+ uses: astral-sh/setup-uv@v7
29
+ with:
30
+ enable-cache: true
31
+
32
+ - name: Set up Python ${{ matrix.python-version }}
33
+ run: uv python install ${{ matrix.python-version }}
34
+
35
+ - name: Install dependencies
36
+ run: uv sync --locked --group dev
37
+
38
+ - name: Lint with ruff
39
+ run: |
40
+ uv run ruff check src tests scripts
41
+ uv run ruff format --check src tests scripts
42
+
43
+ - name: Run tests
44
+ run: uv run pytest
45
+
46
+ - name: Write coverage summary
47
+ if: inputs.coverage && matrix.python-version == '3.12'
48
+ run: |
49
+ {
50
+ echo "## Coverage"
51
+ echo
52
+ echo '```text'
53
+ uv run coverage report
54
+ echo '```'
55
+ } >> "$GITHUB_STEP_SUMMARY"
56
+
57
+ - name: Generate HTML coverage report
58
+ if: inputs.coverage && matrix.python-version == '3.12'
59
+ run: uv run coverage html
60
+
61
+ - name: Upload coverage artifacts
62
+ if: inputs.coverage && matrix.python-version == '3.12'
63
+ uses: actions/upload-artifact@v4
64
+ with:
65
+ name: coverage-report
66
+ path: |
67
+ coverage.xml
68
+ htmlcov/
69
+
70
+ - name: Upload coverage to Codecov
71
+ if: inputs.coverage && matrix.python-version == '3.12'
72
+ uses: codecov/codecov-action@v5
73
+ with:
74
+ files: coverage.xml
75
+ fail_ci_if_error: false
76
+ token: ${{ secrets.codecov_token }}
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ytstudio-cli
3
- Version: 0.4.0
3
+ Version: 0.4.2
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
@@ -34,6 +34,7 @@ Description-Content-Type: text/markdown
34
34
 
35
35
  <p align="center">
36
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
+ <a href="https://codecov.io/gh/jdwit/ytstudio-cli"><img src="https://codecov.io/gh/jdwit/ytstudio-cli/branch/main/graph/badge.svg" alt="Coverage"></a>
37
38
  <a href="https://pypi.org/project/ytstudio-cli/"><img src="https://img.shields.io/pypi/v/ytstudio-cli" alt="PyPI"></a>
38
39
  <a href="https://pypi.org/project/ytstudio-cli/"><img src="https://img.shields.io/pypi/pyversions/ytstudio-cli" alt="Python"></a>
39
40
  </p>
@@ -70,14 +71,9 @@ See the [full documentation](https://jdwit.github.io/ytstudio-cli/) for installa
70
71
 
71
72
  ## Agent skill
72
73
 
73
- ytstudio ships a harness-agnostic [agent skill](skills/ytstudio/SKILL.md) that
74
+ This repo includes a harness-agnostic [agent skill](skills/ytstudio/SKILL.md) that
74
75
  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.
76
+ the open [SKILL standard](https://agentskills.io).
81
77
 
82
78
  ## Development
83
79
 
@@ -6,6 +6,7 @@
6
6
 
7
7
  <p align="center">
8
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
+ <a href="https://codecov.io/gh/jdwit/ytstudio-cli"><img src="https://codecov.io/gh/jdwit/ytstudio-cli/branch/main/graph/badge.svg" alt="Coverage"></a>
9
10
  <a href="https://pypi.org/project/ytstudio-cli/"><img src="https://img.shields.io/pypi/v/ytstudio-cli" alt="PyPI"></a>
10
11
  <a href="https://pypi.org/project/ytstudio-cli/"><img src="https://img.shields.io/pypi/pyversions/ytstudio-cli" alt="Python"></a>
11
12
  </p>
@@ -42,14 +43,9 @@ See the [full documentation](https://jdwit.github.io/ytstudio-cli/) for installa
42
43
 
43
44
  ## Agent skill
44
45
 
45
- ytstudio ships a harness-agnostic [agent skill](skills/ytstudio/SKILL.md) that
46
+ This repo includes a harness-agnostic [agent skill](skills/ytstudio/SKILL.md) that
46
47
  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.
48
+ the open [SKILL standard](https://agentskills.io).
53
49
 
54
50
  ## Development
55
51
 
@@ -42,13 +42,3 @@ YTSTUDIO_PROFILE=work ytstudio videos list
42
42
  Profile directories are `0700`; credential files are `0600`. State writes go
43
43
  through an atomic temp + rename and are serialized under an `fcntl` lock, so
44
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.
@@ -68,8 +68,7 @@ ytstudio status # show the authenticated channel for the active profile
68
68
  ```
69
69
 
70
70
  To remove credentials for a channel, use `ytstudio profile remove <name>` (see
71
- [Multi-channel profiles](profiles.md)). On a fresh single-channel install the
72
- active profile is `default`.
71
+ [Multi-channel profiles](profiles.md)).
73
72
 
74
73
  If you run more than one channel, head to
75
74
  [Multi-channel profiles](profiles.md) next.
@@ -102,7 +102,6 @@ nav:
102
102
  - Reference:
103
103
  - Commands: reference.md
104
104
  - API quota: api-quota.md
105
- - Agent skill: agent-skill.md
106
105
 
107
106
  extra:
108
107
  social:
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "ytstudio-cli"
3
- version = "0.4.0"
3
+ version = "0.4.2"
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" }
@@ -58,11 +58,12 @@ exclude_lines = [
58
58
  "pragma: no cover",
59
59
  "if TYPE_CHECKING:",
60
60
  "raise NotImplementedError",
61
+ "if __name__ == .__main__.:",
61
62
  ]
62
63
 
63
64
  [project.scripts]
64
- ytstudio = "ytstudio.main:app"
65
- yts = "ytstudio.main:app"
65
+ ytstudio = "ytstudio.main:cli"
66
+ yts = "ytstudio.main:cli"
66
67
 
67
68
  [project.urls]
68
69
  Homepage = "https://github.com/jdwit/ytstudio-cli"
@@ -5,6 +5,11 @@ license: MIT
5
5
  metadata:
6
6
  project: ytstudio-cli
7
7
  repository: https://github.com/jdwit/ytstudio-cli
8
+ keywords:
9
+ - youtube
10
+ - youtube-studio
11
+ - youtube-channel
12
+ - youtube-analytics
8
13
  ---
9
14
 
10
15
  # ytstudio
@@ -70,6 +75,16 @@ ytstudio status # confirms the authenticated channel
70
75
  On a headless box, use `ytstudio login --headless`: it prints a URL to open in
71
76
  any browser, then you paste the failed `127.0.0.1` redirect URL back in.
72
77
 
78
+ If `ytstudio login` fails with `access_denied`:
79
+
80
+ - Sign in with the Google account that owns the channel.
81
+ - If the OAuth app is still in "Testing", add that account under Google Cloud
82
+ Console -> APIs & Services -> OAuth consent screen -> Test users.
83
+ - Click through the "Google hasn't verified this app" warning via Advanced ->
84
+ Continue.
85
+ - Approve all requested (read-only) scopes; do not close the tab until it
86
+ reports success.
87
+
73
88
  Credentials live owner-only under `~/.config/ytstudio-cli/`. This step is
74
89
  one-shot per channel; do not re-run it unless auth is actually broken.
75
90
 
@@ -100,6 +115,8 @@ rather than guessing - or run `ytstudio <group> <command> --help`.
100
115
 
101
116
  ```bash
102
117
  ytstudio videos list -n 100 -o json # recent uploads, parseable
118
+ ytstudio videos list --sort views -n 100 -o json # fetched videos sorted by lifetime views
119
+ ytstudio videos list --sort likes -n 100 -o json # fetched videos sorted by lifetime likes
103
120
  ytstudio videos list --scheduled # only future-dated publishes
104
121
  ytstudio videos show <video-id> -o json # full metadata for one video
105
122
  ytstudio videos categories # category ids assignable on upload
@@ -113,6 +130,13 @@ ytstudio videos search-replace -s "2024" -r "2025" -f title
113
130
  ytstudio videos search-replace -s 'season \d' -r 'season X' -f title --regex --execute
114
131
  ```
115
132
 
133
+ `videos list --sort views|likes` sorts the fetched uploads by lifetime Data API
134
+ statistics, so raise `-n` when you need broader channel coverage; use
135
+ `analytics query -d video` for exact period-specific rankings. `videos show -o
136
+ json` returns a flat object with fields such as `title`, `published_at`,
137
+ `views`, `likes`, `comments`, `privacy`, `tags`, `localizations`, and
138
+ `scheduled_publish_at`.
139
+
116
140
  `search-replace` requires `-s/--search`, `-r/--replace`, and `-f/--field`
117
141
  (`title` or `description`); `--limit` caps how many matches it acts on (default
118
142
  10). Preview the dry-run, confirm the match set is what the user intended, then
@@ -146,29 +170,48 @@ ytstudio analytics dimensions # discoverable dimension names
146
170
  # Custom query straight against the Analytics API reports.query endpoint:
147
171
  ytstudio analytics query -m views,likes -d day --days 7 -o json
148
172
  ytstudio analytics query -m views -d country --sort -views -n 10 -o json
173
+ ytstudio analytics query -m views -d video --days 180 --sort -views -n 10 --resolve -o json
149
174
  ytstudio analytics query -m views -d insightTrafficSourceType -f video==<id> -o json
150
175
  ```
151
176
 
152
177
  `analytics query` needs `-m/--metrics`; `-d/--dimensions`, `-f/--filter`
153
178
  (`key==value`, repeatable), `--sort` (prefix `-` for descending), `-n/--limit`,
154
- and date range (`--days` or `-s/-e` start/end) are optional. When unsure which
155
- metric or dimension exists, list them first with `analytics metrics` /
179
+ and date range (`--days` or `-s/-e` start/end) are optional. `-d video` and
180
+ `-d playlist` return IDs; add `--resolve` to include `videoTitle` /
181
+ `playlistTitle` columns in table, JSON, or CSV output. When unsure which metric
182
+ or dimension exists, list them first with `analytics metrics` /
156
183
  `analytics dimensions` instead of guessing names.
157
184
 
185
+ For `-d month` (and `-d week`), the CLI snaps `-s`/`-e` down to the boundary the
186
+ YouTube Analytics API requires (first of the month), so `--days` and arbitrary
187
+ dates just work. The range is inclusive on both ends, so the end month is the
188
+ last month you want, not the month after.
189
+
190
+ ```bash
191
+ # 12 months, Jun 2025 through May 2026:
192
+ ytstudio analytics query -m views -d month -s 2025-06-01 -e 2026-05-01
193
+ ```
194
+
158
195
  ### comments - moderation
159
196
 
160
197
  ```bash
198
+ ytstudio comments list -o json # recent comments across the channel
161
199
  ytstudio comments list --status held -o json # the moderation queue
162
- ytstudio comments list -v <video-id> -n 50 -o json
200
+ ytstudio comments list --status spam -o json # likely spam comments
201
+ ytstudio comments list --sort time -o json # channel-wide newest first
202
+ ytstudio comments list -v <video-id> --sort relevance -n 50 -o json
163
203
  ytstudio comments publish <comment-id> [<comment-id> ...] # approve held; executes immediately
164
204
  ytstudio comments reject <comment-id> --ban # reject (+ optional ban); executes immediately
165
205
  ytstudio comments reply <comment-id> -t "Thanks!" # executes immediately
166
206
  ```
167
207
 
168
- `publish`/`reject` take one or more comment ids and execute immediately (no
169
- `--execute` dry-run). `reply` also posts immediately. Confirm the exact comment
170
- ids/text first. `--ban` on `reject` also bans the author - only use it when the
171
- user explicitly asks to ban.
208
+ `comments list` without `-v/--video` is channel-wide. Use `--status spam` for
209
+ spam review. Channel-wide listing supports `--sort time`; `--sort relevance`
210
+ requires `-v/--video` because of a YouTube API limitation. `publish`/`reject`
211
+ take one or more comment ids and execute immediately (no `--execute` dry-run).
212
+ `reply` also posts immediately. Confirm the exact comment ids/text first.
213
+ `--ban` on `reject` also bans the author - only use it when the user explicitly
214
+ asks to ban.
172
215
 
173
216
  ### livestreams - broadcast lifecycle
174
217
 
@@ -289,7 +289,7 @@ Examples:
289
289
  ytstudio analytics query -m views,shares -d country --sort -views -n 10
290
290
 
291
291
  ytstudio analytics query -m views,estimatedMinutesWatched -d video \
292
- --sort -views -n 5 -o json
292
+ --sort -views -n 5 --resolve -o json
293
293
 
294
294
  ytstudio analytics query -m videoThumbnailImpressions,videoThumbnailImpressionsClickRate \
295
295
  -d video --sort -videoThumbnailImpressions -n 10
@@ -316,6 +316,7 @@ $ ytstudio analytics query [OPTIONS]
316
316
  * `--currency TEXT`: Currency code for revenue (e.g. EUR)
317
317
  * `-o, --output TEXT`: Output format: table, json, csv [default: table]
318
318
  * `--raw`: Show raw numbers instead of human-readable
319
+ * `--resolve`: Resolve video/playlist dimension IDs to title columns
319
320
  * `--help`: Show this message and exit.
320
321
 
321
322
  ### `ytstudio analytics metrics`
@@ -7,6 +7,7 @@ from google.oauth2.credentials import Credentials
7
7
  from google_auth_oauthlib.flow import InstalledAppFlow
8
8
  from googleapiclient.discovery import build
9
9
  from googleapiclient.errors import HttpError
10
+ from oauthlib.oauth2 import AccessDeniedError, OAuth2Error
10
11
  from rich.prompt import Prompt
11
12
 
12
13
  from ytstudio.config import (
@@ -37,7 +38,7 @@ def handle_api_error(error: HttpError) -> None:
37
38
  console.print("[red]Access denied. You may not have permission for this action.[/red]")
38
39
  raise SystemExit(1) from None
39
40
 
40
- # Re-raise for other errors
41
+ # Re-raise: command handlers or the CLI boundary (main.cli) clean it up.
41
42
  raise error
42
43
 
43
44
 
@@ -168,6 +169,22 @@ def _authenticate_headless() -> Credentials:
168
169
  return flow.credentials
169
170
 
170
171
 
172
+ def _authenticate_local_server() -> Credentials:
173
+ flow = _create_flow()
174
+ try:
175
+ return flow.run_local_server(port=9876, prompt="consent", open_browser=True)
176
+ except AccessDeniedError:
177
+ console.print(
178
+ "[red]Authorization denied.[/red] "
179
+ "Approve the requested (read-only) scopes and try again."
180
+ )
181
+ raise SystemExit(1) from None
182
+ except OAuth2Error as error:
183
+ message = getattr(error, "description", "") or str(error)
184
+ console.print(f"[red]Authorization failed: {message}[/red]")
185
+ raise SystemExit(1) from None
186
+
187
+
171
188
  def authenticate(headless: bool = False, profile: str | None = None) -> None:
172
189
  if not CLIENT_SECRETS_FILE.exists():
173
190
  console.print("[red]No client secrets found. Run 'ytstudio init' first.[/red]")
@@ -179,15 +196,7 @@ def authenticate(headless: bool = False, profile: str | None = None) -> None:
179
196
 
180
197
  console.print("[bold]Authenticating with YouTube...[/bold]\n")
181
198
 
182
- if headless:
183
- credentials = _authenticate_headless()
184
- else:
185
- flow = _create_flow()
186
- credentials = flow.run_local_server(
187
- port=9876,
188
- prompt="consent",
189
- open_browser=True,
190
- )
199
+ credentials = _authenticate_headless() if headless else _authenticate_local_server()
191
200
 
192
201
  _save_credentials(credentials, profile)
193
202
  _show_login_success(credentials, profile)
@@ -2,7 +2,7 @@ import csv
2
2
  import io
3
3
  import json
4
4
  from dataclasses import asdict, dataclass
5
- from datetime import datetime, timedelta
5
+ from datetime import date, datetime, timedelta
6
6
 
7
7
  import typer
8
8
 
@@ -318,6 +318,96 @@ def _parse_comma_list(value: str) -> list[str]:
318
318
  return [v.strip() for v in value.split(",") if v.strip()]
319
319
 
320
320
 
321
+ def _align_date_range(
322
+ dimension_names: list[str], start_date: str, end_date: str
323
+ ) -> tuple[str, str]:
324
+ """Snap dates to the boundaries the YouTube Analytics API requires.
325
+
326
+ month: both ends must be the first of a month. The API rejects other days,
327
+ it does not snap. So snap both ends DOWN to the first of their month.
328
+ week: API weeks begin on Sunday. Snap both ends back to their Sunday.
329
+ See https://developers.google.com/youtube/analytics/dimensions (time periods).
330
+ Other dimensions (day, country, ...) are returned unchanged.
331
+ """
332
+ if DimensionName.MONTH in dimension_names:
333
+ return _snap_to_month_start(start_date), _snap_to_month_start(end_date)
334
+ if "week" in dimension_names:
335
+ return _snap_to_week_start(start_date), _snap_to_week_start(end_date)
336
+ return start_date, end_date
337
+
338
+
339
+ def _snap_to_month_start(value: str) -> str:
340
+ d = date.fromisoformat(value)
341
+ return d.replace(day=1).isoformat()
342
+
343
+
344
+ def _snap_to_week_start(value: str) -> str:
345
+ # weekday(): Mon=0 .. Sun=6; days back to the preceding Sunday.
346
+ d = date.fromisoformat(value)
347
+ return (d - timedelta(days=(d.weekday() + 1) % 7)).isoformat()
348
+
349
+
350
+ def _chunks(values: list[str], size: int) -> list[list[str]]:
351
+ return [values[i : i + size] for i in range(0, len(values), size)]
352
+
353
+
354
+ def _fetch_snippet_titles(data_service, resource: str, ids: list[str]) -> dict[str, str]:
355
+ """Fetch snippet titles for YouTube Data API resources by id."""
356
+ if not ids:
357
+ return {}
358
+
359
+ titles: dict[str, str] = {}
360
+ for batch in _chunks(ids, 50):
361
+ if resource == "video":
362
+ response = api(data_service.videos().list(part="snippet", id=",".join(batch)))
363
+ elif resource == "playlist":
364
+ response = api(data_service.playlists().list(part="snippet", id=",".join(batch)))
365
+ else:
366
+ raise ValueError(f"Unsupported resource for title resolution: {resource}")
367
+
368
+ for item in response.get("items", []):
369
+ item_id = item.get("id")
370
+ title = item.get("snippet", {}).get("title")
371
+ if item_id and title is not None:
372
+ titles[item_id] = title
373
+ return titles
374
+
375
+
376
+ def _resolve_query_dimension_titles(data_service, response: dict) -> dict:
377
+ """Add title columns for video/playlist dimensions in an analytics query response."""
378
+ headers = list(response.get("columnHeaders", []))
379
+ rows = [list(row) for row in response.get("rows", [])]
380
+ header_names = [h.get("name") for h in headers]
381
+
382
+ resolvable = sorted(
383
+ (name for name in (DimensionName.VIDEO, DimensionName.PLAYLIST) if name in header_names),
384
+ key=header_names.index,
385
+ )
386
+ if not resolvable or not rows:
387
+ return response
388
+
389
+ title_maps: dict[str, dict[str, str]] = {}
390
+ for name in resolvable:
391
+ idx = header_names.index(name)
392
+ ids = list(dict.fromkeys(str(row[idx]) for row in rows if idx < len(row) and row[idx]))
393
+ title_maps[name] = _fetch_snippet_titles(data_service, name, ids)
394
+
395
+ # Insert title columns immediately after each resolved dimension. Iterate in
396
+ # reverse so earlier indices remain valid while mutating rows/headers.
397
+ for name in reversed(resolvable):
398
+ idx = header_names.index(name)
399
+ title_header = f"{name}Title"
400
+ headers.insert(
401
+ idx + 1,
402
+ {"name": title_header, "columnType": "DIMENSION", "dataType": "STRING"},
403
+ )
404
+ for row in rows:
405
+ resource_id = str(row[idx]) if idx < len(row) and row[idx] is not None else ""
406
+ row.insert(idx + 1, title_maps[name].get(resource_id))
407
+
408
+ return {**response, "columnHeaders": headers, "rows": rows}
409
+
410
+
321
411
  def _format_query_response(response: dict, output: str) -> None:
322
412
  headers = [h["name"] for h in response.get("columnHeaders", [])]
323
413
  rows = response.get("rows", [])
@@ -393,6 +483,11 @@ def query(
393
483
  currency: str = typer.Option(None, "--currency", help="Currency code for revenue (e.g. EUR)"),
394
484
  output: str = typer.Option("table", "--output", "-o", help="Output format: table, json, csv"),
395
485
  raw: bool = typer.Option(False, "--raw", help="Show raw numbers instead of human-readable"),
486
+ resolve: bool = typer.Option(
487
+ False,
488
+ "--resolve",
489
+ help="Resolve video/playlist dimension IDs to title columns",
490
+ ),
396
491
  ):
397
492
  """Run a custom analytics query with any metrics and dimensions.
398
493
 
@@ -406,7 +501,7 @@ def query(
406
501
  ytstudio analytics query -m views,shares -d country --sort -views -n 10
407
502
 
408
503
  ytstudio analytics query -m views,estimatedMinutesWatched -d video \\
409
- --sort -views -n 5 -o json
504
+ --sort -views -n 5 --resolve -o json
410
505
 
411
506
  ytstudio analytics query -m videoThumbnailImpressions,videoThumbnailImpressionsClickRate \\
412
507
  -d video --sort -videoThumbnailImpressions -n 10
@@ -449,9 +544,10 @@ def query(
449
544
  raise typer.Exit(1)
450
545
  filters_str = ";".join(filter_list)
451
546
 
452
- # Build dates
547
+ # Build dates, then snap to dimension-required boundaries (month, week).
453
548
  end_date = end or datetime.now().strftime("%Y-%m-%d")
454
549
  start_date = start or (datetime.now() - timedelta(days=days)).strftime("%Y-%m-%d")
550
+ start_date, end_date = _align_date_range(dimension_names, start_date, end_date)
455
551
 
456
552
  # The video dimension requires sort + maxResults per YouTube API docs
457
553
  if DimensionName.VIDEO in dimension_names and (not sort or not limit):
@@ -477,6 +573,9 @@ def query(
477
573
  currency=currency,
478
574
  )
479
575
 
576
+ if resolve:
577
+ response = _resolve_query_dimension_titles(data_service, response)
578
+
480
579
  _format_query_response(response, output)
481
580
 
482
581