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.
- ytstudio_cli-0.4.2/.github/workflows/ci.yml +22 -0
- ytstudio_cli-0.4.2/.github/workflows/release.yml +96 -0
- ytstudio_cli-0.4.2/.github/workflows/test.yml +76 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/PKG-INFO +4 -8
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/README.md +3 -7
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/docs/profiles.md +0 -10
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/docs/setup.md +1 -2
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/mkdocs.yml +0 -1
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/pyproject.toml +4 -3
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/skills/ytstudio/SKILL.md +50 -7
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/skills/ytstudio/references/reference.md +2 -1
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/api.py +19 -10
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/commands/analytics.py +102 -3
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/config.py +31 -4
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/main.py +18 -1
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/test_analytics.py +235 -0
- ytstudio_cli-0.4.2/tests/test_api.py +411 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/test_comments.py +25 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/test_config.py +43 -1
- ytstudio_cli-0.4.2/tests/test_main.py +45 -0
- ytstudio_cli-0.4.2/tests/test_version.py +84 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/uv.lock +1 -1
- ytstudio_cli-0.4.0/.github/workflows/ci.yml +0 -56
- ytstudio_cli-0.4.0/docs/agent-skill.md +0 -52
- ytstudio_cli-0.4.0/tests/test_api.py +0 -195
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/.editorconfig +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/.github/workflows/docs.yml +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/.gitignore +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/.pre-commit-config.yaml +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/.python-version +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/LICENSE +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/ascii.png +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/docs/analytics.md +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/docs/api-quota.md +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/docs/comments.md +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/docs/index.md +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/docs/installation.md +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/docs/livestreams.md +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/docs/playlists.md +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/docs/stylesheets/extra.css +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/docs/videos.md +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/scripts/build_docs_reference.py +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/scripts/build_skill_reference.py +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/skills/ytstudio/assets/upload-sidecar.example.yaml +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/__init__.py +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/commands/__init__.py +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/commands/comments.py +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/commands/livestreams.py +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/commands/playlists.py +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/commands/profile.py +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/commands/upload.py +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/commands/videos.py +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/registry.py +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/services.py +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/ui.py +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/upload_pipeline.py +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/src/ytstudio/version.py +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/__init__.py +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/conftest.py +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/test_livestreams.py +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/test_playlists.py +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/test_profile.py +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/test_registry.py +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/test_skill_reference.py +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/test_upload_command.py +0 -0
- {ytstudio_cli-0.4.0 → ytstudio_cli-0.4.2}/tests/test_upload_pipeline.py +0 -0
- {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.
|
|
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
|
-
|
|
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).
|
|
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
|
-
|
|
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).
|
|
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)).
|
|
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.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "ytstudio-cli"
|
|
3
|
-
version = "0.4.
|
|
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:
|
|
65
|
-
yts = "ytstudio.main:
|
|
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.
|
|
155
|
-
|
|
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
|
|
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
|
-
`
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
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
|
|
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
|
|