Metacritic CLI

Undocumented internal JSON API powering metacritic.com (a Fandom property). Reverse-engineered from the site's public web client. Every request carries a shared public apiKey that the site embeds in its own JavaScript bundle, so no user credentials are required for read access.

One backend (backend.metacritic.com) serves every media type. The mcoTypeId query parameter selects the medium on the browse endpoint: 1 = TV shows, 2 = movies, 13 = games. The {mediaType} path segment (games, movies, shows) selects the medium on the title-detail, filters, and review endpoints.

The non-obvious insight: Metacritic is not just a review aggregator, it is a cross-media taste graph. Every gap between a title's Metascore (critics) and user score is a signal about critic-audience divergence.

Scope: this spec covers games, movies, and TV shows plus search, filters, title detail, and critic/user reviews. Music (albums) is served through a separate query shape and is intentionally left as a follow-up.

Learn more at Metacritic.

Created by @coopdogGGs (Ryan Cooper).

Quick Start

1. Install

See Install above.

2. Set Up Credentials

Get your API key from your API provider's developer portal. The key typically looks like a long alphanumeric string.

export METACRITIC_API_KEY="<paste-your-key>"

You can also persist this in your config file at ~/.config/metacritic-pp-cli/config.toml.

3. Verify Setup

metacritic-pp-cli doctor

This checks your configuration and credentials.

4. Try Your First Command

metacritic-pp-cli composer mock-value --media-type games --api-key your-token-here

Usage

Run metacritic-pp-cli --help for the full command reference and flag list.

Commands

composer

Manage composer

• metacritic-pp-cli composer <slug> - Returns the full composed detail payload for a title, including Metascore, user score, summary, release data, and platform/genre metadata.

finder

Manage finder

• metacritic-pp-cli finder browse-titles - Paginated, sortable list of titles for one medium. mcoTypeId selects the medium (1 = TV shows, 2 = movies, 13 = games). Powers the /browse/ pages.
• metacritic-pp-cli finder list-filters - Returns the filter facets (genres, platforms, streaming networks, product types) valid for the given medium.
• metacritic-pp-cli finder search-titles - Full-text search spanning games, movies, TV, and people.

reviews

Critic and user reviews for a title

• metacritic-pp-cli reviews list-critic - List critic reviews for a title
• metacritic-pp-cli reviews list-user - List user reviews for a title

Output Formats

# Human-readable table (default in terminal, JSON when piped)
metacritic-pp-cli composer mock-value --media-type games --api-key your-token-here

# JSON for scripting and agents
metacritic-pp-cli composer mock-value --media-type games --api-key your-token-here --json

# Filter to specific fields
metacritic-pp-cli composer mock-value --media-type games --api-key your-token-here --json --select id,name,status

# Dry run — show the request without sending
metacritic-pp-cli composer mock-value --media-type games --api-key your-token-here --dry-run

# Agent mode — JSON + compact + no prompts in one flag
metacritic-pp-cli composer mock-value --media-type games --api-key your-token-here --agent

Agent Usage

This CLI is designed for AI agent consumption:

• Non-interactive - never prompts, every input is a flag
• Pipeable - --json output to stdout, errors to stderr
• Filterable - --select id,name returns only fields you need
• Previewable - --dry-run shows the request without sending
• Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
• Offline-friendly - sync/search commands can use the local SQLite store when available
• Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.

Health Check

metacritic-pp-cli doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Config file: ~/.config/metacritic-pp-cli/config.toml

Static request headers can be configured under headers; per-command header overrides take precedence.

Environment variables:

Name	Kind	Required	Description
METACRITIC_API_KEY	per_call	Yes	Set to your API credential.

agentcookie (optional)

If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, metacritic-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.

Troubleshooting

Authentication errors (exit code 4)

• Run metacritic-pp-cli doctor to check credentials
• Verify the environment variable is set: echo $METACRITIC_API_KEY Not found errors (exit code 3)
• Check the resource ID is correct
• Run the list command to see available items

---

Generated by CLI Printing Press