CLI Tools & Automation¶
Referenced Files in This Document
Table of Contents¶
Introduction¶
This document describes the command-line interface tools and automation scripts for Nexo. It covers:
-
Main CLI entry points for scanning, organizing, and managing media decisions
-
Batch processing commands for bulk operations
-
System administration utilities for setup, database migrations, and maintenance
-
Testing tools and diagnostic helpers
-
Notification CLI for sending alerts and status updates
-
Automation scenarios such as scheduled tasks, batch operations, data migration, and system maintenance
-
Debugging commands, diagnostics, and performance monitoring tips
The goal is to enable operators and developers to run, automate, and maintain Nexo reliably from the command line.
Project Structure¶
At a high level, CLI and automation capabilities are provided by:
-
Top-level Python scripts that serve as quick-start or specialized tools
-
Application modules under apps/ with their own entry points (service, notify, setup, tray, main)
-
Core logic under src/ used by CLIs and services
-
Database migrations under alembic/
-
Build and release tooling at the repository root
graph TB
subgraph "CLI Entry Points"
IDX["index.py"]
DL_SIMPLE["video_downloader_simple.py"]
DL_PLAYWRIGHT["video_downloader_playwright.py"]
DL_STEALTH["video_downloader_stealth.py"]
DL_UC["video_downloader_uc.py"]
DL_CS["video_downloader_cs.py"]
DL_COOKIES["video_downloader_cookies.py"]
DL_MANUAL["video_downloader_manual.py"]
CLEAR_JF["clear_jellyfin.py"]
START_CHROME["start_chrome.py"]
end
subgraph "Apps"
APP_MAIN["apps/main/__main__.py<br/>apps/main/main.py"]
APP_NOTIFY["apps/notify/main.py"]
APP_SERVICE["apps/service/main.py"]
APP_SETUP["apps/setup/main.py"]
APP_TRAY["apps/tray/main.py"]
end
subgraph "Core Libraries"
SRC_CONFIG["src/config.py"]
SRC_NOTIFIER["src/notifier.py"]
SRC_PIPELINE["src/core/pipeline.py"]
SRC_SCAN["src/core/scan.py"]
DB_DECISIONS["src/database/decisions_db.py"]
DB_HISTORY["src/database/history_db.py"]
DB_LOGS["src/database/logs_db.py"]
DB_USERS["src/database/users_db.py"]
end
subgraph "Migrations"
ALEMBIC_ENV["alembic/env.py"]
V001["alembic/versions/001_initial_schema.py"]
V002["alembic/versions/002_add_decision_type.py"]
end
subgraph "Build & Release"
BUILD["build.py"]
RELEASE["release.py"]
end
IDX --> SRC_PIPELINE
IDX --> SRC_SCAN
IDX --> DB_DECISIONS
IDX --> DB_HISTORY
IDX --> DB_LOGS
IDX --> SRC_CONFIG
APP_MAIN --> SRC_PIPELINE
APP_MAIN --> SRC_CONFIG
APP_NOTIFY --> SRC_NOTIFIER
APP_NOTIFY --> SRC_CONFIG
APP_SERVICE --> SRC_CONFIG
APP_SETUP --> ALEMBIC_ENV
APP_SETUP --> V001
APP_SETUP --> V002
DL_PLAYWRIGHT --> SRC_CONFIG
DL_STEALTH --> SRC_CONFIG
DL_UC --> SRC_CONFIG
DL_CS --> SRC_CONFIG
DL_COOKIES --> SRC_CONFIG
DL_MANUAL --> SRC_CONFIG
DL_SIMPLE --> SRC_CONFIG
CLEAR_JF --> SRC_CONFIG
START_CHROME --> SRC_CONFIG
Diagram sources
Section sources
Core Components¶
This section summarizes the primary CLI entry points and what they do. For exact flags and options, inspect each script’s help output or source.
-
index.py
-
Purpose: Primary orchestrator for scanning and organizing media content, applying decisions, and updating history/logs.
-
Typical usage: Run a scan over configured directories, process pipeline stages, persist results.
-
Key dependencies: core pipeline, scanner, decision and history databases, configuration.
-
apps/main/main.py and apps/main/main.py
-
Purpose: Application entry point for the main CLI module; may expose subcommands for common workflows.
-
Typical usage: Invoke via python -m apps.main or through an installed console script if configured.
-
apps/notify/main.py
-
Purpose: CLI for sending notifications/alerts using the shared notifier.
-
Typical usage: Send status updates, alert on errors, or broadcast operational messages.
-
apps/service/main.py
-
Purpose: Starts the long-running service (e.g., API server). Not a traditional CLI but often invoked from automation.
-
Typical usage: Start the HTTP API for dashboard and integrations.
-
apps/setup/main.py
-
Purpose: Setup wizard or initialization routines (e.g., create default config, initialize database).
-
Typical usage: One-time bootstrap or re-initialization.
-
apps/tray/main.py
-
Purpose: Tray application entry point; useful for desktop automation and background tasks.
-
video_downloader_*.py family
-
Purpose: Specialized downloaders with different strategies (simple, Playwright-based, stealth, UC, cookies, manual).
-
Typical usage: Download videos from specific sites or modes; integrate into batch pipelines.
-
clear_jellyfin.py
-
Purpose: Maintenance utility to clear Jellyfin-related state or cache.
-
start_chrome.py
-
Purpose: Utility to launch Chrome for browser-based automation (e.g., headless scraping).
-
build.py and release.py
-
Purpose: Build and packaging helpers for creating distributions or artifacts.
-
Alembic migrations (alembic/env.py and versions/*)
-
Purpose: Database schema management; used by setup and admin tasks.
Section sources
Architecture Overview¶
The CLI layer composes core libraries to perform scanning, decision-making, persistence, and notifications. The following diagram shows how top-level scripts and app entry points depend on shared components.
graph TB
CLI_IDX["CLI: index.py"]
CLI_DL["CLI: video_downloader_*.py"]
CLI_NOTIFY["CLI: apps/notify/main.py"]
CLI_MAIN["CLI: apps/main/__main__.py"]
CLI_SETUP["CLI: apps/setup/main.py"]
CLI_SERVICE["Service: apps/service/main.py"]
CFG["Config: src/config.py"]
PIPE["Pipeline: src/core/pipeline.py"]
SCAN["Scanner: src/core/scan.py"]
NOTIF["Notifier: src/notifier.py"]
DB_DEC["DB: src/database/decisions_db.py"]
DB_HIS["DB: src/database/history_db.py"]
DB_LOG["DB: src/database/logs_db.py"]
DB_USR["DB: src/database/users_db.py"]
ALEMBIC["Alembic: alembic/env.py + versions/*"]
CLI_IDX --> CFG
CLI_IDX --> PIPE
CLI_IDX --> SCAN
CLI_IDX --> DB_DEC
CLI_IDX --> DB_HIS
CLI_IDX --> DB_LOG
CLI_DL --> CFG
CLI_NOTIFY --> NOTIF
CLI_NOTIFY --> CFG
CLI_MAIN --> CFG
CLI_MAIN --> PIPE
CLI_SETUP --> ALEMBIC
CLI_SERVICE --> CFG
Diagram sources
Detailed Component Analysis¶
Main Orchestrator CLI (index.py)¶
-
Responsibilities:
-
Parse CLI arguments for scan targets, filters, and output options
-
Initialize configuration and logging
-
Execute scanning and pipeline stages
-
Persist decisions, history, and logs
-
Typical workflow:
-
Validate inputs and paths
-
Discover media files
-
Apply matching/decision rules
-
Update database records
-
Emit summary or structured output
sequenceDiagram
participant User as "Operator"
participant CLI as "index.py"
participant Cfg as "src/config.py"
participant Scan as "src/core/scan.py"
participant Pipe as "src/core/pipeline.py"
participant DecDB as "src/database/decisions_db.py"
participant HistDB as "src/database/history_db.py"
participant LogDB as "src/database/logs_db.py"
User->>CLI : "python index.py --scan <path> [--flags]"
CLI->>Cfg : "load configuration"
CLI->>Scan : "discover files"
Scan-->>CLI : "file list"
CLI->>Pipe : "process pipeline stages"
Pipe-->>CLI : "results"
CLI->>DecDB : "persist decisions"
CLI->>HistDB : "record history"
CLI->>LogDB : "write logs"
CLI-->>User : "summary / structured output"
Diagram sources
Section sources
Notification CLI (apps/notify/main.py)¶
-
Responsibilities:
-
Accept message content and target channels
-
Use shared notifier to send alerts/status updates
-
Return exit codes and optional JSON summaries
-
Typical usage:
-
Send success/failure notifications after batch jobs
-
Integrate with CI/CD or cron jobs for real-time alerts
flowchart TD
Start(["Notify CLI Entry"]) --> LoadCfg["Load Configuration"]
LoadCfg --> BuildMsg["Build Message Payload"]
BuildMsg --> Send["Send via Notifier"]
Send --> Result{"Success?"}
Result --> |Yes| ExitOk["Exit 0 with Summary"]
Result --> |No| ExitErr["Exit Non-zero with Error"]
Diagram sources
Section sources
Setup CLI (apps/setup/main.py)¶
-
Responsibilities:
-
Initialize environment, create default configurations
-
Run database migrations via Alembic
-
Prepare initial data or users
-
Typical usage:
-
First-run bootstrap
-
Re-initialize after destructive operations
sequenceDiagram
participant User as "Operator"
participant Setup as "apps/setup/main.py"
participant Env as "alembic/env.py"
participant V001 as "alembic/versions/001_initial_schema.py"
participant V002 as "alembic/versions/002_add_decision_type.py"
User->>Setup : "Run setup"
Setup->>Env : "configure migration environment"
Setup->>V001 : "apply initial schema"
Setup->>V002 : "apply decision type extension"
Setup-->>User : "setup complete"
Diagram sources
Section sources
Service CLI (apps/service/main.py)¶
-
Responsibilities:
-
Start the long-running service (API server)
-
Load configuration and initialize subsystems
-
Typical usage:
-
Run as a daemon or managed process
-
Expose endpoints for dashboard and external integrations
sequenceDiagram
participant User as "Operator"
participant Service as "apps/service/main.py"
participant Cfg as "src/config.py"
User->>Service : "Start service"
Service->>Cfg : "load configuration"
Service-->>User : "service listening"
Diagram sources
Section sources
Video Downloader CLIs (video_downloader_*.py)¶
-
Variants:
-
Simple downloader for basic cases
-
Playwright-based for dynamic pages
-
Stealth mode to avoid detection
-
UC mode for specific site behavior
-
Cookies mode for authenticated sessions
-
Manual mode for guided downloads
-
Common responsibilities:
-
Load configuration (proxies, headers, timeouts)
-
Launch browser or HTTP client
-
Download assets and save to disk
-
Report progress and errors
classDiagram
class Config {
+load()
+get(key)
}
class DownloaderBase {
+download(url, dest)
+handle_errors()
}
class SimpleDownloader
class PlaywrightDownloader
class StealthDownloader
class UCDownloader
class CookiesDownloader
class ManualDownloader
Config <.. SimpleDownloader : "uses"
Config <.. PlaywrightDownloader : "uses"
Config <.. StealthDownloader : "uses"
Config <.. UCDownloader : "uses"
Config <.. CookiesDownloader : "uses"
Config <.. ManualDownloader : "uses"
DownloaderBase <|-- SimpleDownloader
DownloaderBase <|-- PlaywrightDownloader
DownloaderBase <|-- StealthDownloader
DownloaderBase <|-- UCDownloader
DownloaderBase <|-- CookiesDownloader
DownloaderBase <|-- ManualDownloader
Diagram sources
Section sources
Maintenance Utilities¶
-
clear_jellyfin.py
-
Purpose: Clear Jellyfin-related state/cache to recover from inconsistencies.
-
Typical usage: Run after library resets or when sync issues occur.
-
start_chrome.py
-
Purpose: Launch Chrome for browser automation tasks.
-
Typical usage: Pre-launch before running Playwright-based downloaders.
Section sources
Build and Release Tooling¶
-
build.py
-
Purpose: Create build artifacts or package distributions.
-
release.py
-
Purpose: Orchestrate release steps (versioning, tagging, publishing).
Section sources
Dependency Analysis¶
The CLI layer depends on shared configuration, core processing, and persistence. Migrations are executed during setup.
graph LR
CFG["src/config.py"]
PIPE["src/core/pipeline.py"]
SCAN["src/core/scan.py"]
NOTIF["src/notifier.py"]
DEC["src/database/decisions_db.py"]
HIS["src/database/history_db.py"]
LOG["src/database/logs_db.py"]
USR["src/database/users_db.py"]
AENV["alembic/env.py"]
AV001["alembic/versions/001_initial_schema.py"]
AV002["alembic/versions/002_add_decision_type.py"]
CLI_IDX["index.py"] --> CFG
CLI_IDX --> PIPE
CLI_IDX --> SCAN
CLI_IDX --> DEC
CLI_IDX --> HIS
CLI_IDX --> LOG
CLI_NOTIFY["apps/notify/main.py"] --> NOTIF
CLI_NOTIFY --> CFG
CLI_SETUP["apps/setup/main.py"] --> AENV
CLI_SETUP --> AV001
CLI_SETUP --> AV002
CLI_DL["video_downloader_*.py"] --> CFG
Diagram sources
Section sources
Performance Considerations¶
-
Prefer incremental scans to reduce I/O overhead; limit scope with targeted paths and filters.
-
Use appropriate concurrency settings in the pipeline and downloader variants based on system resources.
-
Cache frequently accessed configuration and avoid repeated network calls where possible.
-
Monitor database write throughput; consider batching writes for large runs.
-
For browser-based downloaders, manage headless processes carefully to avoid resource exhaustion.
[No sources needed since this section provides general guidance]
Troubleshooting Guide¶
-
Verify configuration loading and paths before running scans.
-
Check notification delivery by sending a test message via the notify CLI.
-
Inspect database state using dedicated tests and helper scripts.
-
Use the service logs and log database entries to trace failures.
-
For browser automation issues, ensure Chrome is available and compatible with the selected downloader variant.
Common debugging and testing tools:
-
test_decision_storage.py
-
test_decisions_svc.py
-
test_matcher.py
-
tests.py
Section sources
Conclusion¶
Nexo provides a robust set of CLI tools and automation scripts for scanning, organizing, notifying, and maintaining media systems. By combining the main orchestrator, specialized downloaders, notification utilities, and setup/maintenance tools, operators can implement reliable automated workflows, schedule recurring tasks, and integrate with external systems effectively.
[No sources needed since this section summarizes without analyzing specific files]
Appendices¶
Command Syntax and Flags Reference¶
-
To discover available commands and flags:
-
Run each script with its built-in help option (for example, append a help flag supported by the script).
-
Review the entry points under apps/*/main.py for subcommand structures.
-
Output formats:
-
Many scripts emit structured summaries suitable for parsing; consult individual scripts for details.
[No sources needed since this section provides general guidance]
Automation Scenarios and Examples¶
-
Scheduled scans:
-
Schedule index.py to run periodically via cron or Task Scheduler.
-
Combine with apps/notify/main.py to send success/failure alerts.
-
Batch downloads:
-
Use video_downloader_*.py variants in loops or job queues.
-
Pre-launch Chrome with start_chrome.py when required.
-
Data migration:
-
Run apps/setup/main.py to apply Alembic migrations and initialize the database.
-
System maintenance:
-
Use clear_jellyfin.py to reset Jellyfin-related state when necessary.
-
Integration with external systems:
-
Call apps/service/main.py to expose APIs for dashboards and third-party tools.
-
Use notification CLI to push status updates to chat or email channels.
[No sources needed since this section provides general guidance]