Metadata-Version: 2.4
Name: ytsh
Version: 0.2.0
Summary: CLI system for YouTube channel intelligence
Author: raisaroj
License-Expression: MIT
Project-URL: Homepage, https://github.com/dioveath/ytsh
Project-URL: Issues, https://github.com/dioveath/ytsh/issues
Keywords: youtube,analytics,cli,oauth,sqlite
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Dynamic: license-file

## ytsh — YouTube Intelligence Shell

`ytsh` is a small CLI for pulling YouTube channel + video + analytics data and storing it locally (SQLite), so you can query and reuse it.

### Install

- **From PyPI (recommended, once published)**:

```bash
pipx install ytsh
```

- **Locally from this repo** (same result as PyPI, no publish needed):

```bash
pipx install .
```

- **From source (development)**:

```bash
pip install -e .
```

Shell completion is built in:

```bash
ytsh --install-completion
```

### Quickstart

Initialize local storage (creates the SQLite database from the bundled schema):

```bash
ytsh init
```

This migrates any pre-existing `data/youtube_ops.sqlite` from an older repo-relative install into the standard data directory on first run.

Where things live:

- **Data (SQLite DB + cache)**: `~/.local/share/ytsh` (override with `YTSH_DATA_HOME` or `XDG_DATA_HOME`)
- **Config (OAuth clients/tokens)**: `~/.config/ytsh` (override with `YTSH_CONFIG_HOME`)

Add a YouTube channel using OAuth client credentials JSON:

```bash
ytsh channels add --client-creds /path/to/google-oauth-client.json
```

List added channels:

```bash
ytsh channels list
```

List latest videos for a channel (channel id like `UC...` or handle like `@somehandle`):

```bash
ytsh videos list --channel @somehandle --limit 10
```

Spy on any public channel using your most recently added OAuth token:

```bash
ytsh spy --channel @somehandle
```

Query YouTube Analytics (defaults to last 30 days, preset `core` metrics):

```bash
ytsh analytics query --channel @somehandle
```

Common options:

```bash
ytsh analytics query --channel @somehandle --days 7
ytsh analytics query --channel @somehandle --start-date 2026-01-01 --end-date 2026-01-31
ytsh analytics query --channel @somehandle --metrics core --dimensions video --sort -views --max-results 30
ytsh spy --channel @somehandle --period month --limit 20
```

### Commands and options

#### `ytsh` (root)

```bash
ytsh --help
```

Global options:

- `--install-completion`: Install shell completion for the current shell
- `--show-completion`: Print the completion script for the current shell (so you can copy/customize it)

#### `ytsh init`

```bash
ytsh init
```

#### `ytsh channels add`

```bash
ytsh channels add --client-creds /path/to/google-oauth-client.json
```

Options:

- `--client-creds TEXT` (required): Path to Google OAuth client credentials JSON

#### `ytsh channels list`

```bash
ytsh channels list
```

#### `ytsh videos list`

```bash
ytsh videos list --channel @somehandle
```

Options:

- `--channel TEXT` (required): YouTube channel ID or channel handle
- `--limit INTEGER` (default: `10`): Number of latest videos to return, 1-50
- `--force-refresh`: Ignore cache and fetch fresh data from YouTube
- `--ttl-seconds INTEGER` (default: `600`): Cache freshness window in seconds
- `--format TEXT` (default: `default`): Output format

#### `ytsh spy`

```bash
ytsh spy --channel @somehandle
```

Returns a summary of the target public channel plus ranked popular/outlier videos for the selected time period.
The target channel does not need to be added first, but `ytsh` must already have at least one active OAuth token from `ytsh channels add`.

Options:

- `--channel TEXT` (required): Public YouTube channel ID or channel handle
- `--period TEXT` (default: `week`): Ranking period (`week`, `month`, `year`, `all`)
- `--limit INTEGER` (default: `15`): Number of ranked videos to return
- `--force-refresh`: Ignore cache and fetch fresh data from YouTube
- `--ttl-seconds INTEGER` (default: `600`): Cache freshness window in seconds
- `--format TEXT` (default: `default`): Output format
- `--max-fetch INTEGER` (default: `200`): Maximum uploads to scan when building the report

#### `ytsh analytics query`

```bash
ytsh analytics query --channel @somehandle
```

Options:

- `--channel TEXT` (required): YouTube channel ID or channel handle
- `--days INTEGER`: Date window ending today. Defaults to 30 when no explicit dates are supplied.
- `--start-date TEXT`: Start date in YYYY-MM-DD format. Use with `--end-date`.
- `--end-date TEXT`: End date in YYYY-MM-DD format. Use with `--start-date`.
- `--metrics TEXT` (default: `core`): Metric preset or comma-separated metrics
- `--dimensions TEXT` (default: empty): Comma-separated dimensions. Uses preset defaults when omitted.
- `--filters TEXT` (default: empty): Raw Analytics API filters string
- `--sort TEXT` (default: empty): Comma-separated sort expression. Uses preset defaults when omitted.
- `--max-results INTEGER` (default: `30`): Maximum rows to return
- `--force-refresh`: Ignore cache and fetch fresh data from YouTube Analytics
- `--ttl-seconds INTEGER` (default: `600`): Cache freshness window in seconds
- `--format TEXT` (default: `default`): Output format

### Config

- **Config directory**: defaults to `~/.config/ytsh`
- **Override config directory**: set `YTSH_CONFIG_HOME` (e.g. `export YTSH_CONFIG_HOME=/some/path`)
- **Data directory**: defaults to `~/.local/share/ytsh` (or `$XDG_DATA_HOME/ytsh`)
- **Override data directory**: set `YTSH_DATA_HOME`

### Help

```bash
ytsh --help
ytsh channels --help
ytsh videos --help
ytsh spy --help
ytsh analytics --help
```
