| 1 | <!-- Parent: ../AGENTS.md --> |
| 2 | <!-- Generated: 2026-03-27 | Updated: 2026-03-27 --> |
| 3 | |
| 4 | # cli |
| 5 | |
| 6 | ## Purpose |
| 7 | Command-line interface — argument parsing, main async download loop, progress display with Rich, and optional Whisper transcription integration. |
| 8 | |
| 9 | ## Key Files |
| 10 | |
| 11 | | File | Description | |
| 12 | |------|-------------| |
| 13 | | `__init__.py` | Package marker | |
| 14 | | `main.py` | CLI entry point: `main()` → `main_async()` → per-URL `download_url()` orchestration | |
| 15 | | `progress_display.py` | Rich-based terminal UI — banners, progress bars, step tracking, result summaries | |
| 16 | | `whisper_transcribe.py` | Optional audio transcription via OpenAI Whisper | |
| 17 | |
| 18 | ## For AI Agents |
| 19 | |
| 20 | ### Working In This Directory |
| 21 | - `main.py` is the orchestration hub — it wires together config, auth, storage, control, and core |
| 22 | - `download_url()` is the per-URL pipeline: resolve short URL → parse → factory → download → record history |
| 23 | - Progress display quiets console logs during download to avoid Rich redraws; restores after |
| 24 | - The `douyin-dl` CLI entry point (from pyproject.toml) maps to `cli.main:main` |
| 25 | |
| 26 | ### Testing Requirements |
| 27 | - Tests: `tests/test_progress_display.py` |
| 28 | - `main.py` is tested indirectly through integration; mock `asyncio.run` for unit tests |
| 29 | |
| 30 | ### Common Patterns |
| 31 | - `argparse` for CLI args with `-u`, `-c`, `-p`, `-t` flags |
| 32 | - Chinese-language step labels in progress display (初始化, 解析链接, etc.) |
| 33 | - `DownloadResult` aggregation for multi-URL summary |
| 34 | |
| 35 | ## Dependencies |
| 36 | |
| 37 | ### Internal |
| 38 | - `config/` — `ConfigLoader` for YAML config |
| 39 | - `auth/` — `CookieManager` for authentication |
| 40 | - `storage/` — `Database`, `FileManager` |
| 41 | - `control/` — `QueueManager`, `RateLimiter`, `RetryHandler` |
| 42 | - `core/` — `DouyinAPIClient`, `URLParser`, `DownloaderFactory` |
| 43 | - `utils/logger` — `setup_logger`, `set_console_log_level` |
| 44 | |
| 45 | ### External |
| 46 | - `rich` — terminal UI rendering |
| 47 | - `openai-whisper` — optional transcription (behind `[transcribe]` extra) |
| 48 | |
| 49 | <!-- MANUAL: --> |
| 50 |