--- title: CLI Overview description: Preview, validate, and maintain your documentation from the terminal. Install globally or run with npx. --- 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](https://github.com/jamdesk/jamdesk-cli). ## Installation Install globally from [npm](https://www.npmjs.com/package/jamdesk) to use `jamdesk` from anywhere: ```bash npm install -g jamdesk ``` Install via Homebrew on macOS or Linux: ```bash brew tap jamdesk/tap brew install jamdesk ``` Install via script: ```bash curl -fsSL https://get.jamdesk.com | bash ``` Upgrade or uninstall: ```bash curl -fsSL https://get.jamdesk.com/upgrade | bash curl -fsSL https://get.jamdesk.com/uninstall | bash ``` Install via script: ```powershell iwr https://get.jamdesk.com/win | iex ``` Upgrade or uninstall: ```powershell iwr https://get.jamdesk.com/upgrade | iex iwr https://get.jamdesk.com/uninstall | iex ``` Run without installing: ```bash npx jamdesk dev ``` After installing, verify it works: ```bash jamdesk --version ``` ### Requirements - **Node.js** v20.0.0 or higher - **npm** v8 or higher (recommended) ## Quick Start Create a new documentation project: ```bash jamdesk init my-docs cd my-docs ``` Run the local development server with hot reload: ```bash jamdesk dev ``` Your docs will be available at **http://localhost:3000/docs** Check for configuration errors, broken links, and spelling: ```bash jamdesk validate jamdesk broken-links jamdesk spellcheck ``` ## Commands Run `jamdesk --help` for detailed information about any command. ### Development Start the local development server with hot reload. ```bash 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 to run on (default: 3000) | | `-v, --verbose` | Enable verbose output | Create a new documentation project. ```bash 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 Log in to Jamdesk via your browser. Required before deploying. ```bash jamdesk login ``` Opens the Jamdesk dashboard in your browser for authentication. Credentials are stored locally in `~/.jamdeskrc`. Browser-based auth flow, session management, and troubleshooting Clear stored credentials. ```bash jamdesk logout ``` Show the current authenticated user and verify your session is valid. ```bash jamdesk whoami ``` ### Validation Validate your `docs.json` configuration, MDX syntax, and OpenAPI specs. ```bash 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. ```bash jamdesk broken-links ``` **Example output:** ```text 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](/content/links#how-internal-links-are-detected) for details. Check your documentation for spelling errors. ```bash jamdesk spellcheck ``` **Example output:** ```text getting-started.mdx:14 - "recieve" └─ Did you mean: receive Found 3 misspellings across 24 pages. Tip: Run "jamdesk spellcheck --fix" to interactively fix or ignore words. ``` Uses an English dictionary with 150+ built-in tech terms (API, GraphQL, Kubernetes, React, etc.) so common jargon doesn't flag. Skips code blocks, inline code, frontmatter, JSX, URLs, and file paths. Currently English only — multi-language dictionary support is planned. **Options:** | Flag | Description | |------|-------------| | `--fix` | Interactively fix misspellings or add to ignore list | | `--json` | Output as JSON (for CI pipelines) | | `-v, --verbose` | Show each file as it's checked | **Interactive fix mode (`--fix`)** steps through each unique misspelled word: ```text 1/10 "recieve" — found in 3 files intro.mdx:14, setup.mdx:7, guide.mdx:22 ? What do you want to do? ❯ Fix → receive (recommended) Fix → relieve Ignore in the future (add to docs.json) Skip ``` - **Fix** replaces the word with a suggestion across all files (prose-safe — won't modify code blocks or JSX attributes). Up to 3 suggestions are shown, with the best match marked as recommended. - **Ignore** adds the word to `spellcheck.ignore` in your docs.json so it won't be flagged again - **Skip** does nothing for this run Changes are previewed and confirmed before applying. **Custom ignore list:** Add project-specific terms to your docs.json: ```json docs.json { "spellcheck": { "ignore": ["YourProduct", "kubectl", "Terraform"] } } ``` Your project name from `docs.json` is automatically ignored. Validate a single OpenAPI specification file. ```bash 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. ```bash 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. ```bash jamdesk migrate ``` Detects your Mintlify config and converts it to Jamdesk format. In the same pass it renames deprecated components (e.g. `CardGroup` → `Columns`), relocates orphan snippet MDX files into `/snippets/` and rewrites parent-relative imports, extracts inline components that use React hooks into `/snippets/.tsx` with `'use client'`, and auto-fixes mechanical MDX syntax issues. Idempotent — re-run it safely. 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. ```bash 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 ` | Deploy to a specific project | Full deployment pipeline, build phases, error reference, and troubleshooting ### Maintenance Check your environment and diagnose issues. ```bash 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. ```bash 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. ```bash jamdesk update ``` You can also update manually: ```bash npm update -g jamdesk ``` ## Configuration Create `~/.jamdeskrc` to set default options: ```json { "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. ```text ✗ 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 < 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:** 1. Run `jamdesk doctor` to check your environment 2. Run `jamdesk clean` to clear the cache 3. Use `jamdesk dev --verbose` for detailed error output 4. 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:** ```bash # 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:** 1. Check permissions on `~/.jamdesk`: `ls -la ~/.jamdesk` 2. Fix ownership: `sudo chown -R $(whoami) ~/.jamdesk` 3. Run `jamdesk clean` and try again **Still having issues?** Check the [CLI Troubleshooting guide](/help/troubleshooting/cli-issues) or [open an issue on GitHub](https://github.com/jamdesk/jamdesk-cli/issues). ## What's Next? Login flow, sessions, and troubleshooting Deploy from the terminal Advanced local development options Migrate from Mintlify or other platforms