CLI

The media CLI for config bootstrap, SQL migration generation, and applying schema to the database.

Better Media ships a small CLI (media, also available as better-media when installed from the better-media package) to bootstrap config, generate migration SQL from the built-in schema, and migrate the database when your adapter supports it.

The CLI lives in @better-media/cli and is the default binary for the better-media metapackage; your app only needs a project config file the commands can load.

Installation

Add the framework (which includes the CLI binary) or the CLI package directly. Pick your package manager in the tab below—the same choice is kept for every command on this page, and it matches the Installation package manager tabs.

pnpm add better-media
# or
pnpm add -D @better-media/cli

npm install better-media
# or
npm install --save-dev @better-media/cli

yarn add better-media
# or
yarn add -D @better-media/cli

Run the CLI with your package manager (after install, the media binary is on your path via npx / yarn / pnpm exec):

pnpm exec media --help

npx media --help

yarn media --help

Config discovery

Commands that need your database adapter resolve a config file from the current working directory (or --cwd), unless you pass --config <path> explicitly.

The loader looks for, in order:

• media.config.ts
• media.config.js
• better-media.config.ts
• better-media.config.js

The file must export an object with at least the fields expected by getAdapter in @better-media/core (e.g. database, and optionally dialect, schemaOutput, migrationsDir).

TypeScript configs are supported via ts-node (install it in your app) or a fallback transpile path. If loading fails, follow the error message or switch to a .js config.

init

Scaffolds a starter media.config.ts or media.config.js in the project root. The template uses a PostgreSQL pg Pool and sets dialect: "postgres" and migrationsDir: "better-media". Framework is detected from package.json (Express vs NestJS vs generic) for messaging only; the file shape is the same.

pnpm exec media init

npx media init

yarn media init

Options

If pg is not in your dependencies, the command prints a hint to install it.

generate

Generates Better Media database migrations (SQL and snapshot metadata) for the configured adapter. Resolution uses your config file, then getAdapter to obtain a DatabaseAdapter.

For the Kysely-style path, the CLI plans operations from the canonical schema in core, compares to the latest snapshot or database introspection (when available), and writes a timestamped run directory under your migrations root containing migration.sql and snapshot.json. If there is nothing to apply, it prints that the database (or snapshot) is already up to date.

pnpm exec media generate

npx media generate

yarn media generate

Options

Output location: controlled by schemaOutput in config (default directory derived from better-media-migrations/migration.sql) and/or migrationsDir for the folder that holds timestamped runs.

migrate

Applies the planned migration to the database when the adapter supports direct execution (the built-in Kysely/Postgres path with __getMetadata and __executeMigration). For other adapters, use generate and run SQL or migrations through your own tooling.

pnpm exec media migrate

npx media migrate

yarn media migrate

You will be prompted to confirm unless you pass --yes.

Options

If the adapter is Prisma or Drizzle and an error is thrown in a way the CLI treats as “use your ORM,” the process may exit without throwing (see the migrate command’s error handling). Prefer generate + your ORM when direct migrate is not supported.

config

Validates that the project config loads and resolves, then prints a small debug summary (config path, adapter hint, dialect, schemaOutput, migrationsDir).

pnpm exec media config

npx media config

yarn media config

Options

It is a lightweight diagnostic for config resolution; it does not print system information, package-manager versions, or a full environment report.

Common issues

No configuration file found

Add one of the expected filenames in the project root, or pass --config.

Cannot load media.config.ts

Install ts-node in the project, or use a .js config, or check that imports in the config resolve (avoid path aliases the standalone loader cannot resolve; prefer relative imports in the config when in doubt).

migrate / generate says the adapter is not supported

Use an adapter that implements the Kysely migration hooks, or rely on generate output and apply it manually. Custom adapters can implement createSchema (for generate) and the metadata/execute hooks (for migrate).

Wrong directory

Use -C / --cwd to point at the package root that contains package.json and the media config.

Relation to the framework

The CLI does orchestration only: it loads config, gets an adapter, and calls into @better-media/core (schema, MigrationPlanner, getMigrations, etc.). It does not start an HTTP server or run upload pipelines—those stay in your app via createBetterMedia. See the API page for the runtime surface.