movie-cli-v6

README

🎬 Movie CLI

Personal movie & TV show library manager — from the terminal

Scan folders, clean filenames, fetch TMDb metadata, organize files, and track your collection.

---

Quick Start

Install latest release

Picks up whatever is currently tagged latest on GitHub — and if no release has been published yet, automatically falls back to a source-build from main so you still end up with a working binary.

Windows (PowerShell)

irm https://raw.githubusercontent.com/alimtvnetwork/movie-cli-v6/main/get.ps1 | iex

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/alimtvnetwork/movie-cli-v6/main/get.sh | bash

get.ps1 / get.sh first probe releases/latest/download/install.{ps1,sh}. If that returns 200 it installs the pre-built binary. If it 404s (no release published yet) it transparently falls back to cloning + building from source via install.{ps1,sh} on main. Either way you get a clear message telling you which path was taken and what to do next.

Install a specific version (pinned)

Installs exactly the version in the URL — never auto-upgrades. Use this for CI pipelines, Dockerfiles, reproducible setups, or when you need to roll back. Replace v2.130.0 with the release tag you want.

Windows (PowerShell)

irm https://github.com/alimtvnetwork/movie-cli-v6/releases/download/v2.130.0/install.ps1 | iex

Linux / macOS

curl -fsSL https://github.com/alimtvnetwork/movie-cli-v6/releases/download/v2.130.0/install.sh | bash

Which one should I use? Use latest for personal machines so you stay current. Use pinned anywhere reproducibility matters — the pinned script is hard-locked to the version in the URL and will install that exact tag forever, even after newer releases ship. (contract spec)

Set up & scan

movie config set tmdb_api_key YOUR_KEY
movie scan ~/Downloads
movie ls

Search & discover

movie search "Inception"
movie suggest 5

Every command supports --help or -h for detailed usage.

---

🎥 Demo

📂 Scanning a Folder

$ movie scan ~/Downloads

🔍 Scanning: /home/user/Downloads
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Found 12 video files

  [1/12] Scream.2022.1080p.WEBRip.x264-RARBG.mkv
         → Title: Scream (2022)
         → TMDb: ★ 6.8 | Horror, Mystery, Thriller
         → Poster saved: thumbnails/scream-2022/scream-2022.jpg
         ✅ Saved to database

  [2/12] The.Batman.2022.2160p.BluRay.x265.mkv
         → Title: The Batman (2022)
         → TMDb: ★ 7.7 | Crime, Mystery, Thriller
         → Poster saved: thumbnails/the-batman-2022/the-batman-2022.jpg
         ✅ Saved to database

  ...

  ✅ Done — 12 items scanned, 11 new, 1 updated

↑ Replace with actual recording

---

📋 Browsing Your Library

$ movie ls

🎬 Library — Page 1 of 3 (20 per page)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  #   Title                          Year   Type    Rating
  ─── ────────────────────────────── ────── ─────── ──────
  1   Scream                         2022   🎬      ★ 6.8
  2   The Batman                     2022   🎬      ★ 7.7
  3   Everything Everywhere All...   2022   🎬      ★ 7.8
  4   Breaking Bad                   2008   📺      ★ 8.9
  5   Severance                      2022   📺      ★ 8.4
  ...

  [N]ext  [P]rev  [1-9] Detail  [Q]uit

↑ Replace with actual recording

---

🎯 Getting Suggestions

$ movie suggest 5

🎯 Movie Suggest
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Select category:
  1. 🎬 Movie
  2. 📺 TV
  3. 🎲 Random

  Choose: 1

  📽️  Recommendations based on your library:

  #   Title                          Year   Rating   Genre
  ─── ────────────────────────────── ────── ──────── ────────────────
  1   Nope                           2022   ★ 6.8    Horror, Sci-Fi
  2   X                              2022   ★ 6.6    Horror, Mystery
  3   Pearl                          2022   ★ 7.0    Drama, Horror
  4   Bodies Bodies Bodies            2022   ★ 6.5    Comedy, Horror
  5   Barbarian                      2022   ★ 7.0    Horror, Thriller

  🔥 Trending This Week:
  1   Oppenheimer                    2023   ★ 8.1    Drama, History
  2   Killers of the Flower Moon     2023   ★ 7.5    Crime, Drama
  3   Poor Things                    2023   ★ 7.9    Comedy, Drama

↑ Replace with actual recording

📹 Recording your own demos: Use VHS or asciinema to record terminal sessions as GIFs.

# VHS (recommended — deterministic, scriptable)
vhs docs/screenshots/scan.tape

# asciinema + agg (manual recording)
asciinema rec demo.cast
agg demo.cast docs/screenshots/demo-scan.gif

---

Installation

One-Liner Install (recommended)

Two flavours — pick based on whether you want auto-updates or a frozen version.

Latest release (auto-tracks newest)

Windows (PowerShell)

irm https://raw.githubusercontent.com/alimtvnetwork/movie-cli-v6/main/get.ps1 | iex

Linux / macOS (Bash)

curl -fsSL https://raw.githubusercontent.com/alimtvnetwork/movie-cli-v6/main/get.sh | bash

get.{ps1,sh} first checks releases/latest/download/install.{ps1,sh}. If a release is published it installs the pre-built binary; otherwise it falls back to a source-build from main, prints exactly which path it took, and tells the maintainer how to publish a release so future installs skip the build step.

Pinned to a specific release

Windows (PowerShell)

irm https://github.com/alimtvnetwork/movie-cli-v6/releases/download/v2.130.0/install.ps1 | iex

Linux / macOS (Bash)

curl -fsSL https://github.com/alimtvnetwork/movie-cli-v6/releases/download/v2.130.0/install.sh | bash

The script attached to each release has the version baked in (PINNED_VERSION="v2.130.0") and will install exactly that tag — it never falls back to "latest" and never delegates to the bootstrap scripts. Replace v2.130.0 with any published release.

When to use which

• Latest — personal machines, demos, "just give me the newest one"
• Pinned — CI pipelines, Dockerfiles, onboarding docs, reproducing a bug on a specific version, controlled rollbacks

Both URLs point at installer assets attached to the GitHub Release. The repo-root install.ps1 and install.sh are unrelated source bootstrap scripts for building locally.

Installer Options

Windows (PowerShell):

Flag	Description	Example
-InstallDir	Custom install directory	-InstallDir C:\tools\movie
-Arch	Force architecture (amd64, arm64)	-Arch arm64
-NoPath	Skip adding to user PATH	-NoPath

Linux / macOS (Bash):

Flag	Description	Example
--dir	Custom install directory	--dir ~/bin
--arch	Force architecture (amd64, arm64)	--arch arm64
--no-path	Skip adding to PATH	--no-path

Clone & Build (Development)

Prerequisites:

Requirement	Minimum	Check
Go	1.22+	go version
Git	2.x	git --version
PowerShell	5.1+ (Win) / 7+ (Unix)	$PSVersionTable.PSVersion

git clone https://github.com/alimtvnetwork/movie-cli-v6.git
cd movie-cli-v6
pwsh run.ps1

Using the bootstrap installer:

pwsh install.ps1                      # Fresh install (clone + build + deploy)
pwsh install.ps1 -DeployPath ~/bin    # Custom deploy path

Verify

movie version
# v1.0.0 (commit: abc1234, built: 2026-04-09)
#   Go:   go1.22.0
#   OS:   linux/amd64

Tip: If movie is not found, add the deploy path to your PATH. Default: E:\bin-run (Windows) or /usr/local/bin (Unix) for source builds.

---

What It Does

A portable CLI that manages your personal movie and TV show library entirely from the terminal. Every scan produces:

• Database — structured metadata in SQLite (WAL mode)
• Thumbnails — poster images downloaded from TMDb
• JSON — per-file metadata written to ./data/json/
• Clean filenames — Scream.2022.1080p.WEBRip.x264.mkv → Scream (2022).mkv

All data lives in ./data/ at the project root.

---

Command Reference

Scanning & Library

Command	Description
movie scan [folder]	Scan folder → DB + TMDb metadata
movie rescan	Re-fetch TMDb metadata for entries with missing data
movie ls	Paginated interactive library browser
movie search <name>	Live TMDb search → save to DB
movie info <id|title>	Detail view (local DB → TMDb fallback)

movie scan ~/Downloads            # scan folder, fetch metadata + posters
movie rescan                      # re-fetch missing genres/ratings from TMDb
movie ls                          # browse library with pagination
movie search "Inception"          # search TMDb and save result
movie info 1                      # show details for media ID 1
movie info "The Batman"           # search by title

---

File Management

Command	Description
movie move [directory]	Browse, select, move with clean name
movie move --all	Batch move all files (auto-route by type)
movie rename	Batch rename to clean format
movie popout [directory]	Extract video files from subfolders to root
movie play <id>	Open with default video player
movie cd [folder-name]	Print path of a scanned folder for quick nav

movie move ~/Downloads            # interactive single-file move
movie move --all ~/Downloads      # batch move all files
movie rename                      # clean all filenames
movie popout ~/Downloads          # flatten nested subfolders
movie play 1                      # play with system player
cd $(movie cd Movies)             # navigate to scanned folder

---

History & Undo

Command	Description
movie undo	Revert last move/rename/delete/scan operation
movie undo --list	Show recent undoable actions
movie undo --batch	Undo the entire last batch (e.g. a full scan)
movie undo --id <id>	Undo a specific action by ID
movie redo	Re-apply the last undone operation
movie history	Show history of all tracked operations

movie undo                        # revert most recent operation
movie undo --list                 # see what can be undone
movie undo --batch                # undo entire last scan batch
movie undo --id 42                # undo specific action
movie redo                        # re-apply last undone operation
movie history                     # view full operation history

---

Discovery & Organization

Command	Description
movie suggest [N]	Genre-based recommendations + trending
movie discover [genre]	Browse TMDb by genre (interactive picker or direct)
movie tag add <id> <tag>	Add a tag to a media item
movie tag remove <id> <tag>	Remove a tag
movie tag list [id]	List tags (per item or all)
movie watch add <id>	Add a library item to your watchlist
movie watch done <id>	Mark a title as watched
movie watch undo <id>	Revert a title back to to-watch
movie watch rm <id>	Remove a title from your watchlist
movie watch ls	List your watchlist
movie watch export	Export watchlist as JSON for backup
movie watch import <file>	Import watchlist from JSON
movie stats	Counts, storage, genre chart, avg ratings
movie duplicates	Detect duplicate media entries

movie suggest 5                   # get 5 recommendations
movie discover                    # interactive genre picker
movie discover Action             # discover Action movies from TMDb
movie discover Comedy --type tv   # discover Comedy TV shows
movie discover Horror --page 2    # page 2 of Horror movies
movie tag add 1 favorite          # tag media #1 as favorite
movie tag list                    # list all tags
movie watch add 3                 # add media #3 to watchlist
movie watch done 3                # mark as watched
movie watch ls                    # view watchlist
movie stats                       # library statistics
movie duplicates                  # find duplicate entries

---

Maintenance & Debugging

Command	Description
movie cleanup	Find stale entries where files no longer exist
movie cleanup --remove	Delete stale entries (not just preview)
movie db	Show resolved database path and status
movie logs	Display recent error logs from the database
movie rest	Start a local REST API server for the library
movie rest --open	Start server and open in browser
movie export [-o path]	Dump media table as JSON

movie cleanup                     # dry run — show stale entries
movie cleanup --remove            # actually remove stale entries
movie db                          # check database location
movie logs                        # view recent error/warning logs
movie rest                        # start REST API on localhost
movie rest --open                 # start and open browser
movie export -o ~/library.json    # export full library as JSON

---

Configuration & System

Command	Description
movie config	Show all configuration
movie config set <key> <val>	Set a config value
movie version	Version, commit, build date, Go, OS/arch
movie update	Pull latest, rebuild, and deploy (copy-and-handoff)
movie update-cleanup	Remove leftover temp binaries and .bak backups
movie changelog [--latest]	Show release notes

movie config set movies_dir ~/Movies
movie config set tmdb_api_key YOUR_KEY
movie update                          # full self-update: pull → build → deploy
movie update-cleanup                  # remove temp update artifacts
movie changelog --latest

Config keys:

Key	Default	Purpose
movies_dir	~/Movies	Movie file destination
tv_dir	~/TVShows	TV show destination
archive_dir	~/Archive	Archive destination
scan_dir	~/Downloads	Default scan source
tmdb_api_key	(none)	TMDb API key
page_size	20	Items per page in ls

---

Command Tree

movie
├── hello                         # Greeting with version
├── version                       # Version, commit, build date, Go, OS/arch
├── changelog [--latest]          # Show changelog (full or latest version)
├── update                        # Pull → rebuild → deploy (copy-and-handoff)
├── update-cleanup                # Remove temp update artifacts
├── config [get|set] [key]        # View/set configuration
├── scan [folder]                 # Scan folder → DB + TMDb metadata
├── rescan                        # Re-fetch missing TMDb metadata
├── ls                            # Paginated library list (file-backed only)
├── search <name>                 # Live TMDb search → save to DB
├── info <id|title>               # Detail view (local DB → TMDb fallback)
├── suggest [N]                   # Recommendations + trending
├── discover [genre]              # Browse TMDb by genre
├── move [directory]              # Browse, select, move with clean name
├── rename                        # Batch rename to clean format
├── popout [directory]            # Extract videos from subfolders
├── undo [--list|--batch|--id]    # Revert operations (move/delete/scan)
├── redo                          # Re-apply last undone operation
├── history                       # Show all tracked operations
├── play <id>                     # Open with default video player
├── stats                         # Counts, storage, genre chart, avg ratings
├── duplicates                    # Detect duplicate media entries
├── cleanup [--remove]            # Find/remove stale entries
├── tag [add|remove|list]         # Manage user-defined tags
├── watch [add|done|undo|rm|ls|export|import]  # Manage watchlist + sync
├── cd [folder-name]              # Print scanned folder path
├── export [-o path]              # Dump media table as JSON
├── db                            # Show database path and status
├── logs                          # View error/warning logs
└── rest [--open]                 # Start local REST API server

---

Build & Deploy

Makefile Targets

Target	Description
make build	Compile for current platform
make build-all	Cross-compile all 6 targets into dist/
make build-windows	Windows amd64 (with embedded icon)
make build-windows-arm	Windows arm64 (with embedded icon)
make build-mac-arm	macOS ARM64
make build-mac-intel	macOS amd64
make build-linux	Linux amd64
make build-linux-arm	Linux arm64
make install	Build + copy to /usr/local/bin

Build via run.ps1

.\run.ps1                           # Full pipeline: pull, build, deploy
.\run.ps1 -NoPull                   # Skip git pull
.\run.ps1 -NoPull -NoDeploy        # Build only
.\run.ps1 -R movie scan D:\movies  # Build + run scan
.\run.ps1 -t                       # Run all unit tests
.\run.ps1 -ForcePull               # CI mode: discard changes + pull

Flag	Description
-NoPull	Skip git pull
-NoDeploy	Skip deploy step
-R	Run movie after build (trailing args forwarded)
-t	Run all unit tests
-ForcePull	CI mode: discard changes + pull

See spec/03-general/04-run-guide.md for the full usage guide.

---

Release Workflow

Releases are fully automated via GitHub Actions. Pushing to a release/** branch or a v* tag triggers:

1. Cross-compilation — 6 binaries (Windows/Linux/macOS × amd64/arm64)
2. Packaging — .zip (Windows) and .tar.gz (Unix)
3. SHA256 checksums — checksums.txt with all artifact hashes
4. Install scripts — version-pinned install.ps1 and install.sh
5. GitHub Release — formatted page with changelog, checksums, and install instructions

Creating a Release

# Option A: Push a release branch
git checkout -b release/v1.3.0
git push origin release/v1.3.0

# Option B: Tag directly
git tag v1.3.0
git push origin v1.3.0

Both trigger the same pipeline. Version is resolved from the ref name.

CI Pipeline: Pushing a release/* branch or v* tag triggers GitHub Actions to cross-compile 6 targets, generate checksums, and create a GitHub release with changelog and install instructions.

See spec/12-ci-cd-pipeline/02-release-pipeline.md for the full pipeline spec.

---

Project Structure

movie-cli-v6/
├── main.go                        # Entry point
├── cmd/                           # Cobra commands (one file per command)
│   ├── root.go                    # Root command, registers subcommands
│   ├── movie_config.go            # config get/set
│   ├── movie_scan.go              # scan folder
│   ├── movie_rescan.go            # re-fetch missing metadata
│   ├── movie_ls.go                # paginated list
│   ├── movie_search.go            # TMDb search
│   ├── movie_info.go              # detail view + shared fetch helpers
│   ├── movie_suggest.go           # recommendations
│   ├── movie_move.go              # interactive move
│   ├── movie_rename.go            # batch rename
│   ├── movie_popout.go            # extract from subfolders
│   ├── movie_undo.go              # undo operations
│   ├── movie_redo.go              # redo undone operations
│   ├── movie_history.go           # operation history
│   ├── movie_play.go              # play with system player
│   ├── movie_stats.go             # library statistics
│   ├── movie_duplicates.go        # duplicate detection
│   ├── movie_cleanup.go           # stale entry cleanup
│   ├── movie_tag.go               # tag management
│   ├── movie_watch.go             # watchlist management
│   ├── movie_cd.go                # folder navigation helper
│   ├── movie_export.go            # JSON export
│   ├── movie_db.go                # database path/status
│   ├── movie_logs.go              # error log viewer
│   ├── movie_rest.go              # REST API server
│   └── movie_resolve.go           # shared ID/title resolver
├── cleaner/cleaner.go             # Filename cleaning + slug generation
├── tmdb/client.go                 # TMDb API client
├── db/                            # SQLite database layer
│   ├── db.go                      # Connection + migrations
│   ├── media.go                   # Media CRUD operations
│   ├── config.go                  # Config get/set
│   └── history.go                 # Move + scan history
├── errlog/                        # Centralized error/warning logging
│   └── errlog.go                  # File + DB logging with stack traces
├── updater/                       # Copy-and-handoff self-update
│   ├── run.go                     # Entry points: Run() + RunWorker()
│   ├── repo.go                    # Repo path resolution
│   ├── handoff.go                 # Binary copy + foreground launch
│   ├── script.go                  # PowerShell script generation
│   └── cleanup.go                 # Temp artifact removal
├── version/version.go             # Build-time version variables
├── .github/
│   └── workflows/
│       ├── ci.yml                 # Lint + test + vulncheck + cross-build
│       ├── release.yml            # Cross-compile + GitHub Release
│       └── vulncheck.yml          # Weekly vulnerability scan
├── run.ps1                        # PowerShell build + deploy pipeline
├── install.ps1                    # Bootstrap installer
├── CHANGELOG.md                   # Release notes
└── spec/                          # Detailed specifications

---

Data Storage

All data lives in ./data/:

./data/
├── movie.db                  # SQLite database (WAL mode)
├── thumbnails/               # Downloaded poster images
└── json/
    ├── movie/                # Per-movie JSON metadata
    ├── tv/                   # Per-show JSON metadata
    └── history/              # Move operation logs (RFC3339)

---

Dependencies

Package	Purpose
github.com/spf13/cobra	CLI framework
modernc.org/sqlite	Pure-Go SQLite driver (no CGo)

---

🤝 Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository
2. Create a branch for your feature or fix:

   git checkout -b feature/my-feature
   

3. Follow the coding guidelines in spec/01-coding-guidelines/
4. Keep files small — one file per command, max ~200 lines
5. Run tests before submitting:

   make tidy
   go test ./... -v
   

6. Open a Pull Request against main with a clear description

Development Setup

git clone https://github.com/alimtvnetwork/movie-cli-v6.git
cd movie-cli-v6
make tidy
make build

See the Install Guide for full setup instructions.

Code Style

• Go standard formatting (gofmt)
• Descriptive variable names, no abbreviations
• Error messages start lowercase, no trailing punctuation
• All new code must pass go vet and golangci-lint

---

📜 Code of Conduct

We are committed to providing a welcoming and inclusive experience for everyone.

Our Standards:

• Be respectful, constructive, and empathetic
• Welcome newcomers and help them get started
• Accept constructive criticism gracefully
• Focus on what's best for the project and community

Unacceptable Behavior:

• Harassment, trolling, or personal attacks
• Publishing others' private information
• Any conduct that would be considered inappropriate in a professional setting

Enforcement: Project maintainers may remove, edit, or reject contributions that violate this code. Repeated violations may result in a temporary or permanent ban.

This Code of Conduct is adapted from the Contributor Covenant v2.1.

---

Author

Md. Alim Ul Karim

Creator & Lead Architect | Chief Software Engineer, Riseup Asia LLC

A system architect with 20+ years of professional software engineering experience across enterprise, fintech, and distributed systems. His technology stack spans .NET/C# (18+ years), JavaScript (10+ years), TypeScript (6+ years), and Golang (4+ years).

Recognized as a top 1% talent at Crossover and one of the top software architects globally. He is also the Chief Software Engineer of Riseup Asia LLC and maintains an active presence on Stack Overflow (2,452+ reputation, member since 2010) and LinkedIn (12,500+ followers).

Website	alimkarim.com · my.alimkarim.com
LinkedIn	linkedin.com/in/alimkarim
Stack Overflow	stackoverflow.com/users/361646/alim-ul-karim
Google	Alim Ul Karim
Role	Chief Software Engineer, Riseup Asia LLC

Riseup Asia LLC

Top Leading Software Company in WY (2026)

Website	riseup-asia.com
Facebook	riseupasia.talent
LinkedIn	Riseup Asia
YouTube	@riseup-asia

---

License

Private project.

Documentation

Overview

main.go — entry point.