--- title: CLI reference description: Use the Thally CLI to create, preview, check, migrate, translate, and publish documentation projects. url: https://pr-6-a9c4e9fe1b6c.thally.app/guides/cli-reference --- # CLI reference Use the Thally CLI to create, preview, check, migrate, translate, and publish documentation projects. The generated project includes `@thallylabs/cli`, so you can run the unified CLI with `npx thally` from the project root. The command keeps routine work focused on content and configuration instead of Next.js internals. ```bash npx thally ``` ## Commands | Command | What it does | | --- | --- | | `thally init [dir]` | Create a project with `create-thally-docs`. | | `thally dev` | Start the local documentation server. | | `thally build` | Build the production site. | | `thally start` | Serve a completed production build. | | `thally deploy [--prod] [--cloudflare]` | Build and deploy with Vercel or Cloudflare Workers. | | `thally check [--agents] [--fix] [--ci] [--external] [--drift]` | Validate content and optional agent-readiness checks. | | `thally new PAGE_ID` | Create an MDX page and register it in `docs.json`. | | `thally migrate SOURCE [dir]` | Import a documentation repository or public site. | | `thally translate --locale LOCALE` | Generate or refresh a translated content tree. | | `thally mcp` | Start the local MCP server over standard input/output. | | `thally agent "INSTRUCTION"` | Draft a documentation change for review. | | `thally track add`, `list`, `test`, or `setup` | Connect product-repository changes to documentation work. | | `thally starter update [--apply]` | Review or apply an immutable starter runtime update. | Run `npx thally` with no command to see the current command list. For detailed agent and tracking workflows, see [Draft updates with the docs agent](/guides/docs-agent) and [Turn product changes into docs pull requests](/guides/thally-track). ### Update the starter runtime ```bash npx thally starter update npx thally starter update --apply ``` The first command prints the release plan without changing files. Review that plan and your working tree, then pass `--apply` to update framework-owned files. Your authored content and configuration remain separate from the runtime snapshot. ### Preview and build ```bash npx thally dev npx thally build npx thally start ``` `dev` starts the project server. `build` creates the production output, and `start` serves an existing production build. ### Add and check content ```bash npx thally new guides/invite-a-member \ --title "Invite a team member" \ --description "Add a teammate and choose their role." npx thally check ``` `new` creates the MDX file and registers it in the last group of the first content tab. `check` validates the project. Add `--ci` for GitHub annotations, `--external` to check external links, `--drift` to evaluate provenance, or `--agents` to include the Agent Readiness Score. ### Deploy ```bash npx thally deploy --prod # Vercel npx thally deploy --cloudflare # Cloudflare Workers ``` The deploy command builds the provider-specific artifact before it publishes. Use the dedicated [deployment guides](/guides/deploying) when you need host configuration, durable storage, or a repeatable CI workflow. ## Scaffold with create-thally-docs Use `create-thally-docs` directly when you are creating or migrating a project: ```bash npx create-thally-docs@latest [command] [args] [options] ``` --- ### Create a project Creates a new Thally documentation project. ```bash npx create-thally-docs my-docs ``` The CLI walks through an interactive setup: - **Project name** — displayed in the header and metadata - **Description** — used for SEO and OpenGraph tags - **Brand preset** — `primary` (green) or `secondary` (purple) - **GitHub repo URL** — auto-wires Support and GitHub links - **Install dependencies now** — optional; skip it for a faster scaffold and run `npm install` later Skip all prompts and accept defaults with `--yes`: ```bash npx create-thally-docs my-docs --yes ``` ### Options | Flag | Description | |------|-------------| | `--yes`, `-y` | Accept all defaults, skip interactive prompts | | `--install` | Install project dependencies after scaffolding | | `--no-install` | Skip dependency installation without prompting | --- ## Migrate existing documentation Migrates a public documentation URL or GitHub documentation repository into a Thally project. ```bash npx create-thally-docs migrate [output-dir] [options] ``` For repository sources, Thally clones and reads the source content directly. For live sites, it discovers machine-readable indexes, sitemaps, and same-origin documentation navigation. Both paths produce the same ready-to-run Thally project. **Dedicated adapters:** Mintlify and Docusaurus. Automatic detection can also import repositories with plain Markdown or MDX and crawl a public docs site, but it does not promise framework-specific configuration parity for other platforms. > **Note:** A GitHub repository is the recommended source for auto-platform migrations because it exposes the original content, navigation, assets, OpenAPI files, redirects, and configuration. ### Examples ```bash # Recommended: auto-detect from the source repository npx create-thally-docs migrate https://github.com/org/repo my-docs # Use a live site when the repository is unavailable npx create-thally-docs migrate https://relay.dev/ relay-docs --max-pages 1000 # Run the same Docusaurus migration without prompts npx create-thally-docs migrate https://relay.dev/ relay-docs --platform docusaurus --max-pages 1000 --yes # Trial a large live site with at most 100 pages npx create-thally-docs migrate https://docs.example.com example-docs --max-pages 100 # Derive the output dir from the repo name npx create-thally-docs migrate https://github.com/mintlify/starter # Migrate a specific branch or subdirectory npx create-thally-docs migrate https://github.com/org/repo/tree/main/docs my-docs # Migrate content into an existing Thally project npx create-thally-docs migrate https://github.com/org/repo --into ./existing-docs ``` ### What gets migrated - All `.md` and `.mdx` files are copied and converted to clean MDX - Live-site pages are discovered from machine-readable indexes, sitemaps, and rendered sidebars within the submitted docs path - Navigation structure is detected from rendered Mintlify/Docusaurus navigation, `mint.json`, `docusaurus.config.js`, `docs.json`, or the directory structure - Docusaurus current-version boundaries, case-sensitive routes, redirects, nested docs plugins, callouts, tabs, tables, and highlighted code are preserved - OpenAPI spec files (`.json`, `.yaml`) are detected and wired up as an API Reference tab - Platform-specific MDX components are normalized to Thally equivalents (see [component mapping](#component-mapping) below) ### Options | Flag | Description | |------|-------------| | `--max-pages ` | Import at most 1–1,000 content pages from a public docs URL (default: 1,000) | | `--into ` | Migrate into an existing Thally project instead of scaffolding a new one | | `--branch ` | Override the auto-detected git branch | | `--docs-dir ` | Override the auto-detected docs subdirectory | | `--platform ` | Select `mintlify`, `docusaurus`, or `auto` | | `--api-key ` | Anthropic API key for converting non-Markdown files (e.g. `.rst`). Falls back to `ANTHROPIC_API_KEY` env var | | `--yes`, `-y` | Accept defaults and live-site limitations, then skip all prompts | > **Warning:** If an interactive auto-platform migration starts from a live URL, the CLI offers to switch to the recommended GitHub repository flow. Continuing with the URL requires confirmation that the result may need manual alignment and suggests using the Thally MCP server to finish the alignment in a PR. `--platform auto` and `--yes` remain non-interactive and print the same warning. ### Component mapping Thally renders common Mintlify components directly. The importer only renames syntax that does not share the same component name: | Source | Thally equivalent | |--------|---------------| | `` | `` | | `` | `` | | `` | `` | | `` | `` | | `` | stripped (children kept) | | `` | `` | | `` / `` | Markdown property definition | | `` / `` | `` | | `` | `` | | Docusaurus `:::note` / `:::tip` | `` | | Docusaurus `:::warning` / `:::caution` | `` | | Docusaurus `:::danger` | `` | | Docusaurus `` | `` | > **Note:** Files in `.rst` or other formats require an Anthropic API key to convert. Set `ANTHROPIC_API_KEY` in your environment or pass `--api-key`. Plain `.md` and `.mdx` files are migrated for free. See [Migrate and publish existing documentation](/guides/migrating) for the complete workflow from a live site to a managed Thally Cloud deployment. --- ## Check a project Lints a Thally project for common issues and reports errors and warnings. ```bash npx create-thally-docs check [project-dir] ``` Defaults to the current directory if no path is given. ### What it checks | Issue | Severity | |-------|----------| | Page listed in `docs.json` but no MDX file found | Error | | Duplicate page ID in `docs.json` | Error | | Tab with no groups and no `href` | Error | | MDX file not listed in `docs.json` (orphan) | Warning | | Missing `title` in frontmatter | Warning | | Missing `description` in frontmatter | Warning | | Empty or near-empty page body | Warning | ```bash # Check the current project npx create-thally-docs check # Check a specific directory npx create-thally-docs check /path/to/my-docs # Auto-fix orphan files by adding them to the nav npx create-thally-docs check --fix ``` The CLI exits with code `1` if any errors are found, `0` if the project is clean or only has warnings. ### Options | Flag | Description | |------|-------------| | `--fix` | Auto-add orphan pages to the last group of the first content tab | --- ## Translate content Translates documentation pages to a secondary locale using Claude AI. Requires an `i18n` block in `docs.json`. ```bash npx create-thally-docs translate --locale es ``` Translated files are written to `src/content/{locale}/` for you to review and commit — no runtime cost, full SSG. ### Examples ```bash # Translate all pages to Spanish npx create-thally-docs translate --locale es # Translate specific pages only npx create-thally-docs translate --locale fr --pages introduction,guides/getting-started # Overwrite existing translations npx create-thally-docs translate --locale es --force # Pass API key explicitly npx create-thally-docs translate --locale de --api-key sk-ant-... ``` ### Options | Flag | Description | |------|-------------| | `--locale ` | Target locale code — required (must be in `docs.json` i18n config) | | `--pages ` | Comma-separated page IDs to translate (omit for all pages) | | `--force` | Overwrite existing translation files | | `--api-key ` | Anthropic API key (falls back to `ANTHROPIC_API_KEY` env var) | | `--model ` | Claude model to use (default: `claude-sonnet-4-6`) | | `--yes`, `-y` | Skip confirmation prompt | See [Multi-Language Support](/guides/multi-language) for full setup instructions.