Add --output flag and drop --content-type from fetch-doc

- `--output <path>` (`-o`) writes the document to a file (creating any
  missing parent directories) instead of printing to stdout.
- Remove the `--content-type` flag: fetch-doc now always requests the
  Markdown representation. Returning HTML is noisy and expensive and not
  a behavior we want to encourage.
- Regenerate oclif manifest, README, and shopify.dev docs.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: nelsonwittwer

.changeset/add-fetch-doc-command.md

@@ -2,4 +2,4 @@
 '@shopify/cli': minor
 ---
 
-Add a `shopify fetch-doc` command that downloads a document from shopify.dev and prints it to stdout. It requests the Markdown representation by default (overridable with `--content-type`), giving agents an easy way to pull instructional content from the centralized docs.
+Add a `shopify fetch-doc` command that downloads a document from shopify.dev and prints it to stdout, or writes it to a file with `--output`. It requests the Markdown representation that every shopify.dev page has, giving agents an easy way to pull instructional content from the centralized docs verbatim.

docs-shopify.dev/commands/interfaces/fetch-doc.interface.ts

@@ -4,18 +4,18 @@
  * @publicDocs
  */
 export interface fetchdoc {
-  /**
-   * The Accept content type to request (defaults to text/markdown).
-   * @environment SHOPIFY_FLAG_CONTENT_TYPE
-   */
-  '--content-type <value>'?: string
-
   /**
    * Disable color output.
    * @environment SHOPIFY_FLAG_NO_COLOR
    */
   '--no-color'?: ''
 
+  /**
+   * Write the document to this file path instead of printing it to stdout.
+   * @environment SHOPIFY_FLAG_OUTPUT
+   */
+  '-o, --output <value>'?: string
+
   /**
    * Increase the verbosity of the output.
    * @environment SHOPIFY_FLAG_VERBOSE

docs-shopify.dev/generated/generated_docs_data_v2.json

@@ -2749,15 +2749,6 @@
       "description": "The following flags are available for the `fetch-doc` command:",
       "isPublicDocs": true,
       "members": [
-        {
-          "filePath": "docs-shopify.dev/commands/interfaces/fetch-doc.interface.ts",
-          "syntaxKind": "PropertySignature",
-          "name": "--content-type <value>",
-          "value": "string",
-          "description": "The Accept content type to request (defaults to text/markdown).",
-          "isOptional": true,
-          "environmentValue": "SHOPIFY_FLAG_CONTENT_TYPE"
-        },
         {
           "filePath": "docs-shopify.dev/commands/interfaces/fetch-doc.interface.ts",
           "syntaxKind": "PropertySignature",
@@ -2775,9 +2766,18 @@
           "description": "Increase the verbosity of the output.",
           "isOptional": true,
           "environmentValue": "SHOPIFY_FLAG_VERBOSE"
+        },
+        {
+          "filePath": "docs-shopify.dev/commands/interfaces/fetch-doc.interface.ts",
+          "syntaxKind": "PropertySignature",
+          "name": "-o, --output <value>",
+          "value": "string",
+          "description": "Write the document to this file path instead of printing it to stdout.",
+          "isOptional": true,
+          "environmentValue": "SHOPIFY_FLAG_OUTPUT"
         }
       ],
-      "value": "export interface fetchdoc {\n  /**\n   * The Accept content type to request (defaults to text/markdown).\n   * @environment SHOPIFY_FLAG_CONTENT_TYPE\n   */\n  '--content-type <value>'?: string\n\n  /**\n   * Disable color output.\n   * @environment SHOPIFY_FLAG_NO_COLOR\n   */\n  '--no-color'?: ''\n\n  /**\n   * Increase the verbosity of the output.\n   * @environment SHOPIFY_FLAG_VERBOSE\n   */\n  '--verbose'?: ''\n}"
+      "value": "export interface fetchdoc {\n  /**\n   * Disable color output.\n   * @environment SHOPIFY_FLAG_NO_COLOR\n   */\n  '--no-color'?: ''\n\n  /**\n   * Write the document to this file path instead of printing it to stdout.\n   * @environment SHOPIFY_FLAG_OUTPUT\n   */\n  '-o, --output <value>'?: string\n\n  /**\n   * Increase the verbosity of the output.\n   * @environment SHOPIFY_FLAG_VERBOSE\n   */\n  '--verbose'?: ''\n}"
     }
   },
   "help": {

packages/cli/README.md

@@ -1215,7 +1215,7 @@ DESCRIPTION
 
 ## `shopify fetch-doc [URL]`
 
-Download a complete document from shopify.dev. Every page on shopify.dev has a Markdown version, and that is what this tool returns by default. Use this to pull an entire document verbatim — for example, a set of instructions an agent follows like a centrally-served skill. For finding the relevant pieces of content across shopify.dev instead, use `search`.
+Download a complete document from shopify.dev. Every page on shopify.dev has a Markdown version, and that is what this tool returns. Use this to pull an entire document verbatim — for example, a set of instructions an agent follows like a centrally-served skill. For finding the relevant pieces of content across shopify.dev instead, use `search`.
 
 ```
 USAGE
@@ -1225,22 +1225,24 @@ ARGUMENTS
   URL  The shopify.dev URL to fetch.
 
 FLAGS
-  --content-type=<value>  [env: SHOPIFY_FLAG_CONTENT_TYPE] The Accept content type to request (defaults to
-                          text/markdown).
-  --no-color              [env: SHOPIFY_FLAG_NO_COLOR] Disable color output.
-  --verbose               [env: SHOPIFY_FLAG_VERBOSE] Increase the verbosity of the output.
+  -o, --output=<value>  [env: SHOPIFY_FLAG_OUTPUT] Write the document to this file path instead of printing it to
+                        stdout.
+      --no-color        [env: SHOPIFY_FLAG_NO_COLOR] Disable color output.
+      --verbose         [env: SHOPIFY_FLAG_VERBOSE] Increase the verbosity of the output.
 
 DESCRIPTION
   Download a complete document from shopify.dev. Every page on shopify.dev has a Markdown version, and that is what this
-  tool returns by default. Use this to pull an entire document verbatim — for example, a set of instructions an agent
-  follows like a centrally-served skill. For finding the relevant pieces of content across shopify.dev instead, use
-  `search`.
+  tool returns. Use this to pull an entire document verbatim — for example, a set of instructions an agent follows like
+  a centrally-served skill. For finding the relevant pieces of content across shopify.dev instead, use `search`.
 
 EXAMPLES
   # fetch the Markdown version of a Shopify.dev page
-      shopify fetch-doc https://shopify.dev/docs/api/shopify-cli
-      # fetch the HTML version of a Shopify.dev page
-      shopify fetch-doc https://shopify.dev/docs/api/shopify-cli --content-type text/html
+
+    $ shopify fetch-doc https://shopify.dev/docs/api/shopify-cli
+
+  # save the document to a file instead of printing it
+
+    $ shopify fetch-doc https://shopify.dev/docs/api/shopify-cli --output docs/shopify-cli.md
 ```
 
 ## `shopify help [command] [flags]`

packages/cli/oclif.manifest.json

@@ -3544,20 +3544,13 @@
           "required": true
         }
       },
-      "description": "Download a complete document from shopify.dev. Every page on shopify.dev has a Markdown version, and that is what this tool returns by default. Use this to pull an entire document verbatim — for example, a set of instructions an agent follows like a centrally-served skill. For finding the relevant pieces of content across shopify.dev instead, use `search`.",
+      "description": "Download a complete document from shopify.dev. Every page on shopify.dev has a Markdown version, and that is what this tool returns. Use this to pull an entire document verbatim — for example, a set of instructions an agent follows like a centrally-served skill. For finding the relevant pieces of content across shopify.dev instead, use `search`.",
       "enableJsonFlag": false,
       "examples": [
-        "# fetch the Markdown version of a Shopify.dev page\n    shopify fetch-doc https://shopify.dev/docs/api/shopify-cli\n\n    # fetch the HTML version of a Shopify.dev page\n    shopify fetch-doc https://shopify.dev/docs/api/shopify-cli --content-type text/html\n    "
+        "# fetch the Markdown version of a Shopify.dev page\nshopify fetch-doc https://shopify.dev/docs/api/shopify-cli",
+        "# save the document to a file instead of printing it\nshopify fetch-doc https://shopify.dev/docs/api/shopify-cli --output docs/shopify-cli.md"
       ],
       "flags": {
-        "content-type": {
-          "description": "The Accept content type to request (defaults to text/markdown).",
-          "env": "SHOPIFY_FLAG_CONTENT_TYPE",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "name": "content-type",
-          "type": "option"
-        },
         "no-color": {
           "allowNo": false,
           "description": "Disable color output.",
@@ -3566,6 +3559,15 @@
           "name": "no-color",
           "type": "boolean"
         },
+        "output": {
+          "char": "o",
+          "description": "Write the document to this file path instead of printing it to stdout.",
+          "env": "SHOPIFY_FLAG_OUTPUT",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "output",
+          "type": "option"
+        },
         "verbose": {
           "allowNo": false,
           "description": "Increase the verbosity of the output.",

packages/cli/src/cli/commands/fetch-doc.ts

@@ -5,17 +5,15 @@ import {Args, Flags} from '@oclif/core'
 
 export default class FetchDoc extends Command {
   static description =
-    'Download a complete document from shopify.dev. Every page on shopify.dev has a Markdown version, and that is what this tool returns by default. Use this to pull an entire document verbatim — for example, a set of instructions an agent follows like a centrally-served skill. For finding the relevant pieces of content across shopify.dev instead, use `search`.'
+    'Download a complete document from shopify.dev. Every page on shopify.dev has a Markdown version, and that is what this tool returns. Use this to pull an entire document verbatim — for example, a set of instructions an agent follows like a centrally-served skill. For finding the relevant pieces of content across shopify.dev instead, use `search`.'
 
   static usage = `fetch-doc [URL]`
 
   static examples = [
     `# fetch the Markdown version of a Shopify.dev page
-    shopify fetch-doc https://shopify.dev/docs/api/shopify-cli
-
-    # fetch the HTML version of a Shopify.dev page
-    shopify fetch-doc https://shopify.dev/docs/api/shopify-cli --content-type text/html
-    `,
+shopify fetch-doc https://shopify.dev/docs/api/shopify-cli`,
+    `# save the document to a file instead of printing it
+shopify fetch-doc https://shopify.dev/docs/api/shopify-cli --output docs/shopify-cli.md`,
   ]
 
   static args = {
@@ -28,14 +26,15 @@ export default class FetchDoc extends Command {
 
   static flags = {
     ...globalFlags,
-    'content-type': Flags.string({
-      description: 'The Accept content type to request (defaults to text/markdown).',
-      env: 'SHOPIFY_FLAG_CONTENT_TYPE',
+    output: Flags.string({
+      char: 'o',
+      description: 'Write the document to this file path instead of printing it to stdout.',
+      env: 'SHOPIFY_FLAG_OUTPUT',
     }),
   }
 
   async run(): Promise<void> {
     const {args, flags} = await this.parse(FetchDoc)
-    await fetchDocService(args.url, flags['content-type'])
+    await fetchDocService(args.url, flags.output)
   }
 }

packages/cli/src/cli/services/commands/fetch-doc.test.ts

@@ -3,9 +3,12 @@ import {describe, expect, test, vi, beforeEach} from 'vitest'
 import {fetch} from '@shopify/cli-kit/node/http'
 import {outputResult} from '@shopify/cli-kit/node/output'
 import {AbortError} from '@shopify/cli-kit/node/error'
+import {mkdir, writeFile} from '@shopify/cli-kit/node/fs'
+import {dirname, resolvePath} from '@shopify/cli-kit/node/path'
 
 vi.mock('@shopify/cli-kit/node/http')
 vi.mock('@shopify/cli-kit/node/output')
+vi.mock('@shopify/cli-kit/node/fs')
 
 const okResponse = (body: string) =>
   ({ok: true, status: 200, statusText: 'OK', text: () => Promise.resolve(body)}) as any
@@ -15,7 +18,7 @@ beforeEach(() => {
 })
 
 describe('fetchDocService', () => {
-  test('requests Markdown by default and prints the body to stdout', async () => {
+  test('requests Markdown and prints the body to stdout', async () => {
     await fetchDocService('https://shopify.dev/docs/api/shopify-cli')
 
     expect(fetch).toHaveBeenCalledWith('https://shopify.dev/docs/api/shopify-cli', {
@@ -24,14 +27,6 @@ describe('fetchDocService', () => {
     expect(outputResult).toHaveBeenCalledWith('# Doc')
   })
 
-  test('passes a custom content type through as the Accept header', async () => {
-    await fetchDocService('https://shopify.dev/docs/api/shopify-cli', 'text/html')
-
-    expect(fetch).toHaveBeenCalledWith('https://shopify.dev/docs/api/shopify-cli', {
-      headers: {Accept: 'text/html'},
-    })
-  })
-
   test('accepts shopify.dev subdomains', async () => {
     await fetchDocService('https://www.shopify.dev/docs')
 
@@ -48,6 +43,15 @@ describe('fetchDocService', () => {
     expect(fetch).not.toHaveBeenCalled()
   })
 
+  test('writes the document to the output path instead of stdout', async () => {
+    await fetchDocService('https://shopify.dev/docs/api/shopify-cli', 'docs/shopify-cli.md')
+
+    const expectedPath = resolvePath('docs/shopify-cli.md')
+    expect(mkdir).toHaveBeenCalledWith(dirname(expectedPath))
+    expect(writeFile).toHaveBeenCalledWith(expectedPath, '# Doc')
+    expect(outputResult).not.toHaveBeenCalled()
+  })
+
   test('throws when the response is not ok', async () => {
     vi.mocked(fetch).mockResolvedValue({ok: false, status: 404, statusText: 'Not Found'} as any)
 

packages/cli/src/cli/services/commands/fetch-doc.ts

@@ -1,14 +1,18 @@
 import {fetch} from '@shopify/cli-kit/node/http'
-import {outputResult} from '@shopify/cli-kit/node/output'
+import {outputInfo, outputResult} from '@shopify/cli-kit/node/output'
 import {AbortError} from '@shopify/cli-kit/node/error'
+import {mkdir, writeFile} from '@shopify/cli-kit/node/fs'
+import {dirname, resolvePath} from '@shopify/cli-kit/node/path'
 
-const DEFAULT_CONTENT_TYPE = 'text/markdown'
+// Every page on shopify.dev has a Markdown representation, which is the clean,
+// parseable content agents want — so we always request it.
+const MARKDOWN_CONTENT_TYPE = 'text/markdown'
 
 // Hosts whose documents are allowed to be fetched. A URL matches when its
 // hostname is one of these or a subdomain of one of these.
 const ALLOWED_HOSTS = ['shopify.dev']
 
-export async function fetchDocService(url: string, contentType?: string) {
+export async function fetchDocService(url: string, outputPath?: string) {
   let parsedURL: URL
   try {
     parsedURL = new URL(url)
@@ -22,12 +26,23 @@ export async function fetchDocService(url: string, contentType?: string) {
     throw new AbortError(`Only documents from the following hosts can be fetched: ${ALLOWED_HOSTS.join(', ')}.`)
   }
 
-  const accept = contentType ?? DEFAULT_CONTENT_TYPE
-  const response = await fetch(url, {headers: {Accept: accept}})
+  const response = await fetch(url, {headers: {Accept: MARKDOWN_CONTENT_TYPE}})
 
   if (!response.ok) {
     throw new AbortError(`Failed to fetch ${url}: ${response.status} ${response.statusText}`)
   }
 
-  outputResult(await response.text())
+  const body = await response.text()
+
+  // When an output path is provided, write the document to disk (creating any
+  // missing parent directories) instead of printing it to stdout.
+  if (outputPath) {
+    const absolutePath = resolvePath(outputPath)
+    await mkdir(dirname(absolutePath))
+    await writeFile(absolutePath, body)
+    outputInfo(`Saved ${url} to ${absolutePath}`)
+    return
+  }
+
+  outputResult(body)
 }