Doctor

The doctor command validates your specra.config.json and checks your project setup for common issues.

1create-specra doctor

What It Checks

The doctor runs the following diagnostics:

Example Output

All checks passing

Specra Doctor
Checking project in /home/user/my-docs

  ✓ specra.config.json: Found
  ✓ Config parsing: Valid JSON
  ✓ site.title: My Documentation
  ✓ site.description: Set
  ✓ site.url: https://docs.example.com
  ✓ docs/ directory: Found
  ✓ Version directories: Found: v1.0.0, v2.0.0
  ✓ site.activeVersion: v1.0.0
  ✓ specra dependency: ^0.2.5
  ✓ navigation.tabGroups: 2 tab group(s) configured

  All 10 checks passed!

With issues

Specra Doctor
Checking project in /home/user/my-docs

  ✓ specra.config.json: Found
  ✓ Config parsing: Valid JSON
  ✗ site.title: Missing required "site.title" (string)
  ⚠ site.description: No description set. Recommended for SEO.
  ⚠ site.url: No URL set. Recommended for canonical URLs and SEO.
  ✓ docs/ directory: Found
  ✗ Version directories: Versioning enabled but no version directories found in docs/
  ⚠ auth.token in config: Token found in specra.config.json. Use --global or add to .gitignore.

  2 error(s) 3 warning(s) 3 passed

Checking a Different Directory

By default, doctor checks the current directory. Use --dir to check a different project:

1create-specra doctor --dir ./my-other-project

Options Reference

Common Issues and Fixes

Missing site.title

Every Specra project needs a title. Add it to your specra.config.json:

1{
2  "site": {
3    "title": "My Documentation"
4  }
5}

No version directories

If versioning is enabled (the default), you need at least one version folder under docs/:

1mkdir -p docs/v1.0.0

Then create your first MDX file inside it.

activeVersion mismatch

The site.activeVersion value must match the name of a directory under docs/. For example, if your directory is docs/v1.0.0/, set:

1{
2  "site": {
3    "activeVersion": "v1.0.0"
4  }
5}

Auth token in config

If you see this warning, your authentication token is stored in specra.config.json. This is fine for local development, but if you commit this file to git, your token will be exposed. Options:

1. Add to .gitignore — Add specra.config.json and use a separate checked-in config
2. Use global storage — Run create-specra logout then create-specra login --global to move the token to ~/.specra/