CLI Overview

The Jamdesk CLI lets you preview docs locally, validate configuration, check for broken links, and migrate from other platforms. It's open-source under the Apache License 2.0.

Installation

Install globally to use jamdesk from anywhere:

npm install -g jamdesk

After installing, verify it works:

jamdesk --version

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:

Automatic validation on startup (docs.json schema and MDX syntax)
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

Authentication

jamdesk login

Opens the Jamdesk dashboard in your browser for authentication. Credentials are stored locally in ~/.jamdeskrc.

Authentication Guide

Browser-based auth flow, session management, and troubleshooting

Clear stored credentials.

jamdesk logout

Show the current authenticated user and verify your session is valid.

jamdesk whoami

Validation

Validate your docs.json configuration, MDX syntax, and OpenAPI specs.

jamdesk validate
jamdesk validate --skip-mdx

Checks for:

Valid JSON syntax in docs.json
Required fields (name, navigation)
Valid theme values
MDX syntax errors (e.g., unescaped < characters)
OpenAPI spec validation (if configured)
Schema compliance

Options:

Flag	Description
`--skip-mdx`	Skip MDX syntax validation
`-v, --verbose`	Show detailed validation output

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.

Detects links to missing pages and typos. See Links & Navigation for details.

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.

jamdesk migrate

The interactive wizard detects your Mintlify configuration and converts it to Jamdesk format, including navigation structure and component syntax.

Migration Guide

Full migration guide with step-by-step instructions for Mintlify and other platforms

Deployment

Upload your docs and trigger a build directly from the terminal.

jamdesk deploy
jamdesk deploy --detach
jamdesk deploy --full-rebuild

Progress is shown live as each build phase completes. Also available as jamdesk push.

Flag	Description
`--detach`	Queue and exit immediately
`--full-rebuild`	Force full rebuild (no cache)
`--project <id>`	Deploy to a specific project

CLI Deploy Guide

Full deployment pipeline, build phases, error reference, and troubleshooting

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

MDX files are parsed as JSX, so certain characters have special meaning.

Common issue: The < character is interpreted as the start of a JSX tag.

✗ Found 1 MDX syntax error(s)

  getting-started.mdx:42
    Unexpected character `5` (U+0035) before name
    Fix: A < character is being parsed as JSX. Use &lt; or rewrite

Solutions:

Use < for literal less-than: Values <50% are low
Rewrite to avoid the character: "Below 50%" instead of "<50%"
Run jamdesk validate for detailed error messages with line numbers

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

Still having issues? Check the CLI Troubleshooting guide or open an issue on GitHub.

What's Next?

Authentication

CLI Deploy

Deploy from the terminal

Local Preview

Advanced local development options

Migration Guide

Migrate from Mintlify or other platforms