CLI Overview

The Jamdesk CLI lets you preview your documentation locally with hot reload, validate your configuration, and more.

Installation

Install globally to use jamdesk from anywhere:

npm install -g jamdesk

Run without installing:

npx jamdesk dev

Requirements

Node.js v20.0.0 or higher
npm v8 or higher (recommended)

Quick Start

Create a Project

Create a new documentation project:

jamdesk init my-docs
cd my-docs

Start Development Server

Run the local development server with hot reload:

jamdesk dev

Your docs will be available at http://localhost:3000/docs

Validate Before Deploying

Check for configuration errors and broken links:

jamdesk validate
jamdesk broken-links

Commands

Run jamdesk <command> --help for detailed information about any command.

Development

Start the local development server with hot reload.

jamdesk dev
jamdesk dev --port 3001

Features:

Hot reload on MDX file changes
Automatic navigation rebuild on docs.json changes
Full search functionality
All themes and components available

Options:

Flag	Description
`-p, --port <port>`	Port to run on (default: 3000)
`-v, --verbose`	Enable verbose output

Create a new documentation project.

jamdesk init              # Interactive mode
jamdesk init my-docs      # Create in new directory

This creates a new project with:

docs.json configuration file
Sample MDX pages
Recommended folder structure

Validation

Validate your docs.json configuration and OpenAPI specs.

jamdesk validate

Checks for:

Valid JSON syntax
Required fields (name, navigation)
Valid theme values
OpenAPI spec validation (if configured)
Schema compliance

Run this before deploying to catch errors early.

Scan your documentation for broken internal links.

jamdesk broken-links

Example output:

docs/getting-started.mdx:15 - /docs/quikstart
  Did you mean: /docs/quickstart

Found 1 broken link in 45 files.

Validate a single OpenAPI specification file.

jamdesk openapi-check openapi.yaml
jamdesk openapi-check api/spec.json

Validates:

Valid YAML/JSON syntax
OpenAPI 3.x schema compliance
Endpoint definitions
$ref references resolve correctly

File Management

Rename a page and automatically update all references.

jamdesk rename docs/old-name.mdx docs/new-name.mdx

This will:

Rename the file
Update docs.json navigation
Update links in all other MDX files
Update snippet references

Use this instead of manual renaming to keep all references in sync.

Migration

Migrate documentation from Mintlify to Jamdesk.

cd /path/to/mintlify-docs
jamdesk migrate

The interactive wizard will:

Detect your Mintlify configuration (mint.json)
Ask where to save the migrated docs
Ask for the new directory name (default: jamdesk-docs)
Let you choose a theme (Jam, Nebula, or Pulsar)
Copy all files and convert the configuration

Supported conversions:

Mintlify	Jamdesk
`$schema`	Updated to Jamdesk schema
`topbarLinks`	`navbar.links`
`topbarCtaButton`	`navbar.primary`
`anchors`	`navigation.anchors`
`navigation`	`navigation.groups`
`footerSocials`	`footer.socials`
`mint.json`	Renamed to `docs.json`

Maintenance

Check your environment and diagnose issues.

jamdesk doctor

Checks:

Node.js version (requires v20+)
npm version
docs.json exists and is valid
~/.jamdesk cache status
Write permissions

Run this if you're experiencing issues with the CLI.

Clear the ~/.jamdesk cache directory.

jamdesk clean

This removes cached dependencies and build artifacts. Use it to:

Free up disk space
Fix corrupted cache issues
Force fresh dependency installation

Dependencies will be reinstalled on the next jamdesk dev.

Update the CLI to the latest version.

jamdesk update

You can also update manually:

npm update -g jamdesk

Configuration

Create ~/.jamdeskrc to set default options:

{
  "defaultPort": 3001,
  "verbose": false,
  "checkUpdates": true
}

Option	Type	Default	Description
`defaultPort`	number	3000	Default port for dev server
`verbose`	boolean	false	Enable verbose output by default
`checkUpdates`	boolean	true	Check for CLI updates on startup

Troubleshooting

Make sure you're in a directory with a docs.json file.

Solutions:

Run jamdesk init to create a new project
Check that you're in the correct directory
Verify the file is named exactly docs.json (not doc.json or similar)

The development server may fail to start for several reasons.

Try these steps:

Run jamdesk doctor to check your environment
Run jamdesk clean to clear the cache
Use jamdesk dev --verbose for detailed error output
Check that Node.js v20+ is installed: node --version

The first run installs dependencies to ~/.jamdesk/node_modules.

This is normal and only happens once. Subsequent runs will be much faster.

Another process is using the default port.

Solutions:

# Use a different port
jamdesk dev --port 3001

# Or set a default in ~/.jamdeskrc
{ "defaultPort": 3001 }

You may not have write permissions to the cache directory.

Solutions:

Check permissions on ~/.jamdesk: ls -la ~/.jamdesk
Fix ownership: sudo chown -R $(whoami) ~/.jamdesk
Run jamdesk clean and try again

What's Next?

docs.json Reference

Complete configuration reference

Components

Explore available MDX components