{"schemaVersion":1,"title":"CLI reference","url":"https://appgram.github.io/docsy/guides/reference/cli","markdownUrl":"https://appgram.github.io/docsy/format-md/guides/reference/cli","jsonUrl":"https://appgram.github.io/docsy/agent/pages/guides/reference/cli.json","version":"current","locale":"en","markdown":"# CLI reference\n\nGenerate projects, validate configuration, build releases, and run production previews.\n\nWritten by: [nedimf](https://github.com/nedimf), [AppGram](https://appgram.dev)\n\nDocsy's CLI wraps Astro with configuration validation, project generation, build staging, and production startup.\n\n## Project commands\n\nThe generated `package.json` exposes these scripts:\n\n| Command | Purpose |\n| --- | --- |\n| `npm run dev` | Start Astro's development server |\n| `npm run validate` | Validate YAML and type-check the site |\n| `npm run build` | Validate, build, and stage production output |\n| `npm run preview` | Serve the staged static site or standalone locked server |\n| `npm run docsy -- doctor` | Check local prerequisites and deployment compatibility |\n| `npm run docsy -- --version` | Show recorded template version |\n| `npm run docsy -- upgrade --from <fresh-project>` | Write an upgrade comparison report; never apply changes |\n| `npm run docsy -- migrate mintlify --source <export> --out <new-project>` | Import a supported local Mintlify export without changing its source |\n| `npm run maintain -- plan --base <ref>` | Inspect source changes and likely documentation impact |\n| `npm run maintain -- run --base <ref>` | Run the agent and validate a local documentation update |\n\nArguments after the command are passed through to Astro where applicable.\n\nMintlify migration preserves native `.mdx` sources by default. Add `--format markdown` for the more limited plain-Markdown conversion. Imported MDX keeps JavaScript execution disabled; custom executable components require separate review and an explicit YAML opt-in.\n\n## Generate a project\n\nUse `npm exec --package @appgram/docsy@0.4.2 -- create-docsy my-docs --yes --ci` for the versioned npm CLI. In a template checkout, `npm run release:pack` prints an equivalent local-tarball creation command. `npm run create -- <directory>` is also available **in the template checkout**; generated sites use `npm run docsy -- create <directory>` when another project is needed. `npm run test:package` tests installation of the real tarball, not a dependency symlink to this checkout. Generation, packing and testing never publish a package.\n\n```text\ndocsy create <directory> [options]\ncreate-docsy <directory> [options]\n```\n\n| Option | Meaning |\n| --- | --- |\n| `--name <name>` | Product or API name |\n| `--openapi <source>` | OpenAPI JSON/YAML file or HTTPS URL |\n| `--api-base <url>` | Request base URL used in API examples |\n| `--base <path>` | Documentation mount path; defaults to `/docs` |\n| `--open` | Generate a public static site; this is the default |\n| `--locked` | Generate a server-rendered permission-gated site |\n| `--yes`, `-y` | Accept defaults without interactive prompts |\n| `--no-install` | Leave dependency installation to the caller |\n| `--ci` | Include validation and static-preview artifact workflow |\n| `--deploy none\\|github-pages` | Optional gated deployment workflow; default `none` |\n| `--repo <https://github.com/OWNER/REPO>` | Configure source links; required for Pages scaffolding |\n| `--force` | Replace an existing target directory |\n| `--help`, `-h` | Show command help |\n\nWithout `--yes`, the generator asks for the missing product, source, mount path, and access choices.\n\nPages scaffolding derives `site.origin`, `site.basePath`, and the home URL from the repository. It rejects locked mode. It never creates repositories or deploys; the owner must explicitly enable Pages and set `DOCSY_ENABLE_PAGES=true` when ready. Generated sites remain private packages and record template provenance under `.docsy/template.json`.\n\n## Validate configuration\n\n```bash\ndocsy validate\n```\n\nValidation expands environment placeholders, parses `docsy.config.yaml`, checks it against the configuration schema, and runs Astro's type and template checks. Invalid configuration reports the exact YAML path.\n\nIt also renders articles/components, expands snippets, checks API contracts and examples, loads SDK inputs, and verifies internal routes and heading anchors for each version/locale context. Production builds additionally check links in the generated static HTML. Validation does not execute examples against live services.\n\n`docsy check` is an alias for the same operation.\n\n## Build production output\n\n```bash\ndocsy build\n```\n\nThe build clears previous `dist/` and `release/` output, validates the project, runs the Astro build, and stages a production release.\n\n* Open mode with `agent.query: false` creates a static `dist/` build and a mount-aware `release/` directory.\n* Locked mode or `agent.query: true` creates the standalone Astro server in `dist/`; static staging is skipped. Run it on Node with `npm start` or on Bun with `npm run start:bun`.\n\n## Run production output\n\n```bash\ndocsy preview\n```\n\nUse `HOST` and `PORT` to change the listener:\n\n```bash\nHOST=0.0.0.0 PORT=8080 docsy preview\n```\n\n`docsy start` is an alias for the same operation.\n\n## Select another configuration\n\nEvery command reads `docsy.config.yaml` by default. Set `DOCSY_CONFIG` to select another project-relative file:\n\n```bash\nDOCSY_CONFIG=docsy.preview.yaml npm run build\n```\n\n## Maintain documentation\n\n```bash\ndocsy maintain plan --base HEAD~1\ndocsy maintain run --base HEAD~1\ndocsy maintain run --base HEAD~1 --pr --target-branch main\ndocsy maintain verify --base HEAD~1 --patch .docsy/maintenance/proposed.patch\n```\n\n`plan` compares committed revisions and writes an impact report and agent prompt under `.docsy/maintenance/`. It never calls a model. Use `--head <ref>` to select the comparison head; it defaults to `HEAD`.\n\n`run` requires a clean checkout, enabled YAML maintenance settings, and an authenticated Codex CLI. It updates documentation and runs independent validation, leaving the diff for review. `--pr` additionally commits to a dedicated branch, pushes, and opens a draft with the GitHub CLI. The target defaults to the repository's default branch.\n\n`verify` applies an optional patch in a clean checkout, enforces editable Markdown and YAML boundaries, and validates the site. The GitHub workflow uses this command in a fresh job before PR publishing. Failed validation produces no validated patch.\n\nSee **Documentation maintenance** for the YAML options, GitHub setup, and the distinction between structural API findings and agent review.\n\n","contentLocale":"en","isFallback":false,"authorship":{"authors":[{"name":"nedimf","kind":"human","github":"nedimf","avatar":"/docsy/assets/authors/nedimf.png","role":"AppGram","id":"nedimf","url":"https://github.com/nedimf"},{"name":"AppGram","kind":"organization","github":"AppGram","url":"https://appgram.dev","avatar":"/docsy/assets/ag-logo.svg","id":"appgram"}],"contributors":[],"reviewedBy":[]},"editUrl":"https://github.com/AppGram/docsy/edit/main/content/reference/cli.md"}