@themvora/cli

`themvora doctor`

Prerequisites

Node.js 22+
Project with @themvora/cli installed or npx access

Check the health of a Themvora project: its framework, package manager, installed Themvora packages, theme configuration, and theme files.

doctor only performs checks it can make reliably. It does not guess, and it never walks a filesystem — it looks at the project root, *.theme.json at the root, and one level of themes/.

Synopsis — Check a Themvora project's health

text

Usage:
  themvora doctor [dir] [options]

Argument	Description
`<dir>`	Project directory to check. Defaults to the current directory. (optional)

Options

Option	Description	Default
`--json`	Emit the health report as JSON on stdout.	—
`--quiet`	Show only warnings and errors.	—

Exit codes

Code	Meaning
`0`	healthy (warnings alone do not fail)
`3`	an actionable health failure
`1`	command/runtime error
`2`	usage/argument error

Examples

bash

themvora doctor
themvora doctor ./my-app
themvora doctor --json

Generated from packages/cli/src/command-schema.json — the same contract themvora --help renders.

Examples

bash

# The current directory
themvora doctor

# Another project
themvora doctor ./my-app

Output

text

themvora doctor — /path/to/project

  ✓ Project manifest    healthy-app — 3 dependencies
  ✓ Package manager     pnpm
  ✓ Framework           React (Vite)
  ✓ Themvora packages   @themvora/core, @themvora/react
  ✓ Theme config        theme.config.ts
  ✓ Theme files         2 valid, generated by semantic-v2

healthy

Every finding that has a concrete correction carries it:

text

  ! Package manager     2 lockfiles found: package-lock.json, yarn.lock
      → Keep one lockfile; several let different tools resolve different trees.
  ✗ Themvora packages   none installed
      → Install @themvora/core (and the integration for your framework).

What it checks

Check	Level
`project`	error if `package.json` is missing or unparseable
`package-manager`	warning for no lockfile, or several
`framework`	warning when nothing is detected
`framework-support`	info when the framework is a library integration but not an `init` target
`themvora-packages`	error when none are installed
`framework-integration`	warning when the framework is in use but its integration is not installed
`theme-config`	error when `theme.config.` exists without `@themvora/core`; warning* when it is missing
`theme-files`	error for an unreadable, malformed, or structurally invalid theme file (comments and trailing commas are accepted, as in `validate`)
`generator-metadata`	warning when a theme was generated by an older algorithm than the current one

Framework detection reads dependencies and prefers the most specific match: a Next.js app also depends on react, so Next.js wins.

Warnings are not failures

A project with warnings is still healthy:

State	Exit
No errors	`0` — including a warnings-only project
Any error	`3`
Not a directory, or an unreadable project	`1`

JSON output

bash

themvora doctor --json

json

{
  "directory": "/path/to/project",
  "framework": { "id": "react", "displayName": "React", "initSupported": true },
  "packageManager": "pnpm",
  "findings": [
    {
      "id": "theme-config",
      "level": "warning",
      "title": "Theme config",
      "detail": "no theme.config.ts found",
      "fix": "Add a theme.config.ts so the pre-paint bootstrap and the runtime read one registry."
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "info": 5, "healthy": true }
}

--quiet prints only warnings and errors.

Next Steps

Next: migrate.

@themvora/cli

`themvora doctor`

Prerequisites

Node.js 22+
Project with @themvora/cli installed or npx access

Check the health of a Themvora project: its framework, package manager, installed Themvora packages, theme configuration, and theme files.

doctor only performs checks it can make reliably. It does not guess, and it never walks a filesystem — it looks at the project root, *.theme.json at the root, and one level of themes/.

Synopsis — Check a Themvora project's health

text

Usage:
  themvora doctor [dir] [options]

Argument	Description
`<dir>`	Project directory to check. Defaults to the current directory. (optional)

Options

Option	Description	Default
`--json`	Emit the health report as JSON on stdout.	—
`--quiet`	Show only warnings and errors.	—

Exit codes

Code	Meaning
`0`	healthy (warnings alone do not fail)
`3`	an actionable health failure
`1`	command/runtime error
`2`	usage/argument error

Examples

bash

themvora doctor
themvora doctor ./my-app
themvora doctor --json

Generated from packages/cli/src/command-schema.json — the same contract themvora --help renders.

Examples

bash

# The current directory
themvora doctor

# Another project
themvora doctor ./my-app

Output

text

themvora doctor — /path/to/project

  ✓ Project manifest    healthy-app — 3 dependencies
  ✓ Package manager     pnpm
  ✓ Framework           React (Vite)
  ✓ Themvora packages   @themvora/core, @themvora/react
  ✓ Theme config        theme.config.ts
  ✓ Theme files         2 valid, generated by semantic-v2

healthy

Every finding that has a concrete correction carries it:

text

  ! Package manager     2 lockfiles found: package-lock.json, yarn.lock
      → Keep one lockfile; several let different tools resolve different trees.
  ✗ Themvora packages   none installed
      → Install @themvora/core (and the integration for your framework).

What it checks

Check	Level
`project`	error if `package.json` is missing or unparseable
`package-manager`	warning for no lockfile, or several
`framework`	warning when nothing is detected
`framework-support`	info when the framework is a library integration but not an `init` target
`themvora-packages`	error when none are installed
`framework-integration`	warning when the framework is in use but its integration is not installed
`theme-config`	error when `theme.config.` exists without `@themvora/core`; warning* when it is missing
`theme-files`	error for an unreadable, malformed, or structurally invalid theme file (comments and trailing commas are accepted, as in `validate`)
`generator-metadata`	warning when a theme was generated by an older algorithm than the current one

Framework detection reads dependencies and prefers the most specific match: a Next.js app also depends on react, so Next.js wins.

Warnings are not failures

A project with warnings is still healthy:

State	Exit
No errors	`0` — including a warnings-only project
Any error	`3`
Not a directory, or an unreadable project	`1`

JSON output

bash

themvora doctor --json

json

{
  "directory": "/path/to/project",
  "framework": { "id": "react", "displayName": "React", "initSupported": true },
  "packageManager": "pnpm",
  "findings": [
    {
      "id": "theme-config",
      "level": "warning",
      "title": "Theme config",
      "detail": "no theme.config.ts found",
      "fix": "Add a theme.config.ts so the pre-paint bootstrap and the runtime read one registry."
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "info": 5, "healthy": true }
}

--quiet prints only warnings and errors.

Next Steps

Next: migrate.

`themvora doctor`

Prerequisites

Synopsis — Check a Themvora project's health

Options

Exit codes

Examples

Examples

Output

What it checks

Warnings are not failures

JSON output

Next Steps

Related

`themvora doctor`

Prerequisites

Synopsis — Check a Themvora project's health

Options

Exit codes

Examples

Examples

Output

What it checks

Warnings are not failures

JSON output

Next Steps

Related