Add JSON schema flag to commands

Author: gonzaloriestra

.changeset/quiet-json-schema-help.md

@@ -0,0 +1,6 @@
+---
+'@shopify/cli-kit': minor
+'@shopify/cli': minor
+---
+
+Show JSON Schema in command help and use `--json-schema` to print result, error, and event schemas.

docs-shopify.dev/generated/generated_docs_data_v2.json

@@ -14,7 +14,7 @@ commands; remove each entry when converted, and never add new finite commands to
 ## Define the result beside the domain service
 
 Keep the schema beside the service that produces the result. One Zod schema supplies runtime validation, the inferred
-TypeScript type, JSON encoding, and the type shown in command help.
+TypeScript type, JSON encoding, and the JSON Schema shown in command help.
 
 ```ts
 import {defineJsonOutputSchema, type InferJsonOutputSchema} from '@shopify/cli-kit/node/json-output-schema'
@@ -34,8 +34,8 @@ export const widgetListJsonOutputSchema = defineJsonOutputSchema({
 export type WidgetListResult = InferJsonOutputSchema<typeof widgetListJsonOutputSchema>
 ```
 
-Add nested object schemas to `definitions` so generated help gives them stable names. Use `.passthrough()` only when
-the public result deliberately permits additional keys.
+Optionally add nested object schemas to `definitions` to give them stable names and references in JSON Schema.
+Use `.passthrough()` only when the public result deliberately permits additional keys.
 
 ## Connect the command and encoder
 
@@ -75,8 +75,8 @@ Presenters continue to own terminal text, output channels, files, and exit behav
 on terminal rendering (including React/Ink), Oclif, filesystem output, or CLI errors.
 
 Events are separate from finite results. Progress events can drive spinners or status messages while the command is
-running, but they aren't fields in the final JSON result. Errors continue through the standard CLI error path and
-stderr; don't encode failures as successful result shapes merely to support `--json`.
+running, but they aren't fields in the final JSON result. Errors continue through the standard CLI error path;
+don't encode failures as successful result shapes merely to support `--json`.
 
 ## Preserve compatibility
 
@@ -104,6 +104,22 @@ The lint rule only exempts paths in that list; a `jsonOutputSupport` property al
 This exemption is only for commands whose lifetime or output is inherently streaming. A finite operation remains a
 finite command even when it emits progress events, writes a file, or has no interesting return value.
 
+## Plugin authors
+
+Plugins must adopt the result contract and control their output before their commands can be used reliably in JSON
+mode. Inheriting `--json-schema` or enabling `SHOPIFY_FLAG_JSON=1` doesn't convert all plugin output automatically.
+
+- Oclif `init` hooks run before the command's error handling. A hook that renders a warning and calls `process.exit(1)`
+  bypasses the JSON fatal error path and can leave stdout empty. Put command validation in the command lifecycle and
+  throw an `AbortError` so CLI Kit can encode the failure.
+- In the command event context, `outputInfo`, `outputWarn`, and `outputDebug` use diagnostic events in JSON mode when
+  using their default logger. Banners such as `renderSuccess` and `renderWarning` still render terminal text to stderr;
+  they aren't automatically converted to events. Use `emitCommandEvent` from `@shopify/cli-kit/node/command-events`
+  for diagnostics, and keep human-only banners in the text presenter.
+- Third-party loggers and child processes aren't automatically converted or silenced. Use `jsonOutputEnabled()` from
+  `@shopify/cli-kit/node/environment` to silence or capture their output in JSON mode. Reserve stdout for the encoded
+  result or fatal error document, and send diagnostics through the event helpers to stderr.
+
 ## Test a new command
 
 Tests should verify:
@@ -115,5 +131,9 @@ Tests should verify:
 - errors and exit behavior; and
 - prompt behavior independently from `--json` and `--no-input`.
 
-Command help includes the generated TypeScript contract automatically through `jsonOutputSchema`. Run the manifest,
+Command help includes the result's JSON Schema automatically through `jsonOutputSchema`. `--json-schema` prints one
+JSON Schema (draft-07) accepting a result, a fatal error document, or a side event. The `Result`, `Error`, and `Event`
+definitions describe these separately; results and fatal errors go to stdout, and side events go to stderr.
+
+Both outputs come from the same Zod definitions used to validate and encode results. Run the manifest,
 README, and code-documentation refresh commands required by CI after changing command metadata.

docs/cli/json-output.md

@@ -3,7 +3,7 @@ import {authAliasFlag, globalFlags, jsonFlag} from '@shopify/cli-kit/node/cli'
 import BaseCommand from '@shopify/cli-kit/node/base-command'
 
 export default class OrganizationList extends BaseCommand {
-  static baseFlags = authAliasFlag
+  static baseFlags = {...BaseCommand.baseFlags, ...authAliasFlag}
 
   static summary = 'List Shopify organizations you have access to.'
 

packages/app/src/cli/commands/organization/list.ts

@@ -8,7 +8,7 @@ interface AppCommandOutput {
 }
 
 export default abstract class AppCommand extends BaseCommand {
-  static baseFlags = authAliasFlag
+  static baseFlags = {...BaseCommand.baseFlags, ...authAliasFlag}
 
   environmentsFilename(): string {
     return configurationFileNames.appEnvironments

packages/app/src/cli/utilities/app-command.ts

@@ -154,7 +154,8 @@
     "strip-ansi": "7.2.0",
     "supports-hyperlinks": "3.2.0",
     "which": "4.0.0",
-    "zod": "3.25.76"
+    "zod": "3.25.76",
+    "zod-to-json-schema": "3.25.2"
   },
   "devDependencies": {
     "@types/archiver": "5.3.2",

packages/cli-kit/package.json

@@ -0,0 +1,44 @@
+import {AbortError} from '../../public/node/error.js'
+import {commandEventOutputSchema} from '../../public/node/command-events.js'
+import {jsonErrorOutputSchema} from '../../public/node/error/schema.js'
+import {defineJsonOutputSchema, type JsonOutputSchema} from '../../public/node/json-output-schema.js'
+import {flushStdout, outputResult} from '../../public/node/output.js'
+import {zod} from '../../public/node/schema.js'
+import {normalizeArgv} from '@oclif/core/help'
+import type {LazyCommandLoader} from '../../public/node/custom-oclif-loader.js'
+import type {Config} from '@oclif/core'
+
+/**
+ * Loads a command's schema without running its lifecycle or Oclif hooks.
+ *
+ * @param config - The loaded CLI configuration.
+ * @param argv - The CLI arguments, including the command name.
+ * @param lazyCommandLoader - The optional loader for bundled commands.
+ */
+export async function printCommandJsonSchema(
+  config: Config,
+  argv: string[],
+  lazyCommandLoader?: LazyCommandLoader,
+): Promise<void> {
+  const [id] = normalizeArgv(config, argv)
+  if (!id || id.startsWith('-')) throw new AbortError('Specify a command to inspect its JSON output schema.')
+
+  const command = config.findCommand(id)
+  if (!command) throw new AbortError(`Command "${id}" not found.`)
+
+  const commandClass = (await lazyCommandLoader?.(command.id)) ?? (await command.load())
+  const outputSchema = (commandClass as typeof commandClass & {jsonOutputSchema?: JsonOutputSchema}).jsonOutputSchema
+  if (!outputSchema) throw new AbortError('This command does not define a JSON output schema.')
+
+  const commandSchema = defineJsonOutputSchema({
+    name: 'CommandOutput',
+    schema: zod.union([outputSchema.schema, jsonErrorOutputSchema.schema, commandEventOutputSchema.schema]),
+    definitions: {
+      Result: outputSchema.schema,
+      Error: jsonErrorOutputSchema.schema,
+      Event: commandEventOutputSchema.schema,
+    },
+  })
+  outputResult(JSON.stringify(commandSchema.jsonSchema, null, 2))
+  await flushStdout()
+}

packages/cli-kit/src/private/node/command-json-schema.ts

@@ -11,6 +11,7 @@ import {defineJsonOutputSchema} from './json-output-schema.js'
 import {zod} from './schema.js'
 import {afterEach, beforeEach, describe, expect, test, vi} from 'vitest'
 import {Flags} from '@oclif/core'
+import {Ajv} from 'ajv'
 
 let originalStdinIsTTY: boolean | undefined
 let originalStdoutIsTTY: boolean | undefined
@@ -285,6 +286,20 @@ describe('command events', () => {
 })
 
 describe('command descriptions', () => {
+  test('preserves schema patterns that resemble Markdown links', () => {
+    class CommandWithPattern extends Command {
+      static get jsonOutputSchema() {
+        return defineJsonOutputSchema({name: 'Result', schema: zod.string().regex(/[a-z](value)/)})
+      }
+
+      public async run(): Promise<void> {}
+    }
+
+    const description = CommandWithPattern.descriptionForHelp()!
+    const schema = JSON.parse(description.match(/```json\n([\s\S]+)\n```/)![1]!)
+    expect(schema.pattern).toBe('[a-z](value)')
+  })
+
   test('includes a JSON output schema without mutating the Markdown description', () => {
     class CommandWithJsonOutput extends Command {
       static get jsonOutputSchema() {
@@ -301,15 +316,22 @@ describe('command descriptions', () => {
       public async run(): Promise<void> {}
     }
 
-    expect(CommandWithJsonOutput.description).toBe(`Returns a value. "Learn more" (https://shopify.dev).
-
-With \`--json\`, the command returns \`CommandResult\`:
-
-\`\`\`ts
-interface CommandResult {
-  value: string
-}
-\`\`\``)
+    expect(CommandWithJsonOutput.description).toContain('Returns a value. "Learn more" (https://shopify.dev).')
+    expect(CommandWithJsonOutput.description).toContain(
+      'Use `--json-schema` to print the result, error, and event schemas.',
+    )
+    const helpSchema = JSON.parse(CommandWithJsonOutput.description!.match(/```json\n([\s\S]+)\n```/)![1]!)
+    expect(helpSchema).toEqual({
+      $schema: 'http://json-schema.org/draft-07/schema#',
+      title: 'CommandResult',
+      type: 'object',
+      properties: {value: {type: 'string'}},
+      required: ['value'],
+      additionalProperties: false,
+    })
+    const validate = new Ajv().compile(helpSchema)
+    expect(validate({value: 'ready'})).toBe(true)
+    expect(validate({value: 1})).toBe(false)
     expect(CommandWithJsonOutput.descriptionWithMarkdown).toBe('Returns a value. [Learn more](https://shopify.dev).')
 
     CommandWithJsonOutput.descriptionForHelp()

packages/cli-kit/src/public/node/base-command.test.ts

@@ -8,11 +8,11 @@ import {terminalSupportsPrompting} from './system.js'
 import {hashString} from './crypto.js'
 import {isTruthy} from './context/utilities.js'
 import {setCurrentCommandId} from './global-context.js'
+import {type JsonOutputSchema} from './json-output-schema.js'
 import {JsonMap} from '../../private/common/json.js'
 import {underscore} from '../common/string.js'
-import {Command, Config, Errors} from '@oclif/core'
+import {Command, Config, Errors, Flags} from '@oclif/core'
 import {OutputFlags, Input, ParserOutput, FlagInput, OutputArgs} from '@oclif/core/parser'
-import type {JsonOutputSchema} from './json-output-schema.js'
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type ArgOutput = OutputArgs<any>
@@ -33,7 +33,13 @@ interface EnvironmentFlags {
 }
 
 abstract class BaseCommand extends Command {
-  static baseFlags: FlagInput<{}> = {}
+  static baseFlags: FlagInput<{}> = {
+    'json-schema': Flags.boolean({
+      description: "Print the command's JSON schemas.",
+      env: 'SHOPIFY_FLAG_JSON_SCHEMA',
+    }),
+  }
+
   static descriptionWithMarkdown?: string
 
   public static get jsonOutputSchema(): JsonOutputSchema | undefined {
@@ -50,10 +56,8 @@ abstract class BaseCommand extends Command {
 
   // Include the JSON result schema and convert Markdown links to plain text for command help.
   public static descriptionForHelp(): string | undefined {
-    return appendJsonOutputSchema(this.descriptionWithMarkdown ?? '', this.jsonOutputSchema).replace(
-      /(\[)(.*?)(])(\()(.*?)(\))/gm,
-      '"$2" ($5)',
-    )
+    const description = (this.descriptionWithMarkdown ?? '').replace(/(\[)(.*?)(])(\()(.*?)(\))/gm, '"$2" ($5)')
+    return appendJsonOutputSchema(description, this.jsonOutputSchema)
   }
 
   /** @deprecated Use descriptionForHelp instead. */
@@ -413,10 +417,12 @@ function commandSupportsFlag(flags: FlagInput | undefined, flagName: string): bo
 function appendJsonOutputSchema(description: string, outputSchema: JsonOutputSchema | undefined): string {
   if (!outputSchema) return description
 
-  const jsonOutputDescription = `With \`--json\`, the command returns \`${outputSchema.name}\`:
+  const jsonOutputDescription = `Output from \`--json\` conforms to the \`${outputSchema.name}\` schema.
+
+Use \`--json-schema\` to print the result, error, and event schemas.
 
-\`\`\`ts
-${outputSchema.typescript}
+\`\`\`json
+${JSON.stringify(outputSchema.jsonSchema, null, 2)}
 \`\`\``
 
   return [description, jsonOutputDescription].filter(Boolean).join('\n\n')