back
loading skill details...
CLI for the Seer media request management API. Search movies and TV shows, create and manage media requests, manage users, track issues, and administer a sel...
---
name: seer-cli
description: >-
CLI for the Seer media request management API. Search movies and TV shows,
create and manage media requests, manage users, track issues, and administer
a self-hosted Seer instance. Use when asked to find, request, or manage media
content, check what is trending, look up actors or collections, manage users,
or check system status.
metadata:
author: electather
repo: https://github.com/electather/seer-cli
env:
- name: SEER_SERVER
description: Full URL of your Seer instance (e.g. https://seer.example.com)
required: true
- name: SEER_API_KEY
description: API key for authenticating with the Seer server
required: true
- name: SEER_MCP_AUTH_TOKEN
description: Bearer token for authenticating MCP HTTP transport clients (required when running the HTTP server; omit for stdio transport)
required: false
---
# seer-cli
CLI for interacting with a [Seer](https://github.com/seerr/app) media request management server.
## Installation
Download the latest release archive and checksum file from the [Releases page](https://github.com/electather/seer-cli/releases/latest), verify, and install:
```bash
# Replace <os> and <arch> with your platform (linux/darwin, amd64/arm64)
curl -fsSL https://github.com/electather/seer-cli/releases/latest/download/seer-cli_<version>_<os>_<arch>.tar.gz -o seer-cli.tar.gz
curl -fsSL https://github.com/electather/seer-cli/releases/latest/download/seer-cli_<version>_checksums.txt -o checksums.txt
grep seer-cli_<version>_<os>_<arch>.tar.gz checksums.txt | sha256sum -c
tar -xzf seer-cli.tar.gz
sudo mv seer-cli /usr/local/bin/
```
Supports Linux and macOS (amd64 / arm64).
## Docker
Run the MCP HTTP server in a container next to your Seer instance:
```bash
# With Bearer token auth
docker run --rm \
-e SEER_SERVER=http://your-seer-instance:5055 \
-e SEER_API_KEY=your-api-key \
-e SEER_MCP_AUTH_TOKEN=your-secret-token \
-p 8811:8811 \
ghcr.io/electather/seer-cli:latest
```
MCP endpoint: `http://localhost:8811/mcp` — set `Authorization: Bearer your-secret-token` in your MCP client.
For clients that cannot send custom headers (e.g. claude.ai remote MCP), use a secret path prefix:
```bash
docker run --rm \
-e SEER_SERVER=http://your-seer-instance:5055 \
-e SEER_API_KEY=your-api-key \
-e SEER_MCP_ROUTE_TOKEN=your-secret-path \
-e SEER_MCP_NO_AUTH=true \
-e SEER_MCP_CORS=true \
-p 8811:8811 \
ghcr.io/electather/seer-cli:latest
```
MCP endpoint: `http://localhost:8811/your-secret-path/mcp` — no auth header required.
At least one of `SEER_MCP_AUTH_TOKEN`, `SEER_MCP_ROUTE_TOKEN`, or `SEER_MCP_NO_AUTH=true` must be set for HTTP transport.
### docker-compose deployment
Use the included `docker-compose.yml` to deploy alongside Seer:
```bash
SEER_API_KEY=xxx SEER_MCP_AUTH_TOKEN=secret docker compose up -d
```
The default `SEER_SERVER` in the compose file points to `http://seer:5055` (the Seer service name). Override it if your Seer instance is elsewhere.
### Running CLI commands via Docker
Override the default CMD to run any CLI command:
```bash
docker run --rm \
-e SEER_SERVER=http://your-seer-instance:5055 \
-e SEER_API_KEY=your-api-key \
ghcr.io/electather/seer-cli:latest \
status system
```
## Setup
```bash
seer-cli config set --server https://your-seer-instance.com --api-key YOUR_KEY
seer-cli config show # verify
```
Environment variables also work: `SEER_SERVER`, `SEER_API_KEY`.
## Global Flags
- `-s, --server` — Seer server URL
- `-k, --api-key` — API key
- `-v, --verbose` — show request URLs and HTTP status codes
- `--config` — path to config file (default `~/.seer-cli.yaml`)
## Output
All commands return JSON. Pipe to `jq` for filtering. With `--verbose`, extra info (URL, HTTP status) is printed before the JSON.
## Commands
### Search & Discovery
Find movies, TV shows, and people:
```bash
seer-cli search multi -q "The Matrix" # search everything
seer-cli search multi -q "Nolan" --page 2 # paginated results
seer-cli search keyword -q "sci-fi" # TMDB keywords
seer-cli search company -q "A24" # production companies
seer-cli search trending # currently trending
seer-cli search trending --time-window week # weekly trending
seer-cli search movies --genre 28 # discover by genre
seer-cli search movies --studio 7505 # by studio
seer-cli search movies --sort-by popularity.desc # custom sort
seer-cli search tv --genre 18 --network 213 # TV by genre + network
```
Search results include a `mediaType` field (`movie`, `tv`, or `person`) and a TMDB `id` used by other commands.
If `mediaInfo` exists on a result, it's already tracked. `mediaInfo.status` values: 1=unknown, 2=pending, 3=processing, 4=partially available, 5=available.
### Movie Details
```bash
seer-cli movies get 157336 # details by TMDB ID
seer-cli movies ratings 157336 # ratings
seer-cli movies ratings-combined 157336 # combined RT/IMDB ratings
seer-cli movies recommendations 157336 # recommended movies
seer-cli movies similar 157336 # similar movies
```
### TV Show Details
```bash
seer-cli tv get 72844 # show details
seer-cli tv ratings 72844 # ratings
seer-cli tv recommendations 72844 # recommendations
seer-cli tv similar 72844 # similar shows
seer-cli tv season 72844 1 # season details + episodes
```
### Requesting Media
Create requests for movies or TV shows using their TMDB ID:
```bash
# Request a movie
seer-cli request create --media-type movie --media-id 157336
# Request a TV show (all seasons)
seer-cli request create --media-type tv --media-id 72844 --seasons all
# Request specific seasons
seer-cli request create --media-type tv --media-id 72844 --seasons 1,2
# Request 4K version
seer-cli request create --media-type movie --media-id 157336 --is4k
```
Manage existing requests:
```bash
seer-cli request list # list all requests
seer-cli request get 5 # get specific request
seer-cli request count # counts by status
seer-cli request approve 5 # approve
seer-cli request decline 5 # decline
seer-cli request retry 5 # retry failed request
seer-cli request delete 5 # delete
```
### Media Management
```bash
seer-cli media list # list all tracked media
seer-cli media status 1 available # update status
seer-cli media watch-data 1 # get watch data
seer-cli media delete 1 # remove from Seer
seer-cli media delete-file 1 # delete file from Radarr/Sonarr
```
### Issues
Report and track problems with media:
```bash
seer-cli issue list # list all issues
seer-cli issue create # create new issue
seer-cli issue get 3 # get issue details
seer-cli issue count # issue counts
seer-cli issue comment 3 # add comment
seer-cli issue update-status 3 resolved # resolve issue
seer-cli issue delete 3 # delete issue
```
### Watchlist
```bash
seer-cli watchlist add --media-type movie --tmdb-id 157336
seer-cli watchlist add --media-type tv --tmdb-id 72844
seer-cli watchlist delete 1 # remove by watchlist ID
```
### Blocklist
Prevent media from appearing in discovery:
```bash
seer-cli blocklist list # list blocked items
seer-cli blocklist get 157336 # get by TMDB ID
seer-cli blocklist add --tmdb-id 157336 # add to blocklist
seer-cli blocklist delete 1 # remove by ID
```
### People
```bash
seer-cli person get 525 # person details
seer-cli person combined-credits 525 # all movie + TV credits
```
### Collections
```bash
seer-cli collection get 2344 # collection details (e.g., a film series)
```
### Users
```bash
seer-cli users list # list all users
seer-cli users get 1 # user details
seer-cli users create # create user
seer-cli users update 1 # update user
seer-cli users delete 1 # delete user
seer-cli users requests 1 # user's requests
seer-cli users watchlist 1 # user's watchlist
seer-cli users watch-data 1 # user's watch data
seer-cli users quota 1 # user's request quota
seer-cli users import-from-plex # import Plex users
seer-cli users import-from-jellyfin # import Jellyfin users
seer-cli users bulk-update # bulk permission update
seer-cli users settings get 1 # get user settings
seer-cli users password reset 1 # reset password
```
### Services (Radarr / Sonarr)
```bash
seer-cli service radarr-list # list Radarr servers
seer-cli service radarr-get 1 # profiles + root folders
seer-cli service sonarr-list # list Sonarr servers
seer-cli service sonarr-get 1 # profiles + root folders
seer-cli service sonarr-lookup 72844 # look up series in Sonarr
```
### TMDB Metadata
```bash
seer-cli tmdb genres-movie # movie genre IDs
seer-cli tmdb genres-tv # TV genre IDs
seer-cli tmdb languages # supported languages
seer-cli tmdb regions # supported regions
seer-cli tmdb network 213 # network details (e.g., Netflix)
seer-cli tmdb studio 7505 # studio details
seer-cli tmdb backdrops # trending backdrops
```
### Other Lookups
```bash
seer-cli other certifications-movie # movie age ratings by country
seer-cli other certifications-tv # TV age ratings by country
seer-cli other keyword 180547 # keyword details
seer-cli other watchprovider-regions # available streaming regions
seer-cli other watchproviders-movies # movie streaming providers
seer-cli other watchproviders-tv # TV streaming providers
```
### Override Rules
Custom rules for request routing:
```bash
seer-cli overriderule list # list rules
seer-cli overriderule create # create rule
seer-cli overriderule update 1 # update rule
seer-cli overriderule delete 1 # delete rule
```
### System Status
```bash
seer-cli status system # server version + status
seer-cli status appdata # app data volume info
```
## MCP Server
`seer-cli mcp serve` starts a Model Context Protocol server that exposes the Seer API as tools. This lets AI agents (including Claude Desktop) use seer-cli without invoking the CLI directly.
### stdio transport (Claude Desktop)
Claude Desktop spawns the process and communicates over stdin/stdout. No authentication or network configuration required.
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"seer": {
"command": "/usr/local/bin/seer-cli",
"args": ["mcp", "serve"],
"env": {
"SEER_SERVER": "https://your-seer-instance.com",
"SEER_API_KEY": "your-api-key"
}
}
}
}
```
### HTTP transport
For MCP clients that connect over HTTP with Bearer token auth:
```bash
seer-cli mcp serve --transport http --addr :8811 --auth-token mysecrettoken
```
Endpoint: `http://localhost:8811/mcp` — set `Authorization: Bearer mysecrettoken` in your client.
For clients that cannot send custom headers (e.g. claude.ai remote MCP), use a secret path prefix via `--route-token` (or `SEER_MCP_ROUTE_TOKEN`):
```bash
# Add --cors if connecting from a browser-based client (e.g. claude.ai)
seer-cli mcp serve --transport http --addr :8811 --route-token abc123 --no-auth --cors
# Endpoint becomes: http://localhost:8811/abc123/mcp
```
Both methods can be combined for defense in depth:
```bash
seer-cli mcp serve --transport http --route-token abc123 --auth-token mysecrettoken
```
All flags are configurable via environment variables:
| Flag | Environment variable | Default |
|------|---------------------|---------|
| `--transport` | `SEER_MCP_TRANSPORT` | `stdio` |
| `--addr` | `SEER_MCP_ADDR` | `:8811` |
| `--auth-token` | `SEER_MCP_AUTH_TOKEN` | — |
| `--no-auth` | `SEER_MCP_NO_AUTH` | `false` |
| `--route-token` | `SEER_MCP_ROUTE_TOKEN` | — |
| `--cors` | `SEER_MCP_CORS` | `false` |
| `--tls-cert` | `SEER_MCP_TLS_CERT` | — |
| `--tls-key` | `SEER_MCP_TLS_KEY` | — |
> Pass `--cors` (or `SEER_MCP_CORS=true`) to enable CORS headers for browser-based clients (e.g. claude.ai). Disabled by default.
> The HTTP transport does not implement OAuth 2.0. Use stdio for Claude Desktop.
### MCP tools available
| Category | Tools |
|---|---|
| Search | `search_multi`, `search_discover_movies`, `search_discover_tv`, `search_trending` |
| Movies | `movies_get`, `movies_recommendations`, `movies_similar`, `movies_ratings` |
| TV | `tv_get`, `tv_season`, `tv_recommendations`, `tv_similar`, `tv_ratings` |
| Requests | `request_list`, `request_get`, `request_create`, `request_approve`, `request_decline`, `request_delete`, `request_count` |
| Media | `media_list`, `media_status_update` |
| Issues | `issue_list`, `issue_get`, `issue_create`, `issue_status_update`, `issue_count` |
| Users | `users_list`, `users_get`, `users_quota` |
| People & Collections | `person_get`, `person_credits`, `collection_get` |
| Services | `service_radarr_list`, `service_sonarr_list` |
| Settings | `settings_about`, `settings_jobs_list`, `settings_jobs_run` |
| Watchlist & Blocklist | `watchlist_add`, `watchlist_remove`, `blocklist_list`, `blocklist_add`, `blocklist_remove` |
| System | `status_system` |
## Common Workflows
### Find and request a movie
```bash
seer-cli search multi -q "Interstellar" # find TMDB ID
seer-cli movies get 157336 # confirm details
seer-cli request create --media-type movie --media-id 157336
```
### Find and request a TV show
```bash
seer-cli search multi -q "Breaking Bad" # find TMDB ID
seer-cli tv get 1396 # confirm details
seer-cli request create --media-type tv --media-id 1396 --seasons all
```
### Check what genre IDs mean
```bash
seer-cli tmdb genres-movie # e.g., 28=Action, 18=Drama
seer-cli tmdb genres-tv
```
don't have the plugin yet? install it then click "run inline in claude" again.