Cremio

A functional way to access Stremio. Cremio is a TUI client built in Go with Bubbletea that talks to Stremio addons, lets you browse catalogs, search for movies and series, pick episodes, and fire streams straight into mpv. No browser, no Electron, no nonsense (I really didn't want a UI)

Disclaimer: This tool neither allows nor encourages streaming and distribution of pirated media. The tool reflects a Proof-of-concept of a Stremio client without any Graphical interface, and the usage in all aspects is subject to the Users' liability and not the tools'.

Quick Install

Windows

irm https://raw.githubusercontent.com/itssoap/cremio/main/install.ps1 | iex

Linux / macOS / FreeBSD

curl -fsSL https://raw.githubusercontent.com/itssoap/cremio/main/install.sh | bash

Both scripts download the latest binary, install it to a local bin directory, and add it to your PATH. Run the same command again anytime to check for and install updates.

Prerequisite: mpv must be in your system PATH.

Updating

Re-running the install command updates cremio in place. The updater is SHA-aware: it compares the SHA-256 of your installed binary against the checksum GitHub publishes for the release asset, so it only downloads when the binary actually differs (falling back to version-tag comparison if no checksum is exposed).

It looks for the binary to replace in this order:

1. cremio (or cremio.exe) in the current working directory
2. cremio found on your PATH
3. Otherwise a fresh install to the default bin directory

Flags

Goal	Windows (PowerShell)	Linux / macOS / FreeBSD
Only check for an update (no changes)	... install.ps1))) -CheckOnly	... | bash -s -- --check
Update to the newest pre-release	... install.ps1))) -PreRelease	... | bash -s -- --pre-release
Skip modifying PATH	... install.ps1))) -NoPath	... | bash -s -- --no-path
Uninstall (keeps history/session by default)	... install.ps1))) -Uninstall	... | bash -s -- --uninstall
Uninstall and delete config/data too	... install.ps1))) -Uninstall -PurgeData	... | bash -s -- --uninstall --purge-data

On Linux/macOS, append flags after bash -s --:

curl -fsSL https://raw.githubusercontent.com/itssoap/cremio/main/install.sh | bash -s -- --check
curl -fsSL https://raw.githubusercontent.com/itssoap/cremio/main/install.sh | bash -s -- --pre-release

On Windows, because irm | iex cannot forward arguments, pass flags by turning the downloaded script into a script block:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/itssoap/cremio/main/install.ps1))) -CheckOnly
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/itssoap/cremio/main/install.ps1))) -PreRelease

Do not write irm ...install.ps1 -CheckOnly | iex. The -CheckOnly there binds to irm (Invoke-RestMethod), not to the script, and fails with "A parameter cannot be found that matches parameter name 'CheckOnly'". Use the script-block form above instead.

Every download is verified against the published SHA-256 before it replaces your existing binary; a mismatch aborts the update without touching the installed file.

Uninstall

Uninstalling removes the cremio binary, its version marker, and the install directory from your PATH. Your config and data (watch history, saved account session) are kept by default and you are asked before they are deleted; add the purge flag to remove them too. A cremio binary in your current directory (a local build) is never touched.

Windows (PowerShell):

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/itssoap/cremio/main/install.ps1))) -Uninstall

# Also delete config/data (history, session) without prompting:
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/itssoap/cremio/main/install.ps1))) -Uninstall -PurgeData

Linux / macOS / FreeBSD:

curl -fsSL https://raw.githubusercontent.com/itssoap/cremio/main/install.sh | bash -s -- --uninstall

# Also delete config/data (history, session) without prompting:
curl -fsSL https://raw.githubusercontent.com/itssoap/cremio/main/install.sh | bash -s -- --uninstall --purge-data

What gets removed / where data lives:

	Windows	Linux / macOS / FreeBSD
Binary	%LOCALAPPDATA%\cremio\bin\cremio.exe	~/.local/bin/cremio
Version marker	%LOCALAPPDATA%\cremio\.version	~/.local/share/cremio/.version
PATH entry	user PATH	shell profile line (a .bak backup is saved)
Config/data (kept unless purged)	%APPDATA%\cremio\	~/.config/cremio/

Features

• Browse catalogs from all installed Stremio addons
• Cinemeta (v3) installed by default on first run; can be removed via the Addons tab
• Full-text search with automatic fallback to client-side filtering
• Search category checkboxes (Movies, Series, ...) to narrow results; press 1-9 to toggle
• Optional auto-focus of the search bar when switching to the Search tab (set auto_focus_search in config)
• History tab for quick access to watched movies and shows
• Series support with season/episode navigation
• Stream resolution across multiple addons (fetched in parallel)
• Stream info panel toggle (i key) showing release, file name, size, source, group, addon, type
• Per-stream filtering (/) plus a Global Filters tab for persistent, cross-addon rules
• Playback via mpv (should be in PATH)
• Playlist mode: batch-play all episodes sequentially via mpv (on by default; set playlist_mode: false to disable)
• Download streams keeping the original file name
  • Folder layout: <Name> (<Year>)/<file> for movies, <Show> (<Year>)/Season XX/<file> for series
  • Download location priority: configured download_dir > OS Downloads folder > current directory
  • Single movie/episode download with d key
  • Batch season download: choose release group (with resolution/size info), select episodes, queue
  • Downloads popup (D key) with live progress, speed, ETA, cancel, queue management
  • aria2c support for accelerated downloads (auto-detected; multi-connection with live status)
• Global Filters tab: persistent include/exclude rules for source/provider tag (RD, Torrentio, ...), file info, file source, type, and release group
• Addon management (add/remove by URL with manifest validation)
• Persistent configuration stored as JSON

Prerequisites

• mpv in your system PATH (for stream playback)
• aria2c (optional) in your system PATH for accelerated downloads
• Go 1.25 or later (only needed to build from source)
• go-winres (optional, only needed to embed a custom icon on Windows builds)

Pre-built Windows binaries are available on the releases page. Use the Quick Install command above for the easiest setup.

Development Setup

Clone the repository and install dependencies:

git clone https://github.com/itssoap/cremio.git
cd cremio
go mod tidy

Run the application directly:

go run .

Compilation

Build a standalone binary:

go build -o cremio.exe .

On Linux or macOS, omit the .exe extension (I haven't tested the build on these systems, will need assistance for this):

go build -o cremio .

Windows Icon Embedding

To embed a custom icon into the Windows executable, install go-winres and regenerate the resource files before building:

go install github.com/tc-hib/go-winres@latest

Place your icon as a PNG in winres/icon.png (max 256x256) and winres/icon16.png (16x16), then:

go-winres make
go build -o cremio.exe .

The generated .syso files are excluded from version control via .gitignore and must be regenerated locally.

Configuration

Cremio stores its configuration as a JSON file:

• Windows: %APPDATA%\cremio\config.json
• Linux/macOS: ~/.config/cremio/config.json

The config file holds the list of installed addon base URLs and optional settings. It is created automatically on first use. Cinemeta (v3) is added as the default addon on first run.

{
  "addons": [
    "https://v3-cinemeta.strem.io/manifest.json"
  ],
  "auto_focus_search": false,
  "global_filters": {
    "addon": "",
    "file_info": "",
    "file_source": "",
    "type": "",
    "release_group": ""
  },
  "download_dir": "",
  "download_use_aria2c": true,
  "download_parallel": 1,
  "stream_fetch_concurrency": 1
}

On Windows, if you set download_dir, write the path with double backslashes ("C:\\Users\\me\\Downloads") or forward slashes ("C:/Users/me/Downloads"); a single backslash is invalid JSON. A malformed config no longer crashes cremio: the bad file is renamed to config.json.invalid and defaults are restored.

Configuration fields

Field	Type	Default	Description
addons	array of strings	[cinemeta URL]	List of installed Stremio addon manifest URLs
auto_focus_search	boolean	false	When true, the search input is automatically focused when switching to the Search tab
playlist_mode	boolean	true	Batch playback sends all episodes to mpv as a playlist. Omitted by default (on); set to false to disable
global_filters	object	all empty	Persistent per-field stream filters (also editable in the Filters tab)
download_dir	string	""	Base download directory. Priority: this > OS Downloads folder > current directory
download_use_aria2c	boolean	true	Use aria2c for downloads if available in PATH (falls back to Go HTTP)
download_parallel	integer	1	Number of simultaneous downloads
stream_fetch_concurrency	integer	1	Max concurrent stream requests sent to a single addon when loading a whole season. Aggregators (e.g. AIOStreams) rate-limit and drop episodes above 1, so keep this at 1 unless your addons tolerate more. Different addons are always queried in parallel

Watch History

Cremio tracks watched movies and episodes in a local JSON file:

• Windows: %APPDATA%\cremio\history.json
• Linux/macOS: ~/.config/cremio/history.json

Episodes are automatically marked as watched when played via mpv. You can also manually toggle watched status with the w key - on individual episodes, whole seasons, or movies.

The file uses a simple JSON structure:

{
  "movies": [
    {
      "watched_at": "2026-05-26T12:00:00Z",
      "ids": { "imdb": "tt1234567" }
    }
  ],
  "shows": [
    {
      "ids": { "imdb": "tt7654321" },
      "seasons": [
        {
          "number": 1,
          "episodes": [
            { "number": 1, "watched_at": "2026-05-26T12:00:00Z" },
            { "number": 2, "watched_at": "2026-05-26T12:30:00Z" }
          ]
        }
      ]
    }
  ]
}

Controls

Key	Action
tab	Cycle between Home, Search, Addons, Filters, and History tabs
/	Focus the search input (Search tab) / filter (Streams)
enter	Select item / submit input / edit filter field
esc	Go back / unfocus input / cancel loading
w	Toggle watched (episode, season, or movie)
f	Fetch streams for all episodes (series)
d	Download stream or batch download (series/streams)
D	Toggle downloads popup (global)
i	Toggle stream info panel (Streams)
s	Select search addon (Search tab)
1-9	Toggle a search category (Search tab)
c / C	Clear selected / all fields (Filters tab)
a	Add a new addon (Addons tab)
q	Quit
ctrl+c	Quit

Project Structure

main.go                  Entry point
internal/
  config/config.go       Configuration loading, saving, addon management
  history/history.go     Watch history tracking
  player/
    mpv.go               mpv process launcher (single + playlist)
    download.go          Download manager, HTTP/aria2c backends, path builders
  stremio/
    client.go            HTTP client for the Stremio Addon Protocol
    types.go             Manifest, catalog, meta, stream type definitions
  tui/
    app.go               Root Bubbletea model and screen routing
    home.go              Home screen with catalog browsing
    search.go            Search screen with addon querying
    addons.go            Addon management screen
    globalfilters.go     Global Filters tab (persistent stream filters)
    detail.go            Movie/series detail and episode list
    streams.go           Stream list, mpv launch, download flow
    downloads.go         Downloads popup with progress and queue management
    historytab.go        History tab for browsing watched movies and shows
    styles.go            Lipgloss style definitions
winres/
  winres.json            Windows resource manifest for go-winres
  icon.png               Application icon (256x256)
  icon16.png             Application icon (16x16)

Contributing

1. Fork the repository
2. Create a feature branch
3. Keep changes focused and minimal
4. Submit a pull request

Please avoid introducing new dependencies unless strictly necessary. Keep the codebase simple and the TUI responsive.

Where to make changes

Use the table below to find the right file for what you want to improve:

What you want to change	File(s)
Home tab - catalog browsing, how items are loaded or displayed	internal/tui/home.go
Search tab - search input, result deduplication, client-side filtering	internal/tui/search.go
Addons tab - add/remove addons, URL validation, manifest display	internal/tui/addons.go
Detail screen - movie/series info layout, episode/season list, watched toggle	internal/tui/detail.go
Streams screen - stream list, filter, info panel, mpv launch, batch mode, download flow	internal/tui/streams.go
Global Filters tab - persistent per-field stream filters	internal/tui/globalfilters.go
Downloads popup - progress bars, queue management, cancel	internal/tui/downloads.go
History tab - watched movies/shows list, navigation to detail	internal/tui/historytab.go
Screen routing & global keys - tab switching, ESC behaviour, app-level messages	internal/tui/app.go
Colours, borders, text styles	internal/tui/styles.go
Stremio addon protocol - HTTP client, endpoint logic	internal/stremio/client.go
Stremio types - manifest, catalog, meta, stream structs	internal/stremio/types.go
Watch history - toggle watched, local JSON structure	internal/history/history.go
Download manager - queue, HTTP/aria2c backends, folder/file naming	internal/player/download.go
Config - addon list persistence, config file path	internal/config/config.go
App data directory - where config & history are stored	internal/appdir/appdir.go
mpv integration - launch flags, extra arguments	internal/player/mpv.go
Windows executable icon / version metadata	winres/winres.json

FAQ/Known issues

Q. Search is broken? I see results showing in Stremio, but not on this app.

A. Cinemeta is installed by default on first run. If you removed it, re-add it from the Addons tab. Some addons lack search capability in their catalogs by default.

Q. Sometimes the Search results appear blank, but it seems like I am able to navigate across them.

A. Please restart the app. This issue occurs very seldomly.

Q. It shows "▶ Launched", but I don't see the mpv window yet?

A. mpv takes its own sweet time to fetch the metadata and start the stream. Cremio triggers mpv as an independent process, so that killing cremio won't kill your stream.

License

This project is licensed under the MIT License.