@prisma-next/cli 0.10.0-dev.22 → 0.10.0-dev.24

package/src/commands/init/templates/readme-mongo.md

@@ -0,0 +1,35 @@
+# {{projectName}}
+
+Generated by `prisma-next init` with the Minimal template.
+
+## First run
+
+1. `{{runDbUp}}` — start the local MongoDB replica set with `mongodb-memory-server`. Data persists in `.mongo-data/` across restarts.
+2. `{{runDev}}` — runs `src/index.ts`, which writes one row and reads it back.
+
+## Available scripts
+
+- `{{runDev}}` — run the Prisma Next sample script
+
+### Database and migrations
+
+- `{{runContractEmit}}` — emit contract artifacts after contract changes
+- `{{runDbUp}}` — start the local MongoDB replica set with `mongodb-memory-server`. Data persists in `.mongo-data/` across restarts.
+- `{{runDbDown}}` — stop the local MongoDB process (data preserved)
+- `{{runDbReset}}` — stop and wipe `.mongo-data/` for a clean slate
+- `{{runMigrationPlan}}` — create a MongoDB migration plan
+- `{{runMigrate}}` — apply the planned MongoDB migration
+- `{{runDbSeed}}` — insert sample users manually
+
+## Prisma Next
+
+Prisma Next setup is scaffolded in:
+
+- `{{contractPath}}`
+- `prisma-next.config.ts`
+- `prisma/db.ts`
+- `src/lib/prisma.ts`
+
+For provider-specific Prisma Next reference docs, see `prisma-next.md`. Prisma Next skills live in the upstream `skills/` directory: https://github.com/prisma/prisma-next/tree/main/skills.
+
+Node-based Prisma Next projects expect Node.js 24 LTS or newer.

package/src/commands/init/templates/readme-postgres.md

@@ -0,0 +1,34 @@
+# {{projectName}}
+
+Generated by `prisma-next init` with the Minimal template.
+
+## First run
+
+1. `{{runDbInit}}` — applies your contract to the database (creates tables, signs the marker).
+2. `{{runDev}}` — runs `src/index.ts`, which writes one row and reads it back.
+
+## Available scripts
+
+- `{{runDev}}` — run the Prisma Next sample script
+
+### Database and migrations
+
+- `{{runContractEmit}}` — emit contract artifacts after contract changes
+- `{{runDbInit}}` — initialize database state manually
+- `{{runDbUpdate}}` — update database state manually
+- `{{runMigrationPlan}}` — create a migration plan
+- `{{runMigrate}}` — apply a planned migration
+- `{{runDbSeed}}` — insert sample users manually (run after `db:init`)
+
+## Prisma Next
+
+Prisma Next setup is scaffolded in:
+
+- `{{contractPath}}`
+- `prisma-next.config.ts`
+- `prisma/db.ts`
+- `src/lib/prisma.ts`
+
+For provider-specific Prisma Next reference docs, see `prisma-next.md`. Prisma Next skills live in the upstream `skills/` directory: https://github.com/prisma/prisma-next/tree/main/skills.
+
+Node-based Prisma Next projects expect Node.js 24 LTS or newer.

package/src/commands/init/templates/readme.ts

@@ -0,0 +1,62 @@
+import { formatRunScriptCommand, type PackageManager } from '../detect-package-manager';
+import type { TargetId } from './code-templates';
+import { renderTemplate } from './render';
+
+const sharedVariables = ['projectName', 'contractPath', 'runDev', 'runContractEmit'] as const;
+
+export const postgresVariables = [
+  ...sharedVariables,
+  'runDbInit',
+  'runDbUpdate',
+  'runMigrationPlan',
+  'runMigrate',
+  'runDbSeed',
+] as const;
+
+export const mongoVariables = [
+  ...sharedVariables,
+  'runDbUp',
+  'runDbDown',
+  'runDbReset',
+  'runMigrationPlan',
+  'runMigrate',
+  'runDbSeed',
+] as const;
+
+type PostgresVars = Record<(typeof postgresVariables)[number], string>;
+type MongoVars = Record<(typeof mongoVariables)[number], string>;
+
+export function minimalProjectReadmeMd(
+  target: TargetId,
+  schemaPath: string,
+  projectName: string,
+  pm: PackageManager,
+): string {
+  const run = (script: string): string => formatRunScriptCommand(pm, script);
+  const shared = {
+    projectName,
+    contractPath: schemaPath,
+    runDev: run('dev'),
+    runContractEmit: run('contract:emit'),
+    runMigrationPlan: run('migration:plan'),
+    runMigrate: run('migrate'),
+    runDbSeed: run('db:seed'),
+  };
+
+  if (target === 'mongo') {
+    const vars: MongoVars = {
+      ...shared,
+      runDbUp: run('db:up'),
+      runDbDown: run('db:down'),
+      runDbReset: run('db:reset'),
+    };
+    return renderTemplate('readme-mongo.md', mongoVariables, vars);
+  }
+
+  const vars: PostgresVars = {
+    ...shared,
+    runDbInit: run('db:init'),
+    runDbUpdate: run('db:update'),
+  };
+  return renderTemplate('readme-postgres.md', postgresVariables, vars);
+}

package/src/commands/migrate.ts

@@ -43,9 +43,9 @@ import {
 import { formatMigrationApplyCommandOutput } from '../utils/formatters/migrations';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface MigrateCommandOptions extends CommonCommandOptions {
   readonly db?: string;
@@ -319,13 +319,10 @@ export function createMigrateCommand(): Command {
       'Target contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
     )
     .action(async (options: MigrateCommandOptions) => {
-      const flags = parseGlobalFlags(options);
+      const flags = parseGlobalFlagsOrExit(options);
       const startTime = Date.now();
 
-      const ui = new TerminalUI({
-        color: flags.color,
-        interactive: flags.interactive,
-      });
+      const ui = createTerminalUI(flags);
 
       const result = await executeMigrateCommand(options, flags, ui, startTime);
 

package/src/commands/migration-check.ts

@@ -17,8 +17,8 @@ import {
 } from '../utils/command-helpers';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
-import { TerminalUI } from '../utils/terminal-ui';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 import { INTEGRITY_FAILED, OK, PRECONDITION } from './migration-check/exit-codes';
 
 interface MigrationCheckOptions extends CommonCommandOptions {
@@ -335,8 +335,8 @@ export function createMigrationCheckCommand(): Command {
     .argument('[migration]', 'Migration reference (directory name or hash) to check')
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(async (target: string | undefined, options: MigrationCheckOptions) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
 
       let result: MigrationCheckResult;
       let exitCode: number;

package/src/commands/migration-graph.ts

@@ -23,10 +23,10 @@ import { migrationGraphToRenderInput } from '../utils/formatters/graph-migration
 import { graphRenderer } from '../utils/formatters/graph-render';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import type { StatusRef } from '../utils/migration-types';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface MigrationGraphOptions extends CommonCommandOptions {
   readonly config?: string;
@@ -130,8 +130,8 @@ export function createMigrationGraphCommand(): Command {
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .option('--dot', 'Output in Graphviz DOT format')
     .action(async (options: MigrationGraphOptions) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
       const result = await executeMigrationGraphCommand(options, flags, ui);
       const exitCode = handleResult(result, flags, ui, (graphResult) => {
         // Explicit format flags win over the auto-JSON default. `flags.json`

package/src/commands/migration-list.ts

@@ -20,9 +20,9 @@ import {
 } from '../utils/command-helpers';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface MigrationListOptions extends CommonCommandOptions {
   readonly config?: string;
@@ -130,8 +130,8 @@ export function createMigrationListCommand(): Command {
   addGlobalOptions(command)
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(async (options: MigrationListOptions) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
       const result = await executeMigrationListCommand(options, flags, ui);
       const exitCode = handleResult(result, flags, ui, (listResult) => {
         if (flags.json) {

package/src/commands/migration-log.ts

@@ -26,9 +26,9 @@ import {
 } from '../utils/command-helpers';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface MigrationLogOptions extends CommonCommandOptions {
   readonly db?: string;
@@ -193,8 +193,8 @@ export function createMigrationLogCommand(): Command {
     .option('--db <url>', 'Database connection string')
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(async (options: MigrationLogOptions) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
       const result = await executeMigrationLogCommand(options, flags, ui);
       const exitCode = handleResult(result, flags, ui, (logResult) => {
         if (flags.json) {

package/src/commands/migration-new.ts

@@ -49,9 +49,9 @@ import {
 import { formatStyledHeader } from '../utils/formatters/styled';
 import { assertFrameworkComponentsCompatible } from '../utils/framework-components';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { parseGlobalFlags } from '../utils/global-flags';
+import { parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI } from '../utils/terminal-ui';
 
 interface MigrationNewOptions extends CommonCommandOptions {
   readonly name?: string;
@@ -287,8 +287,8 @@ export function createMigrationNewCommand(): Command {
     .option('--from <hash>', 'Starting contract hash (default: latest migration target)')
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(async (options: MigrationNewOptions) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
 
       if (!flags.json && !flags.quiet) {
         const header = formatStyledHeader({

package/src/commands/migration-plan.ts

@@ -51,9 +51,9 @@ import { toExtensionInputs } from '../utils/extension-pack-inputs';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import { assertFrameworkComponentsCompatible } from '../utils/framework-components';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface MigrationPlanOptions extends CommonCommandOptions {
   readonly config?: string;
@@ -551,10 +551,10 @@ export function createMigrationPlanCommand(): Command {
       'Starting contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
     )
     .action(async (options: MigrationPlanOptions) => {
-      const flags = parseGlobalFlags(options);
+      const flags = parseGlobalFlagsOrExit(options);
       const startTime = Date.now();
 
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const ui = createTerminalUI(flags);
       const result = await executeMigrationPlanCommand(options, flags, ui, startTime);
 
       const exitCode = handleResult(result, flags, ui, (planResult) => {

package/src/commands/migration-show.ts

@@ -43,9 +43,9 @@ import { buildContractSpaceAggregate } from '../utils/contract-space-aggregate-l
 import { formatMigrationShowOutput } from '../utils/formatters/migrations';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface MigrationShowOptions extends CommonCommandOptions {
   readonly config?: string;
@@ -495,9 +495,9 @@ export function createMigrationShowCommand(): Command {
     )
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(async (target: string | undefined, options: MigrationShowOptions) => {
-      const flags = parseGlobalFlags(options);
+      const flags = parseGlobalFlagsOrExit(options);
 
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const ui = createTerminalUI(flags);
 
       const result = await executeMigrationShowCommand(target, options, flags, ui);
 

package/src/commands/migration-status.ts

@@ -65,10 +65,10 @@ import {
 } from '../utils/formatters/graph-render';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import type { StatusDiagnostic, StatusRef } from '../utils/migration-types';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface MigrationStatusOptions extends CommonCommandOptions {
   readonly db?: string;
@@ -1140,8 +1140,8 @@ export function createMigrationStatusCommand(): Command {
       'Origin contract reference; same grammar as --to. Supplying --from switches to offline path computation.',
     )
     .action(async (options: MigrationStatusOptions) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
 
       const result = await executeMigrationStatusCommand(options, flags, ui);
 

package/src/commands/ref.ts

@@ -25,9 +25,9 @@ import {
   setCommandDescriptions,
 } from '../utils/command-helpers';
 import { formatCommandHelp } from '../utils/formatters/help';
-import { parseGlobalFlags } from '../utils/global-flags';
+import { parseGlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI } from '../utils/terminal-ui';
 
 interface RefSetResult {
   readonly ok: true;
@@ -145,8 +145,8 @@ function createRefSetCommand(): Command {
         hash: string,
         options: { config?: string; json?: string | boolean; quiet?: boolean },
       ) => {
-        const flags = parseGlobalFlags(options);
-        const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+        const flags = parseGlobalFlagsOrExit(options);
+        const ui = createTerminalUI(flags);
         const result = await executeRefSetCommand(name, hash, options);
         const exitCode = handleResult(result, flags, ui, (value) => {
           if (flags.json) {
@@ -172,8 +172,8 @@ function createRefDeleteCommand(): Command {
         name: string,
         options: { config?: string; json?: string | boolean; quiet?: boolean },
       ) => {
-        const flags = parseGlobalFlags(options);
-        const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+        const flags = parseGlobalFlagsOrExit(options);
+        const ui = createTerminalUI(flags);
         const result = await executeRefDeleteCommand(name, options);
         const exitCode = handleResult(result, flags, ui, (value) => {
           if (flags.json) {
@@ -194,8 +194,8 @@ function createRefListCommand(): Command {
   addGlobalOptions(command)
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(async (options: { config?: string; json?: string | boolean; quiet?: boolean }) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
       const result = await executeRefListCommand(options);
       const exitCode = handleResult(result, flags, ui, (value) => {
         if (flags.json) {

package/src/utils/cli-errors.ts

@@ -16,9 +16,11 @@ import {
   errorDriverRequired,
   errorFamilyReadMarkerSqlRequired,
   errorFileNotFound,
+  errorInvalidOutputFormat,
   errorMigrationCliInvalidConfigArg,
   errorMigrationCliUnknownFlag,
   errorMigrationPlanningFailed,
+  errorOutputFormatMutex,
   errorQueryRunnerFactoryRequired,
   errorTargetMigrationNotSupported,
   errorUnexpected,
@@ -56,9 +58,11 @@ export {
   errorDriverRequired,
   errorFamilyReadMarkerSqlRequired,
   errorFileNotFound,
+  errorInvalidOutputFormat,
   errorMigrationCliInvalidConfigArg,
   errorMigrationCliUnknownFlag,
   errorMigrationPlanningFailed,
+  errorOutputFormatMutex,
   errorQueryRunnerFactoryRequired,
   errorTargetMigrationNotSupported,
   errorUnexpected,

package/src/utils/command-helpers.ts

@@ -365,7 +365,7 @@ export function sanitizeErrorMessage(message: string, connectionUrl?: string): s
 
 /**
  * Registers the global CLI options shared by every command:
- * --json, -q/--quiet, -v/--verbose, --trace, --color, --no-color,
+ * --format, --json, -q/--quiet, -v/--verbose, --trace, --color, --no-color,
  * --interactive, --no-interactive, -y/--yes.
  *
  * Also sets up the styled help formatter.
@@ -378,7 +378,11 @@ export function addGlobalOptions(command: Command): Command {
         return formatCommandHelp({ command: cmd, flags });
       },
     })
-    .option('--json', 'Output as JSON')
+    .option(
+      '--format <pretty|json>',
+      'Output format (default: pretty, or json when stdout is not a TTY)',
+    )
+    .option('--json', 'Output as JSON (alias for --format json)')
     .option('-q, --quiet', 'Quiet mode: errors only')
     .option('-v, --verbose', 'Verbose output: debug info, timings')
     .option('--trace', 'Trace output: deep internals, stack traces')

package/src/utils/global-flags.ts

@@ -1,9 +1,17 @@
+import { notOk } from '@prisma-next/utils/result';
+import { CliStructuredError, errorInvalidOutputFormat, errorOutputFormatMutex } from './cli-errors';
 import { isCI } from './is-ci';
+import { handleResult } from './result-handler';
+import { createTerminalUI } from './terminal-ui';
+
+export type OutputFormat = 'pretty' | 'json';
 
 export interface GlobalFlags {
+  readonly format: OutputFormat;
+  readonly explicitFormat: boolean;
   readonly json?: boolean;
   readonly quiet?: boolean;
-  readonly verbose?: number; // 0, 1, or 2
+  readonly verbose?: number;
   readonly color?: boolean;
   readonly interactive?: boolean;
   readonly yes?: boolean;
@@ -14,6 +22,7 @@ export interface GlobalFlags {
  * Extend this for command-specific options instead of duplicating these fields.
  */
 export interface CommonCommandOptions {
+  readonly format?: string;
   readonly json?: string | boolean;
   readonly quiet?: boolean;
   readonly q?: boolean;
@@ -28,33 +37,117 @@ export interface CommonCommandOptions {
   readonly y?: boolean;
 }
 
+function isJsonFlagSet(json: string | boolean | undefined): boolean {
+  return json === true;
+}
+
+interface ResolvedOutputFormat {
+  readonly format: OutputFormat;
+  readonly explicitFormat: boolean;
+}
+
+function resolveOutputFormat(options: CommonCommandOptions): ResolvedOutputFormat {
+  const formatOption = options.format;
+  const jsonFlag = isJsonFlagSet(options.json);
+
+  if (formatOption !== undefined) {
+    if (formatOption !== 'pretty' && formatOption !== 'json') {
+      throw errorInvalidOutputFormat(formatOption);
+    }
+    if (jsonFlag && formatOption === 'pretty') {
+      throw errorOutputFormatMutex();
+    }
+    return { format: formatOption, explicitFormat: true };
+  }
+
+  if (jsonFlag) {
+    return { format: 'json', explicitFormat: false };
+  }
+
+  if (!process.stdout.isTTY) {
+    return { format: 'json', explicitFormat: false };
+  }
+
+  return { format: 'pretty', explicitFormat: false };
+}
+
+function inferJsonModeForParseError(options: CommonCommandOptions): boolean {
+  if (options.format === 'json') {
+    return true;
+  }
+  if (isJsonFlagSet(options.json) && options.format !== 'pretty') {
+    return true;
+  }
+  if (options.format !== undefined) {
+    return false;
+  }
+  return !process.stdout.isTTY;
+}
+
+function emitGlobalFlagParseError(error: CliStructuredError, options: CommonCommandOptions): never {
+  const jsonMode = inferJsonModeForParseError(options);
+  const flags: GlobalFlags = {
+    format: jsonMode ? 'json' : 'pretty',
+    explicitFormat: false,
+    ...(jsonMode ? { json: true } : {}),
+    color: false,
+    verbose: 0,
+    interactive: false,
+  };
+  const ui = createTerminalUI(flags);
+  const exitCode = handleResult(notOk(error), flags, ui);
+  process.exit(exitCode);
+}
+
+/**
+ * Parses global flags from CLI options.
+ * Handles verbosity flags (-v, --trace), output format (--format, --json),
+ * quiet mode, color, interactivity (--interactive/--no-interactive), and
+ * auto-accept (-y/--yes).
+ *
+ * On invalid or conflicting format flags, prints a structured CLI error
+ * envelope and exits with code 2.
+ */
+export function parseGlobalFlagsOrExit(options: CommonCommandOptions): GlobalFlags {
+  try {
+    return parseGlobalFlags(options);
+  } catch (error) {
+    if (CliStructuredError.is(error)) {
+      emitGlobalFlagParseError(error, options);
+    }
+    throw error;
+  }
+}
+
 /**
  * Parses global flags from CLI options.
- * Handles verbosity flags (-v, --trace), JSON output, quiet mode, color,
- * interactivity (--interactive/--no-interactive), and auto-accept (-y/--yes).
+ * Handles verbosity flags (-v, --trace), output format (--format, --json),
+ * quiet mode, color, interactivity (--interactive/--no-interactive), and
+ * auto-accept (-y/--yes).
+ *
+ * Throws {@link CliStructuredError} for invalid or conflicting format flags.
  */
 export function parseGlobalFlags(options: CommonCommandOptions): GlobalFlags {
+  const { format, explicitFormat } = resolveOutputFormat(options);
   const flags: {
+    format: OutputFormat;
+    explicitFormat: boolean;
     json?: boolean;
     quiet?: boolean;
     verbose?: number;
     color?: boolean;
     interactive?: boolean;
     yes?: boolean;
-  } = {};
+  } = { format, explicitFormat };
 
-  // JSON output: explicit --json flag or auto-detect piped stdout (Unix convention)
-  if (options.json || !process.stdout.isTTY) {
+  if (format === 'json') {
     flags.json = true;
   }
 
-  // Quiet mode
   if (options.quiet || options.q) {
     flags.quiet = true;
   }
 
-  // Verbosity: -v = 1, --trace = 2
-  // Env toggles: PRISMA_NEXT_TRACE=1 ≅ --trace, PRISMA_NEXT_DEBUG=1 ≅ -v
   if (options.trace || process.env['PRISMA_NEXT_TRACE'] === '1') {
     flags.verbose = 2;
   } else if (options.verbose || options.v || process.env['PRISMA_NEXT_DEBUG'] === '1') {
@@ -63,8 +156,6 @@ export function parseGlobalFlags(options: CommonCommandOptions): GlobalFlags {
     flags.verbose = 0;
   }
 
-  // Color: respect NO_COLOR env var, --color/--no-color flags
-  // When JSON output is enabled, disable color to ensure clean JSON output
   if (process.env['NO_COLOR'] || flags.json) {
     flags.color = false;
   } else if (options['no-color']) {
@@ -72,14 +163,9 @@ export function parseGlobalFlags(options: CommonCommandOptions): GlobalFlags {
   } else if (options.color !== undefined) {
     flags.color = options.color;
   } else {
-    // Default: enable color if TTY and not in CI. Uses the consolidated
-    // `isCI()` helper (`./is-ci.ts`) — the single source of truth shared
-    // with telemetry-skip detection.
     flags.color = process.stdout.isTTY && !isCI();
   }
 
-  // Interactivity: --interactive/--no-interactive
-  // Default: interactive when stdout is a TTY
   if (options['no-interactive']) {
     flags.interactive = false;
   } else if (options.interactive !== undefined) {
@@ -88,7 +174,6 @@ export function parseGlobalFlags(options: CommonCommandOptions): GlobalFlags {
     flags.interactive = !!process.stdout.isTTY;
   }
 
-  // Auto-accept prompts: -y/--yes
   if (options.yes || options.y) {
     flags.yes = true;
   }