Add typed JSON output to app dev

.changeset/bright-dev-stream.md

@@ -0,0 +1,5 @@
+---
+'@shopify/cli': minor
+---
+
+Add `app dev --json` streaming and expose session-file schemas with `--json-schema`.

docs-shopify.dev/generated/generated_docs_data_v2.json

@@ -1402,6 +1402,15 @@
           "isOptional": true,
           "environmentValue": "SHOPIFY_FLAG_APP_CONFIG"
         },
+        {
+          "filePath": "docs-shopify.dev/commands/interfaces/app-dev.interface.ts",
+          "syntaxKind": "PropertySignature",
+          "name": "-j, --json",
+          "value": "''",
+          "description": "Output the result as JSON. Automatically disables color output.",
+          "isOptional": true,
+          "environmentValue": "SHOPIFY_FLAG_JSON"
+        },
         {
           "filePath": "docs-shopify.dev/commands/interfaces/app-dev.interface.ts",
           "syntaxKind": "PropertySignature",
@@ -1421,7 +1430,7 @@
           "environmentValue": "SHOPIFY_FLAG_THEME"
         }
       ],
-      "value": "export interface appdev {\n  /**\n   * Alias of the Shopify account to use for authentication.\n   * @environment SHOPIFY_FLAG_AUTH_ALIAS\n   */\n  '--auth-alias <value>'?: string\n\n  /**\n   * Resource URL for checkout UI extension. Format: \"/cart/{productVariantID}:{productQuantity}\"\n   * @environment SHOPIFY_FLAG_CHECKOUT_CART_URL\n   */\n  '--checkout-cart-url <value>'?: string\n\n  /**\n   * The Client ID of your app. Use with --config to run dev with that configuration for a different app than the one it is linked to.\n   * @environment SHOPIFY_FLAG_CLIENT_ID\n   */\n  '--client-id <value>'?: string\n\n  /**\n   * The name of the app configuration.\n   * @environment SHOPIFY_FLAG_APP_CONFIG\n   */\n  '-c, --config <value>'?: string\n\n  /**\n   * Install and use mkcert to generate localhost certificates when --use-localhost is enabled without prompting.\n   * @environment SHOPIFY_FLAG_INSTALL_MKCERT\n   */\n  '--install-mkcert'?: ''\n\n  /**\n   * Print the command's JSON schemas.\n   * @environment SHOPIFY_FLAG_JSON_SCHEMA\n   */\n  '--json-schema'?: ''\n\n  /**\n   * Port to use for localhost. Must be between 1 and 65535.\n   * @environment SHOPIFY_FLAG_LOCALHOST_PORT\n   */\n  '--localhost-port <value>'?: string\n\n  /**\n   * Disable color output.\n   * @environment SHOPIFY_FLAG_NO_COLOR\n   */\n  '--no-color'?: ''\n\n  /**\n   * Disable interactive prompts and browser authentication.\n   * @environment SHOPIFY_FLAG_NO_INPUT\n   */\n  '--no-input'?: ''\n\n  /**\n   * Uses the app URL from the toml file instead an autogenerated URL for dev.\n   * @environment SHOPIFY_FLAG_NO_UPDATE\n   */\n  '--no-update'?: ''\n\n  /**\n   * The file path or URL. The file path is to a file that you want updated on idle. The URL path is where you want a webhook posted to report on file changes.\n   * @environment SHOPIFY_FLAG_NOTIFY\n   */\n  '--notify <value>'?: string\n\n  /**\n   * The path to your app directory.\n   * @environment SHOPIFY_FLAG_PATH\n   */\n  '--path <value>'?: string\n\n  /**\n   * Reset all your settings.\n   * @environment SHOPIFY_FLAG_RESET\n   */\n  '--reset'?: ''\n\n  /**\n   * Skips the installation of dependencies. Deprecated, use workspaces instead.\n   * @environment SHOPIFY_FLAG_SKIP_DEPENDENCIES_INSTALLATION\n   */\n  '--skip-dependencies-installation'?: ''\n\n  /**\n   * Store URL. Must be an existing development or Shopify Plus sandbox store.\n   * @environment SHOPIFY_FLAG_STORE\n   */\n  '-s, --store <value>'?: string\n\n  /**\n   * The password for storefronts with password protection.\n   * @environment SHOPIFY_FLAG_STORE_PASSWORD\n   */\n  '--store-password <value>'?: string\n\n  /**\n   * Resource URL for subscription UI extension. Format: \"/products/{productId}\"\n   * @environment SHOPIFY_FLAG_SUBSCRIPTION_PRODUCT_URL\n   */\n  '--subscription-product-url <value>'?: string\n\n  /**\n   * Theme ID or name of the theme app extension host theme.\n   * @environment SHOPIFY_FLAG_THEME\n   */\n  '-t, --theme <value>'?: string\n\n  /**\n   * Local port of the theme app extension development server. Must be between 1 and 65535.\n   * @environment SHOPIFY_FLAG_THEME_APP_EXTENSION_PORT\n   */\n  '--theme-app-extension-port <value>'?: string\n\n  /**\n   * Use a custom tunnel, it must be running before executing dev. Format: \"https://my-tunnel-url:port\".\n   * @environment SHOPIFY_FLAG_TUNNEL_URL\n   */\n  '--tunnel-url <value>'?: string\n\n  /**\n   * Allow app dev to continue with warnings for eligible app version validation failures.\n   * @environment SHOPIFY_FLAG_UNSAFE_VALIDATION\n   */\n  '--unsafe-validation'?: ''\n\n  /**\n   * Service entry point will listen to localhost. A tunnel won't be used. Will work for testing many app features, but not those that directly invoke your app (E.g: Webhooks)\n   * @environment SHOPIFY_FLAG_USE_LOCALHOST\n   */\n  '--use-localhost'?: ''\n\n  /**\n   * Increase the verbosity of the output. May include sensitive data.\n   * @environment SHOPIFY_FLAG_VERBOSE\n   */\n  '--verbose'?: ''\n}"
+      "value": "export interface appdev {\n  /**\n   * Alias of the Shopify account to use for authentication.\n   * @environment SHOPIFY_FLAG_AUTH_ALIAS\n   */\n  '--auth-alias <value>'?: string\n\n  /**\n   * Resource URL for checkout UI extension. Format: \"/cart/{productVariantID}:{productQuantity}\"\n   * @environment SHOPIFY_FLAG_CHECKOUT_CART_URL\n   */\n  '--checkout-cart-url <value>'?: string\n\n  /**\n   * The Client ID of your app. Use with --config to run dev with that configuration for a different app than the one it is linked to.\n   * @environment SHOPIFY_FLAG_CLIENT_ID\n   */\n  '--client-id <value>'?: string\n\n  /**\n   * The name of the app configuration.\n   * @environment SHOPIFY_FLAG_APP_CONFIG\n   */\n  '-c, --config <value>'?: string\n\n  /**\n   * Install and use mkcert to generate localhost certificates when --use-localhost is enabled without prompting.\n   * @environment SHOPIFY_FLAG_INSTALL_MKCERT\n   */\n  '--install-mkcert'?: ''\n\n  /**\n   * Output the result as JSON. Automatically disables color output.\n   * @environment SHOPIFY_FLAG_JSON\n   */\n  '-j, --json'?: ''\n\n  /**\n   * Print the command's JSON schemas.\n   * @environment SHOPIFY_FLAG_JSON_SCHEMA\n   */\n  '--json-schema'?: ''\n\n  /**\n   * Port to use for localhost. Must be between 1 and 65535.\n   * @environment SHOPIFY_FLAG_LOCALHOST_PORT\n   */\n  '--localhost-port <value>'?: string\n\n  /**\n   * Disable color output.\n   * @environment SHOPIFY_FLAG_NO_COLOR\n   */\n  '--no-color'?: ''\n\n  /**\n   * Disable interactive prompts and browser authentication.\n   * @environment SHOPIFY_FLAG_NO_INPUT\n   */\n  '--no-input'?: ''\n\n  /**\n   * Uses the app URL from the toml file instead an autogenerated URL for dev.\n   * @environment SHOPIFY_FLAG_NO_UPDATE\n   */\n  '--no-update'?: ''\n\n  /**\n   * The file path or URL. The file path is to a file that you want updated on idle. The URL path is where you want a webhook posted to report on file changes.\n   * @environment SHOPIFY_FLAG_NOTIFY\n   */\n  '--notify <value>'?: string\n\n  /**\n   * The path to your app directory.\n   * @environment SHOPIFY_FLAG_PATH\n   */\n  '--path <value>'?: string\n\n  /**\n   * Reset all your settings.\n   * @environment SHOPIFY_FLAG_RESET\n   */\n  '--reset'?: ''\n\n  /**\n   * Skips the installation of dependencies. Deprecated, use workspaces instead.\n   * @environment SHOPIFY_FLAG_SKIP_DEPENDENCIES_INSTALLATION\n   */\n  '--skip-dependencies-installation'?: ''\n\n  /**\n   * Store URL. Must be an existing development or Shopify Plus sandbox store.\n   * @environment SHOPIFY_FLAG_STORE\n   */\n  '-s, --store <value>'?: string\n\n  /**\n   * The password for storefronts with password protection.\n   * @environment SHOPIFY_FLAG_STORE_PASSWORD\n   */\n  '--store-password <value>'?: string\n\n  /**\n   * Resource URL for subscription UI extension. Format: \"/products/{productId}\"\n   * @environment SHOPIFY_FLAG_SUBSCRIPTION_PRODUCT_URL\n   */\n  '--subscription-product-url <value>'?: string\n\n  /**\n   * Theme ID or name of the theme app extension host theme.\n   * @environment SHOPIFY_FLAG_THEME\n   */\n  '-t, --theme <value>'?: string\n\n  /**\n   * Local port of the theme app extension development server. Must be between 1 and 65535.\n   * @environment SHOPIFY_FLAG_THEME_APP_EXTENSION_PORT\n   */\n  '--theme-app-extension-port <value>'?: string\n\n  /**\n   * Use a custom tunnel, it must be running before executing dev. Format: \"https://my-tunnel-url:port\".\n   * @environment SHOPIFY_FLAG_TUNNEL_URL\n   */\n  '--tunnel-url <value>'?: string\n\n  /**\n   * Allow app dev to continue with warnings for eligible app version validation failures.\n   * @environment SHOPIFY_FLAG_UNSAFE_VALIDATION\n   */\n  '--unsafe-validation'?: ''\n\n  /**\n   * Service entry point will listen to localhost. A tunnel won't be used. Will work for testing many app features, but not those that directly invoke your app (E.g: Webhooks)\n   * @environment SHOPIFY_FLAG_USE_LOCALHOST\n   */\n  '--use-localhost'?: ''\n\n  /**\n   * Increase the verbosity of the output. May include sensitive data.\n   * @environment SHOPIFY_FLAG_VERBOSE\n   */\n  '--verbose'?: ''\n}"
     }
   },
   "appenvpull": {

docs/cli/dev-instance-agent-workflow.md

@@ -53,12 +53,18 @@ of commits and external reports; output and local URLs can contain secrets.
 ## App dev
 
 `shopify app dev` owns one session per app configuration. The instance details
-include the app configuration, app identity, store, URLs, and `preview`:
+include the app configuration, app identity, store, URLs, and `preview`.
 
-- `state`: `starting`, `updating`, `ready`, or `error`.
-- `message`: the current CLI status message, or `null` before one is available.
-- `errors`: the current reported errors. Errors remain during retries and clear
-  when the CLI reports success.
+Use `shopify app dev --json-schema` to inspect the contract. `definitions.DevInstance`
+describes the saved instance JSON, and `definitions.DevPreview` describes
+`details.preview`. `definitions.Result` describes each JSONL stream record.
+The instance metadata is stored in the file; it is not added to the JSONL stream.
+Preview errors remain during retries and clear when the CLI reports success.
 
 Process messages keep their terminal source, including extension handles.
 Changes to the status message also produce a log record with source `app dev`.
+
+With `--json`, dev stream records use identical JSONL bytes in stdout and the session
+log. The log contains process output, preview URLs, and session status messages.
+CLI setup messages and other diagnostics use stderr. Fatal CLI errors use the
+standard JSON error output on stdout and are not added to the session log.

docs/cli/json-output.md

@@ -240,6 +240,23 @@ events from stderr; missing required input then produces a fatal error instead o
 
 ## Exempt only streaming commands
 
+`shopify app dev --json` writes dev stream records as identical JSONL bytes to stdout and the session log. Each record
+has `timestamp`, `source`, and `message`, with `level` when available. The log contains process output, preview URLs,
+and session status messages. There is no final success result. Preview errors remain log records so that the
+developer can fix the app while dev keeps running.
+
+CLI setup messages and other diagnostics use stderr. Fatal CLI failures use the standard `{error: {...}}` envelope
+on stdout and exit nonzero. These failures are not added to the session log. A second invocation that cannot acquire
+the session never changes the running process's log.
+
+```jsonl
+{"timestamp":"2026-10-20T09:00:00Z","source":"web","message":"Server listening on 3000"}
+{"timestamp":"2026-10-20T09:00:01Z","source":"app dev","level":"info","message":"Ready, watching for changes in your app"}
+```
+
+Setup prompts still use stderr. Use `--json --no-input` for unattended runs. `app dev --json-schema` describes the
+stream's event and fatal error formats. This streaming contract does not change the single-document rule for finite commands.
+
 Long-lived commands that produce an open-ended event stream don't have one finite result. Track these exemptions in
 `packages/eslint-plugin-cli/rules/json-output-command-exceptions.js`, in its streaming section. Add the command's
 repository-relative path: