feat(cli): add --include to override config include globs

Add a repeatable, comma-separated --include flag to the scanning commands (panda/build/dev/check, cssgen, debug, info, buildinfo) that replaces the config's include globs for a single run. Plumbed via NodeDriverOptions.include, applied to the loaded config before building the compiler (and re-applied on watch reload). Drive-by: replace deprecated z.ZodIssue with z.core.$ZodIssue.

Author: segunadebayo

.changeset/cli-include-flag.md

@@ -0,0 +1,6 @@
+---
+'@pandacss/cli': minor
+'@pandacss/compiler': minor
+---
+
+Add a `--include` flag to the scanning commands (`panda`, `build`, `dev`, `check`, `cssgen`, `debug`, `info`, `buildinfo`) to override the config's `include` globs for a single run. The flag is repeatable and accepts comma-separated values, and replaces (does not merge with) the configured globs — useful for scanning a subset of files in CI or one-off builds.

packages/cli/__tests__/buildinfo.test.ts

@@ -76,6 +76,15 @@ describe('buildinfo command', () => {
     `)
   })
 
+  it('--include narrows the scanned modules in the artifact', async () => {
+    dir = createLibFixture()
+
+    const result = await runBuildinfo({ cwd: dir, logLevel: 'silent', include: ['button.tsx'] })
+
+    expect(result.ok).toBe(true)
+    expect(Object.keys(readBuildInfo(dir).modules)).toEqual(['button.tsx'])
+  })
+
   it('tracks exports of recipe-consuming components with portable module keys', async () => {
     dir = mkdtempSync(join(tmpdir(), 'panda-cli-lib-'))
     writeFileSync(

packages/cli/__tests__/cli-smoke.test.ts

@@ -46,6 +46,7 @@ describe('cli smoke', () => {
 
       \`--cwd="<cwd>"\` Current working directory
       \`-c, --config\` Path to panda config file
+      \`--include=<glob>\` Source file globs to scan, replacing the config include list
       \`-w, --watch\` Watch files and rebuild
       \`--outdir\` Output directory for generated files
       \`-o, --outfile\` Output file for extracted CSS

packages/cli/__tests__/cssgen.test.ts

@@ -78,6 +78,39 @@ describe('cssgen command', () => {
     })
   })
 
+  it('--include overrides a config that matches no sources', async () => {
+    dir = createFixture(`export default {
+      outdir: 'styled-system',
+      include: ['no-match/**/*.tsx'],
+      importMap: { css: ['@panda/css'] },
+    }`)
+
+    const result = await runCssgen({ cwd: dir, include: ['**/*.tsx'], logLevel: 'silent' })
+
+    expect(result.parsed).toHaveLength(1)
+    expect(readFileSync(join(dir, 'styled-system', 'styles.css'), 'utf8')).toContain('red')
+  })
+
+  it('--include replaces the config include rather than merging', async () => {
+    dir = createFixture()
+
+    const result = await runCssgen({ cwd: dir, include: ['missing/**/*.tsx'], logLevel: 'silent' })
+
+    expect(result.parsed).toEqual([])
+  })
+
+  it('--include accepts a comma-separated glob list', async () => {
+    dir = createFixture(`export default {
+      outdir: 'styled-system',
+      include: ['no-match/**/*.tsx'],
+      importMap: { css: ['@panda/css'] },
+    }`)
+
+    const result = await runCssgen({ cwd: dir, include: 'missing/**/*.tsx,**/*.tsx', logLevel: 'silent' })
+
+    expect(result.parsed).toHaveLength(1)
+  })
+
   it('renders human diagnostics with severity, code, and message', async () => {
     dir = createFixture()
     writeSyntaxError(dir)

packages/cli/__tests__/debug.test.ts

@@ -35,6 +35,19 @@ describe('debug command', () => {
     expect(extract.calls.length).toBeGreaterThan(0)
   })
 
+  it('--include overrides the config to extract otherwise-unscanned files', async () => {
+    dir = createFixture(`export default {
+      outdir: 'styled-system',
+      include: ['no-match/**/*.tsx'],
+      importMap: { css: ['@panda/css'] },
+    }`)
+
+    const result = await runDebug({ cwd: dir, include: ['**/*.tsx'], logLevel: 'silent' })
+
+    expect(result.sourceCount).toBe(1)
+    expect(existsSync(join(dir, 'styled-system', 'debug', 'App.tsx.extract.json'))).toBe(true)
+  })
+
   it('--only-config skips per-file extraction and css', async () => {
     dir = createFixture()
 

packages/cli/__tests__/info.test.ts

@@ -27,6 +27,18 @@ describe('info command', () => {
     expect(JSON.parse(logs[0])).toMatchObject({ ok: true, command: 'info', sourceCount: 1, diagnostics: [] })
   })
 
+  it('--include replaces the reported source globs', async () => {
+    // info reports the include globs (sourceCount = glob count), so an override
+    // with two globs replaces the config's single default glob.
+    dir = createFixture()
+
+    const base = await runInfo({ cwd: dir })
+    const overridden = await runInfo({ cwd: dir, include: ['a/**/*.tsx', 'b/**/*.tsx'] })
+
+    expect(base.sourceCount).toBe(1)
+    expect(overridden.sourceCount).toBe(2)
+  })
+
   it('includes timings in json output', async () => {
     dir = createFixture()
 

packages/cli/src/args.ts

@@ -22,6 +22,28 @@ export function outputArgs(): ArgsDef {
   }
 }
 
+export function includeArgs(): ArgsDef {
+  return {
+    include: {
+      type: 'string',
+      valueHint: 'glob',
+      description: 'Source file globs to scan, replacing the config include list',
+    },
+  }
+}
+
+/** Normalize `--include` (string, repeated array, or comma-separated) into a glob list. */
+export function normalizeInclude(value: unknown): string[] | undefined {
+  if (value == null) return undefined
+
+  const globs = (Array.isArray(value) ? value : [value])
+    .flatMap((entry) => String(entry).split(','))
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+
+  return globs.length > 0 ? globs : undefined
+}
+
 export function traceArgs(): ArgsDef {
   return {
     trace: { type: 'boolean', description: 'Enable compiler tracing' },
@@ -79,7 +101,7 @@ function flagName(path: PropertyKey | undefined): string {
   return `--${String(path).replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`)}`
 }
 
-function formatIssue(issue: z.ZodIssue, flags: Record<string, unknown>): string {
+function formatIssue(issue: z.core.$ZodIssue, flags: Record<string, unknown>): string {
   const path = issue.path[0]
   const name = flagName(path)
   const received = path === undefined ? undefined : flags[String(path)]

packages/cli/src/commands/build.ts

@@ -1,5 +1,5 @@
 import { defineCommand, type ArgsDef } from 'citty'
-import { baseArgs, outputArgs, parseCliFlags, traceArgs } from '../args'
+import { baseArgs, includeArgs, outputArgs, parseCliFlags, traceArgs } from '../args'
 import { isCheckClean } from '../check'
 import { buildFlagsSchema } from '../schema'
 import { runCommand } from '../run-command'
@@ -17,6 +17,7 @@ import { formatWatchError, startProjectWatch } from '../watch'
 export function buildArgs(): ArgsDef {
   return {
     ...baseArgs(),
+    ...includeArgs(),
     watch: { type: 'boolean', description: 'Watch files and rebuild', alias: 'w' },
     outdir: { type: 'string', description: 'Output directory for generated files' },
     outfile: { type: 'string', description: 'Output file for extracted CSS', alias: 'o' },

packages/cli/src/commands/buildinfo.ts

@@ -2,7 +2,7 @@ import { type BuildInfo, type Driver } from '@pandacss/compiler'
 import { defineCommand } from 'citty'
 import { mkdirSync, writeFileSync } from 'node:fs'
 import { dirname, isAbsolute, relative } from 'node:path'
-import { baseArgs, outputArgs, parseCliFlags, traceArgs } from '../args'
+import { baseArgs, includeArgs, outputArgs, parseCliFlags, traceArgs } from '../args'
 import { runCommand } from '../run-command'
 import { buildinfoFlagsSchema } from '../schema'
 import { collectParseDiagnostics, diagnosticsPass, normalizeDiagnostics } from '../diagnostics'
@@ -18,6 +18,7 @@ export const buildinfoCommand = defineCommand({
   },
   args: () => ({
     ...baseArgs(),
+    ...includeArgs(),
     outfile: { type: 'string', description: "Output path, default './<outdir>/panda.buildinfo.json'", alias: 'o' },
     panda: { type: 'string', description: "Peer Panda version range to stamp into the artifact (default '*')" },
     minify: { type: 'boolean', description: 'Minify the generated JSON', alias: 'm' },

packages/cli/src/commands/cssgen.ts

@@ -1,6 +1,6 @@
 import { defineCommand } from 'citty'
 import { type ParseFileReport, type StylesheetLayerName } from '@pandacss/compiler'
-import { baseArgs, outputArgs, parseCliFlags, traceArgs } from '../args'
+import { baseArgs, includeArgs, outputArgs, parseCliFlags, traceArgs } from '../args'
 import { checkExpectedFiles, formatCheckSummary, isCheckClean } from '../check'
 import { cssgenFlagsSchema } from '../schema'
 import { runCommand } from '../run-command'
@@ -18,6 +18,7 @@ export const cssgenCommand = defineCommand({
   },
   args: () => ({
     ...baseArgs(),
+    ...includeArgs(),
     watch: { type: 'boolean', description: 'Watch files and rebuild', alias: 'w' },
     outfile: { type: 'string', description: 'Output file for extracted CSS', alias: 'o' },
     splitting: { type: 'boolean', description: 'Emit split CSS files' },