yt-stash 1.0.0__tar.gz

yt_stash-1.0.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store
+# Never commit exported cookies
+*cookies*.txt
+*cookies*.json
+*.cookies
+# Local Claude Code settings
+.claude/

yt_stash-1.0.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to yt-stash are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). For a command-line tool, the
+public interface that SemVer applies to is: command names, flags and their meaning, exit codes, and
+the environment variables and settings file described in the documentation.
+
+## [Unreleased]
+
+## [1.0.0] - 2026-10-08
+
+First public release.
+
+### Added
+
+- Interactive main menu (`yt-stash` without arguments) with arrow-key navigation, a description
+  under every entry, Esc to go back, and a built-in setup check.
+- `video` mode for one or more videos and `playlist` mode for whole playlists, with links read
+  from arguments or from a text file (`--from-file`).
+- Quality selection across a whole batch: every available resolution from 144p to 8K is
+  detected, the default is 1080p (or the highest available), and `-q` accepts `2160`, `720p`,
+  `best` and `worst`.
+- Audio-only downloads (`-a`: m4a, mp3, opus) and the video container choice (`--container`).
+- Subtitles: download, auto-generated captions and embedding (`--subs`, `--auto-subs`,
+  `--embed-subs`).
+- Members-only, private and age-restricted videos through a browser's signed-in session
+  (`--cookies-from-browser`), a `cookies.txt` file (`--cookies`), or cookies pasted for one run
+  (`--paste-cookies`); an interactive "sign in and retry" recovery.
+- Parallel downloads (`-j`), resume of interrupted downloads, skipping of files that already exist
+  (`--overwrite` to override), and automatic retries with back-off for network errors and HTTP 429.
+- Scripting support: `--yes`, automatic non-interactive mode without a terminal, a command that
+  repeats an interactive run, and the exit codes 0, 1, 2 and 130.
+- English and Turkish interface (`--lang`, `YT_STASH_LANG`, saved choice, system language).
+- Packaging for PyPI, an MIT license, a code of conduct, a security policy, contribution guidelines,
+  issue forms, and installation guides for macOS, Windows and Linux.
+
+[Unreleased]: https://github.com/ilkerkeklik01/yt-stash/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/ilkerkeklik01/yt-stash/releases/tag/v1.0.0

yt_stash-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,174 @@
+# Contributing to yt-stash
+
+Thank you for taking the time to contribute! yt-stash is a small project maintained by a volunteer, and
+every bug report, documentation fix, translation and pull request makes it better. This guide explains
+how to take part. By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Ways to contribute
+
+You don't need to write code to help:
+
+- **Report a bug** with the [bug report form](https://github.com/ilkerkeklik01/yt-stash/issues/new/choose).
+  Include `yt-stash --version`, your operating system, the exact command and the output of `-v`.
+  Remove cookies and private links first.
+- **Suggest a feature** with the feature request form. Describe the problem you want to solve before the
+  solution; it helps to find the best fit.
+- **Ask a question or share an idea** in [Discussions](https://github.com/ilkerkeklik01/yt-stash/discussions).
+- **Improve the documentation**: typos, unclear steps and missing examples are all welcome fixes.
+- **Translate**: see [docs/translating.md](docs/translating.md).
+- **Triage**: reproduce reported bugs and add details to them.
+- **Write code**: pick an issue labelled
+  [`good first issue`](https://github.com/ilkerkeklik01/yt-stash/labels/good%20first%20issue) or
+  [`help wanted`](https://github.com/ilkerkeklik01/yt-stash/labels/help%20wanted) and say that you are
+  working on it, so nobody duplicates the effort.
+
+For anything bigger than a small fix, **open an issue or discussion first**. It avoids the
+disappointment of a large pull request that doesn't fit the project's direction.
+
+## Scope
+
+yt-stash is a workflow and UX layer over yt-dlp. These guide what fits:
+
+- Behavior that yt-dlp already provides is used, not reimplemented. Bugs in extraction or downloading
+  itself belong to [yt-dlp](https://github.com/yt-dlp/yt-dlp).
+- Features should help most users and work on Linux, macOS and Windows.
+- yt-stash does not bypass DRM or paywalls, and it will not store credentials. Sign-in works through
+  browser cookies the user already has.
+- Fewer options are better than many; a feature that needs a long explanation may belong in a script.
+
+A pull request that doesn't fit will be closed with an explanation and thanks. That's never personal.
+
+## Set up your environment
+
+You need Python 3.10 or newer and git.
+
+```bash
+git clone https://github.com/ilkerkeklik01/yt-stash.git
+cd yt-stash
+python -m venv .venv
+source .venv/bin/activate                  # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+Without an activated virtual environment, call `.venv/bin/pytest`, `.venv/bin/ruff` and
+`.venv/bin/yt-stash` directly.
+
+Running `yt-stash` by hand reads and writes your real settings file. When experimenting, point
+`HOME` (and `XDG_CONFIG_HOME` / `APPDATA`) at a temporary folder.
+
+## Checks to run
+
+CI runs the same checks on Linux, macOS and Windows with Python 3.10 and 3.13:
+
+```bash
+pytest                                     # fast, offline test suite
+pytest -m network                          # real YouTube download (needs internet; optional)
+pytest --cov --cov-report=term-missing     # coverage, as CI runs it
+ruff check . && ruff format --check .      # lint and format (line length 110)
+ruff format .                              # apply formatting
+```
+
+## Making a change
+
+`main` is protected. Nothing is pushed to it directly: every change goes through a short-lived branch and
+a pull request. If you are not a maintainer, **fork** the repository first and open the pull request from
+your fork.
+
+1. **Start from an up-to-date `main`.**
+
+   ```bash
+   git switch main && git pull --ff-only
+   ```
+
+2. **Create a branch** named `<type>/<short-kebab-description>`:
+
+   | Prefix      | Use for                                   |
+   |-------------|-------------------------------------------|
+   | `feature/`  | New behavior or options                   |
+   | `fix/`      | Bug fixes                                 |
+   | `docs/`     | Documentation only                        |
+   | `chore/`    | Tooling, CI, dependencies, refactoring    |
+
+   ```bash
+   git switch -c fix/playlist-numbering
+   ```
+
+3. **Commit in small steps.** Write a short, imperative subject line ("Fix playlist numbering"); add a
+   body that explains *why* when it isn't obvious.
+
+4. **Check locally** (see above), then push and open a pull request against `main`:
+
+   ```bash
+   git push -u origin HEAD
+   gh pr create --fill          # or use the GitHub website
+   ```
+
+5. **Wait for CI** and fix whatever it reports by pushing more commits to the same branch. Reviews
+   are discussions: ask questions, push back politely, and expect the same.
+
+6. **Merging.** A maintainer merges the pull request with a merge commit after CI passes. The branch is
+   deleted automatically.
+
+Keep one branch to one concern, and keep branches short-lived so they don't drift from `main`.
+
+### Pull request checklist
+
+- Tests added or updated. **No default test may touch the network**; mark real-network tests with
+  `@pytest.mark.network`.
+- Code stays compatible with **Python 3.10 and Windows** (no PEP 701 f-string nesting of the same
+  quote style; use `os.sep`/`pathlib`).
+- [README](README.md) and [docs/](docs/) updated for user-facing changes;
+  [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) updated when behavior or module responsibilities change.
+- A line in [CHANGELOG.md](CHANGELOG.md) under **Unreleased** (see below).
+- New user-visible text has keys in both `i18n/en.py` and `i18n/tr.py`. Don't know Turkish? Add the
+  English text to both and say so in the pull request; a maintainer will help.
+
+See [CLAUDE.md](CLAUDE.md) for the invariants that span several files, such as "only `gateway.py`
+calls the yt-dlp API", and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the design.
+
+## The changelog and versions
+
+yt-stash follows [Semantic Versioning](https://semver.org/) and keeps a
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) file. Add one bullet per user-visible change
+under `## [Unreleased]`, in the section that fits:
+
+| Section | Use for | Version bump |
+|---|---|---|
+| Added | new features, flags, languages | minor |
+| Changed | behavior changes of existing features | minor, or **major** if scripts can break |
+| Deprecated / Removed | features going away or gone | minor / **major** |
+| Fixed | bug fixes | patch |
+| Security | vulnerability fixes | patch |
+
+The public interface is the command names, flags, exit codes, environment variables and settings file.
+Maintainers cut releases as described in [docs/RELEASING.md](docs/RELEASING.md).
+
+## How decisions get made
+
+yt-stash currently has a single maintainer, who decides what is merged and tries to explain every
+decision in the open (in the issue or pull request). Regular contributors who show good judgment will be
+invited to become maintainers. Questions and decisions stay in public issues and discussions so that
+everyone can follow them.
+
+## What protects `main`
+
+These rules are enforced by GitHub, for administrators too:
+
+- Changes must arrive through a pull request; direct pushes are rejected.
+- All CI checks must pass: `lint` and `test` on Ubuntu, macOS and Windows with Python 3.10 and 3.13,
+  and the `package` build check.
+- The branch must be up to date with `main` before it merges. If `main` moved, merge it into your branch
+  (`git merge origin/main`), push, and let CI run again.
+- Review conversations must be resolved.
+- Force-pushes to `main` and deleting `main` are blocked.
+
+(Maintainers: if the job list in `.github/workflows/ci.yml` changes, update the required checks in the
+branch protection settings too, otherwise pull requests wait forever for a missing check.)
+
+## Reporting security problems
+
+Please don't use public issues for vulnerabilities; follow [SECURITY.md](SECURITY.md).
+
+## License
+
+By contributing you agree that your contribution is licensed under the project's [MIT License](LICENSE).

yt_stash-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 İlker Keklik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

yt_stash-1.0.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.5
+Name: yt-stash
+Version: 1.0.0
+Summary: Download YouTube videos and playlists from the terminal: pick any quality, run downloads in parallel, and save members-only videos.
+Project-URL: Homepage, https://github.com/ilkerkeklik01/yt-stash
+Project-URL: Documentation, https://github.com/ilkerkeklik01/yt-stash/tree/main/docs
+Project-URL: Changelog, https://github.com/ilkerkeklik01/yt-stash/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/ilkerkeklik01/yt-stash/issues
+Project-URL: Source, https://github.com/ilkerkeklik01/yt-stash
+Author-email: Ilker Keklik <ilkerkeklik50@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audio,cli,downloader,playlist,subtitles,video,youtube,yt-dlp
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: questionary>=2.1
+Requires-Dist: rich>=15.0.0
+Requires-Dist: yt-dlp[default]>=2026.8.19
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# yt-stash
+
+**Download YouTube videos and playlists from your terminal.**
+Any quality, parallel downloads, members-only videos, subtitles, and a friendly arrow-key menu.
+
+[![CI](https://github.com/ilkerkeklik01/yt-stash/actions/workflows/ci.yml/badge.svg)](https://github.com/ilkerkeklik01/yt-stash/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/yt-stash)](https://pypi.org/project/yt-stash/)
+[![Python](https://img.shields.io/pypi/pyversions/yt-stash)](https://pypi.org/project/yt-stash/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ilkerkeklik01/yt-stash/blob/main/LICENSE)
+
+</div>
+
+yt-stash is a cross-platform (Linux, macOS, Windows) command-line downloader for single videos, several
+videos and whole playlists, including **members-only and private videos**. It is a thin, heavily tested
+workflow layer on top of [yt-dlp](https://github.com/yt-dlp/yt-dlp), the best-maintained YouTube
+extraction library, so it keeps working when YouTube changes.
+
+## Features
+
+- **Every quality**: detects all resolutions (144p … 8K, high frame rate, HDR) and lets you choose once
+  for a whole batch. Defaults to **1080p**, or the highest available.
+- **Videos and playlists**: one or many links, a text file of links, or every video of a playlist.
+- **Parallel downloads**: several videos at once, plus parallel fragments per video.
+- **Members-only, private and age-restricted videos** through your browser's signed-in session, a
+  `cookies.txt` file, or cookies pasted for one run (never saved).
+- **Audio only** (m4a, mp3, opus) and **subtitles** (save or embed, any language, auto-generated too).
+- **Resume and skip**: interrupted downloads continue; files you already have are skipped; transient
+  errors and rate limits are retried automatically.
+- **Interactive or scriptable**: arrow-key menus with an explanation under every entry, or
+  `--yes` plus flags for cron and CI, with documented exit codes.
+- **English and Turkish** interface.
+
+## Quickstart
+
+```bash
+# 1. Install (details for every system: docs/installation.md)
+pipx install yt-stash
+
+# 2. Open the interactive menu
+yt-stash
+
+# 3. Or download straight away
+yt-stash video https://youtu.be/dQw4w9WgXcQ                      # asks for quality and folder
+yt-stash video URL -q 720 -o ~/Videos                            # no questions
+yt-stash video URL1 URL2 URL3 -j 3                               # three at once
+yt-stash playlist "https://www.youtube.com/playlist?list=PL..."  # a whole playlist
+yt-stash video URL -a mp3                                        # audio only
+yt-stash video URL --subs en,tr --embed-subs                     # with subtitles
+yt-stash video URL --cookies-from-browser firefox                # members-only video
+```
+
+```text
+$ yt-stash
+yt-stash 1.0.0  Download YouTube videos and playlists
+
+▶ What do you want to do? (↑↓ to move, Enter to choose)
+ ❯ Download videos
+   Download a playlist
+   Download links from a text file
+   Show available qualities
+
+   Sign-in (off)
+   Language (English)
+   Check setup
+   Command-line options
+   Quit
+  Description: Paste one or more video links.
+```
+
+## Installation
+
+yt-stash needs Python 3.10+; install **ffmpeg** and **deno** too for full quality.
+
+| System | Install |
+|---|---|
+| **macOS** | `brew install python pipx ffmpeg deno && pipx ensurepath`, then `pipx install yt-stash` |
+| **Windows** (PowerShell) | `winget install Python.Python.3.13`, `winget install Gyan.FFmpeg`, `winget install DenoLand.Deno`, reopen PowerShell, `py -m pip install --user pipx`, `py -m pipx ensurepath`, reopen, then `pipx install yt-stash` |
+| **Debian / Ubuntu** | `sudo apt install python3 pipx ffmpeg && pipx ensurepath`, install [deno](https://deno.com), then `pipx install yt-stash` |
+| **Fedora / Arch / openSUSE / uv / pip / source** | see the [installation guide](https://github.com/ilkerkeklik01/yt-stash/blob/main/docs/installation.md) |
+
+Check it: `yt-stash --version`. **If downloads suddenly fail, update first:** `pipx upgrade yt-stash`.
+
+## Documentation
+
+| Guide | What is in it |
+|---|---|
+| [Installation](https://github.com/ilkerkeklik01/yt-stash/blob/main/docs/installation.md) | Step by step for macOS, Windows and Linux; updating and uninstalling |
+| [Using yt-stash](https://github.com/ilkerkeklik01/yt-stash/blob/main/docs/usage.md) | Every feature: menus, videos, playlists, quality, audio, subtitles, resume, language, scripting, all options, recipes |
+| [Members-only videos](https://github.com/ilkerkeklik01/yt-stash/blob/main/docs/authentication.md) | Sign-in with browser cookies, a cookies file or pasted cookies |
+| [Troubleshooting](https://github.com/ilkerkeklik01/yt-stash/blob/main/docs/troubleshooting.md) | Common problems and fixes |
+| [Translating](https://github.com/ilkerkeklik01/yt-stash/blob/main/docs/translating.md) | Add or improve a language |
+| [Architecture](https://github.com/ilkerkeklik01/yt-stash/blob/main/docs/ARCHITECTURE.md) | How the code is organised and why |
+| [Changelog](https://github.com/ilkerkeklik01/yt-stash/blob/main/CHANGELOG.md) | What changed in each release |
+
+Quick reference: `yt-stash --help`, `yt-stash video --help`, `yt-stash playlist --help`.
+
+**Exit codes:** `0` everything downloaded or already present · `1` at least one video failed ·
+`2` invalid usage · `130` interrupted with Ctrl+C.
+
+## Getting help
+
+- **Question or idea?** Open a [Discussion](https://github.com/ilkerkeklik01/yt-stash/discussions).
+- **Found a bug?** Open an [issue](https://github.com/ilkerkeklik01/yt-stash/issues/new/choose); the form
+  asks for the details that make it fixable.
+- **Security problem?** Please don't open an issue; follow the
+  [security policy](https://github.com/ilkerkeklik01/yt-stash/blob/main/SECURITY.md).
+
+yt-stash is maintained by one volunteer in their spare time. Replies may take a few days; thank you
+for your patience.
+
+## Contributing
+
+Contributions of every size are welcome: bug reports, documentation fixes, translations and code. Read
+[CONTRIBUTING.md](https://github.com/ilkerkeklik01/yt-stash/blob/main/CONTRIBUTING.md) first; issues
+labelled [`good first issue`](https://github.com/ilkerkeklik01/yt-stash/labels/good%20first%20issue) are
+a good place to start. By taking part you agree to the
+[Code of Conduct](https://github.com/ilkerkeklik01/yt-stash/blob/main/CODE_OF_CONDUCT.md).
+
+```bash
+git clone https://github.com/ilkerkeklik01/yt-stash.git && cd yt-stash
+python -m venv .venv && source .venv/bin/activate     # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+pytest && ruff check . && ruff format --check .
+```
+
+## Legal
+
+yt-stash is released under the [MIT License](https://github.com/ilkerkeklik01/yt-stash/blob/main/LICENSE).
+It is an independent project, not affiliated with or endorsed by YouTube or Google. Only download
+content you have the right to download, and respect YouTube's Terms of Service and the creators'
+rights. You are responsible for how you use this tool.
+
+yt-stash builds on [yt-dlp](https://github.com/yt-dlp/yt-dlp) (Unlicense), [rich](https://github.com/Textualize/rich)
+(MIT), [questionary](https://github.com/tmbo/questionary) (MIT) and
+[prompt_toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit) (BSD-3-Clause). Thank you to their authors.

yt_stash-1.0.0/README.md

@@ -0,0 +1,137 @@
+<div align="center">
+
+# yt-stash
+
+**Download YouTube videos and playlists from your terminal.**
+Any quality, parallel downloads, members-only videos, subtitles, and a friendly arrow-key menu.
+
+[![CI](https://github.com/ilkerkeklik01/yt-stash/actions/workflows/ci.yml/badge.svg)](https://github.com/ilkerkeklik01/yt-stash/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/yt-stash)](https://pypi.org/project/yt-stash/)
+[![Python](https://img.shields.io/pypi/pyversions/yt-stash)](https://pypi.org/project/yt-stash/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ilkerkeklik01/yt-stash/blob/main/LICENSE)
+
+</div>
+
+yt-stash is a cross-platform (Linux, macOS, Windows) command-line downloader for single videos, several
+videos and whole playlists, including **members-only and private videos**. It is a thin, heavily tested
+workflow layer on top of [yt-dlp](https://github.com/yt-dlp/yt-dlp), the best-maintained YouTube
+extraction library, so it keeps working when YouTube changes.
+
+## Features
+
+- **Every quality**: detects all resolutions (144p … 8K, high frame rate, HDR) and lets you choose once
+  for a whole batch. Defaults to **1080p**, or the highest available.
+- **Videos and playlists**: one or many links, a text file of links, or every video of a playlist.
+- **Parallel downloads**: several videos at once, plus parallel fragments per video.
+- **Members-only, private and age-restricted videos** through your browser's signed-in session, a
+  `cookies.txt` file, or cookies pasted for one run (never saved).
+- **Audio only** (m4a, mp3, opus) and **subtitles** (save or embed, any language, auto-generated too).
+- **Resume and skip**: interrupted downloads continue; files you already have are skipped; transient
+  errors and rate limits are retried automatically.
+- **Interactive or scriptable**: arrow-key menus with an explanation under every entry, or
+  `--yes` plus flags for cron and CI, with documented exit codes.
+- **English and Turkish** interface.
+
+## Quickstart
+
+```bash
+# 1. Install (details for every system: docs/installation.md)
+pipx install yt-stash
+
+# 2. Open the interactive menu
+yt-stash
+
+# 3. Or download straight away
+yt-stash video https://youtu.be/dQw4w9WgXcQ                      # asks for quality and folder
+yt-stash video URL -q 720 -o ~/Videos                            # no questions
+yt-stash video URL1 URL2 URL3 -j 3                               # three at once
+yt-stash playlist "https://www.youtube.com/playlist?list=PL..."  # a whole playlist
+yt-stash video URL -a mp3                                        # audio only
+yt-stash video URL --subs en,tr --embed-subs                     # with subtitles
+yt-stash video URL --cookies-from-browser firefox                # members-only video
+```
+
+```text
+$ yt-stash
+yt-stash 1.0.0  Download YouTube videos and playlists
+
+▶ What do you want to do? (↑↓ to move, Enter to choose)
+ ❯ Download videos
+   Download a playlist
+   Download links from a text file
+   Show available qualities
+
+   Sign-in (off)
+   Language (English)
+   Check setup
+   Command-line options
+   Quit
+  Description: Paste one or more video links.
+```
+
+## Installation
+
+yt-stash needs Python 3.10+; install **ffmpeg** and **deno** too for full quality.
+
+| System | Install |
+|---|---|
+| **macOS** | `brew install python pipx ffmpeg deno && pipx ensurepath`, then `pipx install yt-stash` |
+| **Windows** (PowerShell) | `winget install Python.Python.3.13`, `winget install Gyan.FFmpeg`, `winget install DenoLand.Deno`, reopen PowerShell, `py -m pip install --user pipx`, `py -m pipx ensurepath`, reopen, then `pipx install yt-stash` |
+| **Debian / Ubuntu** | `sudo apt install python3 pipx ffmpeg && pipx ensurepath`, install [deno](https://deno.com), then `pipx install yt-stash` |
+| **Fedora / Arch / openSUSE / uv / pip / source** | see the [installation guide](https://github.com/ilkerkeklik01/yt-stash/blob/main/docs/installation.md) |
+
+Check it: `yt-stash --version`. **If downloads suddenly fail, update first:** `pipx upgrade yt-stash`.
+
+## Documentation
+
+| Guide | What is in it |
+|---|---|
+| [Installation](https://github.com/ilkerkeklik01/yt-stash/blob/main/docs/installation.md) | Step by step for macOS, Windows and Linux; updating and uninstalling |
+| [Using yt-stash](https://github.com/ilkerkeklik01/yt-stash/blob/main/docs/usage.md) | Every feature: menus, videos, playlists, quality, audio, subtitles, resume, language, scripting, all options, recipes |
+| [Members-only videos](https://github.com/ilkerkeklik01/yt-stash/blob/main/docs/authentication.md) | Sign-in with browser cookies, a cookies file or pasted cookies |
+| [Troubleshooting](https://github.com/ilkerkeklik01/yt-stash/blob/main/docs/troubleshooting.md) | Common problems and fixes |
+| [Translating](https://github.com/ilkerkeklik01/yt-stash/blob/main/docs/translating.md) | Add or improve a language |
+| [Architecture](https://github.com/ilkerkeklik01/yt-stash/blob/main/docs/ARCHITECTURE.md) | How the code is organised and why |
+| [Changelog](https://github.com/ilkerkeklik01/yt-stash/blob/main/CHANGELOG.md) | What changed in each release |
+
+Quick reference: `yt-stash --help`, `yt-stash video --help`, `yt-stash playlist --help`.
+
+**Exit codes:** `0` everything downloaded or already present · `1` at least one video failed ·
+`2` invalid usage · `130` interrupted with Ctrl+C.
+
+## Getting help
+
+- **Question or idea?** Open a [Discussion](https://github.com/ilkerkeklik01/yt-stash/discussions).
+- **Found a bug?** Open an [issue](https://github.com/ilkerkeklik01/yt-stash/issues/new/choose); the form
+  asks for the details that make it fixable.
+- **Security problem?** Please don't open an issue; follow the
+  [security policy](https://github.com/ilkerkeklik01/yt-stash/blob/main/SECURITY.md).
+
+yt-stash is maintained by one volunteer in their spare time. Replies may take a few days; thank you
+for your patience.
+
+## Contributing
+
+Contributions of every size are welcome: bug reports, documentation fixes, translations and code. Read
+[CONTRIBUTING.md](https://github.com/ilkerkeklik01/yt-stash/blob/main/CONTRIBUTING.md) first; issues
+labelled [`good first issue`](https://github.com/ilkerkeklik01/yt-stash/labels/good%20first%20issue) are
+a good place to start. By taking part you agree to the
+[Code of Conduct](https://github.com/ilkerkeklik01/yt-stash/blob/main/CODE_OF_CONDUCT.md).
+
+```bash
+git clone https://github.com/ilkerkeklik01/yt-stash.git && cd yt-stash
+python -m venv .venv && source .venv/bin/activate     # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+pytest && ruff check . && ruff format --check .
+```
+
+## Legal
+
+yt-stash is released under the [MIT License](https://github.com/ilkerkeklik01/yt-stash/blob/main/LICENSE).
+It is an independent project, not affiliated with or endorsed by YouTube or Google. Only download
+content you have the right to download, and respect YouTube's Terms of Service and the creators'
+rights. You are responsible for how you use this tool.
+
+yt-stash builds on [yt-dlp](https://github.com/yt-dlp/yt-dlp) (Unlicense), [rich](https://github.com/Textualize/rich)
+(MIT), [questionary](https://github.com/tmbo/questionary) (MIT) and
+[prompt_toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit) (BSD-3-Clause). Thank you to their authors.