export declare const commandsMdxTemplate = "---\ntitle: \"Commands\"\ndescription: \"In this page, you can find all the commands available in Doccupine CLI.\"\ndate: \"2026-02-19\"\nupdated: \"2026-08-04\"\ncategory: \"Getting Started\"\ncategoryOrder: 0\norder: 2\n---\n# Commands\n\nIn this page, you can find all the commands available in Doccupine CLI.\n\n## Run Doccupine CLI\n\nCreate a new directory for your project and navigate to it in your terminal. Run the following command to create a new Doccupine project:\n\n```bash\nnpx doccupine\n```\n\nOnce you run the command, Doccupine will ask you to select a directory to store your MDX files. Choose the directory where you want to create your documentation files.\nAfter selecting the directory, Doccupine will ask you to enter the name of the directory for the generated website. Enter the name of the directory where you want to create your website.\nFinally, Doccupine will ask for an optional path to an OpenAPI document. Leave it blank to skip, or point it at a `.yaml`, `.yml`, or `.json` spec to generate an interactive [API Playground](/api-playground) from your API.\n\nThis will start the development server on port 3000. Open your browser and navigate to http://localhost:3000 to view your documentation.\n\n## Options\n\n| Flag                       | Description                                                                 |\n| -------------------------- | --------------------------------------------------------------------------- |\n| `--port <port>`            | Port for the dev server (default: `3000`). Auto-increments if taken.        |\n| `--verbose`                | Show all Next.js output including compilation details.                      |\n| `--reset`                  | Re-prompt for watch/output directories and the OpenAPI spec path.           |\n| `--skip-install`           | Always skip dependency installation before starting the development server. |\n| `--package-manager <name>` | Use `pnpm` or `npm` for the generated app instead of auto-detection.        |\n\n<Callout type=\"warning\">\n  The watch and output directories must not overlap. The output directory must be empty, contain only local metadata such as `.DS_Store` or `.env.local`, or already be owned by Doccupine. This prevents the generator from overwriting another project. If an older `doccupine.json` no longer validates, run `doccupine config --reset`. Generation also reports a validation error, instead of letting one page overwrite another, when two source files resolve to the same route.\n</Callout>\n\nStarter documentation is created only when the selected source directory contains no MDX files. Existing pages are never replaced just because `index.mdx` is missing. Frontmatter must use the normal YAML `---` delimiter; language-tagged executable frontmatter is rejected.\n\nDoccupine marks its output directory with `.doccupine-generated.json` and records generated route, Markdown-mirror, and copied public-file ownership in `.doccupine-artifacts.json`. Treat both files as internal generator state. A fresh run recreates `app`, and later refreshes may rewrite other registered template paths, so keep durable changes in source MDX, project-root JSON files, and `public`.\n\n## Watch mode\n\nThe default command watches MDX files, supported project-root JSON configuration, `fonts.json`, `analytics.json`, `doccupine.json`, public assets, and configured OpenAPI documents with their discovered local `$ref` files. Changes are processed serially. Once every watcher is ready, Doccupine compares the current sources with the versions used during initial generation and reconciles edits made while startup was still running.\n\n## Route collisions and recovery\n\nTwo MDX sources cannot generate the same route. For example, `guide.mdx` and `guide/index.mdx` both resolve to `/guide`. A one-time build stops before either source can overwrite the other.\n\nDuring watch mode, a collision keeps the last successfully generated page and site metadata in place. After you move, rename, or delete one of the colliding sources, Doccupine retries the blocked sources and any other MDX changes that could not be applied while the collision existed. A restart or manual resave is not required.\n\n<Callout type=\"info\">\n  Failed watch refreshes keep or restore the last successful pages, route ownership, inferred sections, sitemap, and LLMS/MCP content. A new page with no successful version stays absent until it can be generated safely.\n</Callout>\n\n## Reloading doccupine.json\n\nChanging the `openapi` field is applied live after the complete candidate reference validates and generates successfully. Invalid JSON, invalid configuration, a missing spec, or a failed generation keeps the current OpenAPI reference and watcher active. Changes to `watchDir`, `outputDir`, `port`, or `packageManager` require restarting Doccupine.\n\n## File-system safety\n\nDoccupine does not follow symlinked MDX files or nested directories beneath `watchDir`. Project-root configuration and public assets must also use real files and directories, and the `public` root cannot be a symlink. A stable symlink used as the `watchDir` root is supported, but links inside it are rejected.\n\nThe output directory must be a real directory, and generated paths cannot contain symlinks. OpenAPI root specs must resolve inside the project, while local references must remain inside the root spec's directory. These checks prevent generated reads, writes, and removals from being redirected elsewhere.\n\n## Dependency installation\n\nThe first run installs the generated app's dependencies. After that, Doccupine records a fingerprint of the generated `package.json` and the package manager in `.doccupine-install` and reinstalls only when that fingerprint changes or `node_modules` is missing - later runs start the dev server straight away. Pass `--skip-install` to skip the check entirely, for example when you manage dependencies yourself.\n\n## Browsing from another device\n\nThe dev server is reachable from other devices on your network, but Next.js only serves development resources such as the hot-reload socket to hosts it recognizes. Opened over a LAN IP or a Tailscale/VPN hostname, the page renders but never becomes interactive.\n\nTo allow additional hostnames, set `ALLOWED_DEV_ORIGINS` in the generated app's `.env` file and restart the dev server. Comma-separate multiple hostnames:\n\n```env\nALLOWED_DEV_ORIGINS=my-machine.tailnet-name.ts.net\n```\n\n<Callout type=\"note\">\n  This only affects the development server. Production builds ignore the\n  variable, and leaving it unset keeps Next's DNS-rebinding protection fully\n  enabled.\n</Callout>\n\n## Verbose mode\n\n```bash\nnpx doccupine --verbose\n```\n\n<Callout type=\"note\">\n  This will show Next.js output in the terminal, providing detailed logs useful for debugging during development.\n</Callout>\n\n## Generate the website\n\n```bash\nnpx doccupine build\n```\n\nYou can also use the equivalent `npx doccupine generate` command. These commands scaffold the Next.js app from your MDX files without installing dependencies or starting the development server. To produce a production build, install dependencies and run the generated app's `build` script.\n\n## Show current configuration\n\n```bash\nnpx doccupine config --show\n```\n\nThis will show the current configuration for Doccupine.\n\n## Reset configuration\n\n```bash\nnpx doccupine config --reset\n```\n\nThis will reset the current configuration for Doccupine.";