# Typemark CLI

> Create or download a project, edit it in your own editor, check it, and publish from the terminal or CI.

The `typemark` command lets you work on a project from your own editor: create or download it, edit the files, check them for problems, and push them back to publish. It also moves a Mintlify site to Typemark, and publishes from CI. It's on every plan.

You don't need it to use Typemark. The [editor](https://docs.typemark.dev/editor/visual-mode) does everything in your browser.

## Install

The CLI needs [Node.js](https://nodejs.org) 22 or later, on macOS, Linux or Windows.

```bash
npm install -g @gettypemark/cli
typemark --version
```

The package is `@gettypemark/cli`. The command it installs is `typemark`. To run it once without installing, use `npx @gettypemark/cli` in place of `typemark`.

### Updating

When a newer version is out, the CLI says so in one line after a command, at most once a day. It stays quiet with `--json`, in CI, and when its output isn't a terminal. To update:

```bash
npm install -g @gettypemark/cli@latest
```

If your version is too old for Typemark, commands stop with the error `cli_outdated` (exit code 6) and the same command to update.

## Sign in

```bash
typemark login
```

Your browser opens a Typemark page showing a code. Check that it matches the code in your terminal and click **Approve**. The terminal then says who you're signed in as.

A sign-in lasts six months. After that, run `typemark login` again. If your organization starts [requiring single sign-on](https://docs.typemark.dev/team/single-sign-on#require-single-sign-on), sign-ins and tokens from before stop working: run `typemark login` again and sign in through SSO. On a machine without a browser, run `typemark login --no-browser` and open the link it prints on any device.

The sign-in appears under **Account** > **API tokens** as "CLI on" followed by your computer's name. Revoke it there, or run `typemark logout` on that computer.

## Edit a project locally

<Steps>
  <Step title="Download the project">
    ```bash
    typemark projects          # lists the projects you can open
    typemark pull acme-docs    # downloads acme-docs into ./acme-docs
    cd acme-docs
    ```
  </Step>
  <Step title="Edit and preview">
    ```bash
    typemark dev
    ```
    Opens your site at `http://localhost:3333` while you edit in any editor. See [Preview locally](#preview-locally).
  </Step>
  <Step title="Check">
    ```bash
    typemark check
    ```
    Finds problems before readers see them. See [Checking your docs](#checking-your-docs).
  </Step>
  <Step title="Publish">
    ```bash
    typemark push --wait
    ```
    Uploads what you changed, added, or deleted as one change under your name, then publishes it like a save in the editor. `--wait` waits until the new version is live.
  </Step>
</Steps>

`typemark new guides/setup` creates a page and adds it to navigation. `typemark open` opens your site in the browser (`typemark open editor` opens the editor). `typemark status` shows the site's address, the last publish, and what you've changed locally. `typemark push --dry-run` lists what a push would send without sending it.

The site's address that `typemark projects`, `status` and `open` show is its own: your [custom domain](https://docs.typemark.dev/configuration/custom-domain) once it's verified, otherwise `https://{slug}.typemark.dev`.

A push publishes the pages it changes right away, like a push to a [connected GitHub repo](https://docs.typemark.dev/github/sync). That's true in [manual deploy mode](https://docs.typemark.dev/configuration/publishing#manual-deploy) too, so use `--dry-run` to see what's about to go live.

<Callout type="info">
  Pushing needs the editor or owner role. Viewers can pull. See [Team members](https://docs.typemark.dev/team/members#roles).
</Callout>

## Create a project

```bash
cd my-docs
typemark create "Acme Docs"
```

Creates a project named Acme Docs and links the folder you're in to it, so `typemark push`, `typemark status` and the other commands know which project to use. It's the same as **New project** on the dashboard: the project starts with a `typemark.json` and a few starter pages, and its site is [offline](https://docs.typemark.dev/configuration/publishing) until you publish it. Your plan's project limit applies. See [Billing](https://docs.typemark.dev/team/billing).

Then publish the folder in place of the starter pages:

```bash
typemark push --prune
```

Or start from the starter pages instead: in an empty folder, run `typemark pull`.

| Option | What it does |
|--------|--------------|
| `--slug acme` | Chooses the project's address. Without it, the address is made from the name, like `acme-docs`. |
| `--no-link` | Only creates the project. Link a folder to it later with `typemark link acme-docs`. |
| `--dir docs` | Links another folder instead of the one you're in |

A folder that's already linked to a project stays linked to it: `typemark create` stops without creating anything. Use `--no-link`, or `typemark link` to switch the folder to another project.

## Preview locally

```bash
typemark dev
```

`typemark dev` shows your folder at `http://localhost:3333` the way Typemark will publish it: the same layout, components, code highlighting, navigation, search, and brand colour. Saving, adding, deleting or renaming a file reloads the page; changes in `.git`, `node_modules` and what `.gitignore` or `.typemarkignore` ignore don't. It works offline and doesn't need you to sign in.

- A page that won't build shows the error and its line in place of the page.
- A page that isn't in navigation shows "Not published", because readers wouldn't be able to reach it. A [hidden page](https://docs.typemark.dev/configuration/navigation) opens, but isn't in the sidebar.
- On a site in [several languages](https://docs.typemark.dev/configuration/languages), each language is at its own address, such as `/fr/quickstart`, with the language picker, as on your site. A page without a translation shows the default language's text there.
- The terminal lists how many problems `typemark check` finds whenever that changes.

### API reference pages

Typemark generates the overview and endpoint pages of an [OpenAPI spec](https://docs.typemark.dev/api-reference/openapi). When you're signed in, `typemark dev` sends the spec to Typemark and shows the pages it answers, exactly as they'll be published. Only the spec is sent, and only when it changes. Signed out or offline, the reference shows a placeholder until you run `typemark login`.

A spec that won't parse shows its error in place of the reference, signed in or not, and `typemark check` reports it with its line. A page you wrote for an endpoint shows the endpoint the same way.

### Not in the preview

Some things only happen on your published site: [AI search](https://docs.typemark.dev/ai/ai-search) (the preview's search matches page text instead), the feedback widget, the page actions menu, "Powered by Typemark", and your custom code and integrations.

| Option | What it does |
|--------|--------------|
| `--port 4000` | Serves on another port. Without it, the next free port after 3333 is used. |
| `--host 0.0.0.0` | Makes the preview reachable from other devices on your network, like your phone |
| `--no-open` | Doesn't open the browser |

## Add a page

```bash
typemark new guides/setup --title "Set up Acme"
```

Creates `guides/setup.mdx` with a title, inside your `docs_root` if you have one, and adds it to navigation. Without `--group`, the page goes next to other pages in the same folder, or into the first group. `--group "Guides"` puts it in that group, creating the group if it doesn't exist; add `--tab` to pick the tab. `--no-nav` only creates the file.

### When someone else edits too

`typemark pull` remembers which version of each file it downloaded, in a `.typemark` folder that Git ignores. A push uses that to send only your changes.

- **Someone changed other files** on Typemark since your last pull: your push goes through, and the CLI tells you to run `typemark pull` to get their changes.
- **Someone changed the same file**: nothing is pushed. The CLI lists the files. Run `typemark pull` to get their version, then push again.

Run `typemark pull` in a downloaded folder to bring it up to date. It never overwrites a file you changed. When a file changed both locally and on Typemark, it stops and lists them. `typemark pull --force` then takes Typemark's version of those files, after saving yours in `.typemark/backup/`.

Some names Typemark stores can't be files on your computer: on Windows, names with `< > : " | ? *`, ending in a dot or space, or a reserved name like `con.mdx`; on macOS and Windows, two names that differ only in upper and lower case, like `Guide.mdx` and `guide.mdx`. `typemark pull` finds them before it writes anything, pulls everything else, and lists the files it left out and why. Rename them on Typemark, or in the connected repository, then pull again. Pushing from your folder leaves them as they are.

### Files that aren't pushed

Files matched by a `.gitignore` or `.typemarkignore` in the folder are never pushed, and neither are `.git`, `node_modules`, `.DS_Store`, `Thumbs.db` and `desktop.ini`. Add drafts or build output to `.typemarkignore` to keep them local.

A push can change up to 500 files and 50 MB at a time, with up to 10 MB per file.

On Windows, Git and many editors save text files with CRLF line endings. That doesn't count as a change: a push sends text with LF line endings, the way Git stores it, and images and other binary files exactly as they are.

### Projects connected to GitHub

If the project [syncs with GitHub](https://docs.typemark.dev/github/sync), GitHub is where its files live. `typemark pull`, `check`, and `status` work, but `typemark push` is refused. Commit and push to GitHub instead, and Typemark publishes from there.

## Checking your docs

`typemark check` reads your folder the way Typemark's build does and reports:

| Errors | Warnings |
|--------|----------|
| `typemark.json` missing or not valid JSON | Pages that aren't in navigation, so readers can't find them |
| Navigation entries with no matching page or OpenAPI file | Pages listed in navigation more than once |
| OpenAPI specs that won't parse, with the line | |
| MDX that won't build, with the line and column | Pages without a title in their frontmatter |
| Frontmatter that isn't valid YAML | Components Typemark doesn't render |
| Links to pages that don't exist (links to [API reference pages](https://docs.typemark.dev/api-reference/openapi) count as pages) | `import`/`export` statements and `{expressions}`, which are removed on publish |
| | Pages saved with a byte order mark, whose frontmatter Typemark can't read |
| | Pages whose [`openapi` endpoint](https://docs.typemark.dev/api-reference/openapi#write-an-endpoints-page) isn't in a spec, so they show only their own text |
| | File names Windows or macOS can't store, which `typemark pull` leaves out there |
| [`languages`](https://docs.typemark.dev/configuration/languages#check-before-you-publish) entries Typemark can't use, such as a code that isn't a language code or appears twice | `languages` with only one language, so the whole site is in it |
| | Pages in navigation inside a language's folder, which readers can't reach |
| | Translations, such as `fr/quickstart.mdx`, of pages that aren't in navigation |
| | A `translate` other than `"ai"` or `"manual"`, or a `translations.do_not_translate` that isn't a list |

Errors stop `typemark push`. Use `typemark check --strict` to fail on warnings too, for example in CI. `typemark push --no-check` pushes without checking.

## Migrate from another platform

The CLI converts a Mintlify, GitBook or ReadMe site in a folder on your computer, wherever the repository is hosted. To import from GitHub in the browser instead, see [Migrating to Typemark](https://docs.typemark.dev/migrating/overview).

```bash
cd my-old-docs
typemark login
typemark migrate             # detects the platform, converts the folder, then offers to create the project and push it
```

`typemark migrate` looks for `docs.json` or `mint.json` (Mintlify), `.gitbook.yaml` or `SUMMARY.md` (GitBook), or a `docs/` folder with `_order.yaml` files (ReadMe), at the root or up to two folders down. It converts them with the same code as the GitHub import, prints what it couldn't carry over, then runs `typemark check`. Add `--from mintlify`, `--from gitbook` or `--from readme` to skip detection, and `--dry-run` to see the result without writing anything.

- **Mintlify:** only `typemark.json` is written. Your pages and `docs.json` aren't changed. See [From Mintlify](https://docs.typemark.dev/migrating/mintlify).
- **GitBook and ReadMe:** pages are converted and moved in place, so the folder must be a Git repository with no uncommitted changes (`--force` skips that check). Review the result with `git diff`; `git checkout -- . && git clean -fd` undoes it. See [From GitBook](https://docs.typemark.dev/migrating/gitbook) and [From ReadMe](https://docs.typemark.dev/migrating/readme).

After converting, `typemark migrate` asks whether to create a Typemark project for the folder (named after your site; you can type another name) and link it, then whether to push it in place of the new project's starter pages (`typemark push --prune`, after `typemark check`). If `typemark check` finds errors, it doesn't offer the push: fix them, then run `typemark push --prune`. A new project's site stays offline until you publish it.

In scripts, CI or with a coding agent, pass the answers as flags instead: nothing is asked when output is `--json`, `CI` is set, or input isn't a terminal.

```bash
typemark migrate --create "My Docs" --push
```

If creating or pushing fails (your plan's project limit, an unconfirmed email address, check errors, an expired sign-in), your converted files stay as they are and the CLI says what to run next. To publish to a project you already have, run `typemark link my-project` before migrating, then `typemark migrate --push`, or `typemark push --prune` afterwards.

### With your coding agent

`typemark migrate --agent claude` starts your coding agent in the current folder with Typemark's migration guide as its instructions. It also works with `codex`, `cursor` and `gemini`, and with `--from` for any platform name and `--source` for where your docs are now: a folder, a repository or a live site.

```bash
typemark migrate --agent claude --from docusaurus --source ../old-docs
```

The agent runs on your computer under your own login. `typemark migrate --guide` prints the same instructions for any other agent. If the agent isn't installed, the CLI says how to install it; on Windows, Cursor installs from PowerShell with `irm 'https://cursor.com/install?win32=true' | iex`. See [With your coding agent](https://docs.typemark.dev/migrating/other).

## Publish from CI

To publish docs that live in another repository, such as a `docs/` folder in your product's repo, push them from CI on every merge:

<Steps>
  <Step title="Create a token">
    Create an [API token](https://docs.typemark.dev/automation/api#create-an-api-token) and store it as a CI secret named `TYPEMARK_TOKEN`.
  </Step>
  <Step title="Add a CI step">
    The folder isn't linked in CI, so name the project with `TYPEMARK_PROJECT`. With GitHub Actions:

    ```yaml
    - uses: actions/setup-node@v4
      with:
        node-version: 22
    - run: npx @gettypemark/cli push --prune --wait --message "docs: ${{ github.sha }}"
      working-directory: docs
      env:
        TYPEMARK_TOKEN: ${{ secrets.TYPEMARK_TOKEN }}
        TYPEMARK_PROJECT: acme-docs
    ```
  </Step>
</Steps>

Here the repository is the source of truth: `--prune` deletes pages on Typemark that the repository no longer has, and edits made in the Typemark editor are overwritten by the next push of the same file. Leave `--prune` out to only add and update.

If the push fails a check or the build fails, the step fails with the reason.

## Scripts and AI agents

Every command takes `--json`. The result is a single JSON document on stdout, and progress messages go to stderr. Errors look like this:

```json
{
  "error": {
    "code": "conflict",
    "exit_code": 5,
    "message": "1 file was also changed on Typemark since your last pull:\n  quickstart.mdx",
    "hint": "Nothing was pushed. Run `typemark pull` to see their version, then push again.",
    "conflicts": ["quickstart.mdx"]
  }
}
```

The codes are the [API's error codes](https://docs.typemark.dev/automation/api#errors), plus `usage` (the command line is wrong), `not_linked` (the folder isn't linked to a project), `already_linked` (`typemark create` in a folder linked to another project), `check_failed` (`typemark check` found errors), and `deploy_failed` (with `--wait`, the publish failed). Rely on `code` and the exit code; messages are written for people and may change.

### Exit codes

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | Something else went wrong: the network, the server, a project that isn't there, a plan limit, a publish that failed |
| `2` | The command line is wrong: an unknown command or option, a missing or extra argument, or a value that isn't allowed |
| `3` | `typemark check` found errors (or warnings, with `--strict`), or `typemark push` stopped because of them |
| `4` | You're not signed in, or your sign-in or `TYPEMARK_TOKEN` is revoked, expired, or older than your organization's single sign-on requirement: run `typemark login` or use a new token |
| `5` | A file changed both here and on Typemark: run `typemark pull`, then try again |
| `6` | This version of the CLI is too old: run `npm install -g @gettypemark/cli@latest` |

These codes never change meaning. New ones are only added for failures that already exit with a non-zero code.

## Commands

| Command | What it does |
|---------|--------------|
| `typemark login` | Signs in through your browser |
| `typemark logout` | Signs out and revokes the sign-in |
| `typemark whoami` | Shows who you're signed in as |
| `typemark projects` | Lists your projects |
| `typemark link [project]` | Links the current folder to a project |
| `typemark create <name>` | Creates a project and links the current folder to it |
| `typemark status` | Shows the site, the last publish, and your local changes |
| `typemark deployments` | Lists recent publishes, with the latest one's warnings, such as files your GitHub repository holds that the site ignores. `-n 20` shows more. |
| `typemark open [site\|editor\|settings]` | Opens the project in your browser. `--print` prints the address instead. |
| `typemark pull [project] [folder]` | Downloads a project into a new folder, or updates a linked one |
| `typemark push` | Uploads your changes and publishes them |
| `typemark new <page>` | Creates a page and adds it to navigation |
| `typemark dev` | Previews your docs locally, reloading on every save |
| `typemark check` | Finds problems before you push |
| `typemark migrate` | Converts a Mintlify, GitBook or ReadMe site and offers to create the project and push it (`--create`, `--push`), or starts your coding agent to migrate anything else |

Run `typemark help <command>` for its options.

## Settings

| Variable | Default | What it does |
|----------|---------|--------------|
| `TYPEMARK_TOKEN` | | An API token to use instead of `typemark login` |
| `TYPEMARK_PROJECT` | The linked project | The project to use. Same as `--project`. |
| `TYPEMARK_API_URL` | `https://typemark.dev` | The Typemark server to talk to. Same as `--api-url`. |
| `TYPEMARK_CONFIG_DIR` | `~/.config/typemark` | Where `typemark login` keeps its sign-in (`%APPDATA%\typemark` on Windows) |
