Typemark Documentation

Typemark CLI

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

Actualizado el 19 nov 202612 min de lectura

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 does everything in your browser.

Install

The CLI needs Node.js 22 or later, on macOS, Linux or Windows.

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:

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

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, 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

  1. Download the project

    typemark projects          # lists the projects you can open
    typemark pull acme-docs    # downloads acme-docs into ./acme-docs
    cd acme-docs
  2. Edit and preview

    typemark dev

    Opens your site at http://localhost:3333 while you edit in any editor. See Preview locally.

  3. Check

    typemark check

    Finds problems before readers see them. See Checking your docs.

  4. Publish

    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.

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 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. That's true in manual deploy mode too, so use --dry-run to see what's about to go live.

Create a project

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 until you publish it. Your plan's project limit applies. See Billing.

Then publish the folder in place of the starter pages:

typemark push --prune

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

OptionWhat it does
--slug acmeChooses the project's address. Without it, the address is made from the name, like acme-docs.
--no-linkOnly creates the project. Link a folder to it later with typemark link acme-docs.
--dir docsLinks 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

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 opens, but isn't in the sidebar.
  • On a site in several 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. 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 (the preview's search matches page text instead), the feedback widget, the page actions menu, "Powered by Typemark", and your custom code and integrations.

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

Add a page

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, 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:

ErrorsWarnings
typemark.json missing or not valid JSONPages that aren't in navigation, so readers can't find them
Navigation entries with no matching page or OpenAPI filePages listed in navigation more than once
OpenAPI specs that won't parse, with the line
MDX that won't build, with the line and columnPages without a title in their frontmatter
Frontmatter that isn't valid YAMLComponents Typemark doesn't render
Links to pages that don't exist (links to API reference pages 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 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 entries Typemark can't use, such as a code that isn't a language code or appears twicelanguages 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.

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.
  • 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 and From 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.

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.

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.

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:

  1. Create a token

    Create an API token and store it as a CI secret named TYPEMARK_TOKEN.

  2. Add a CI step

    The folder isn't linked in CI, so name the project with TYPEMARK_PROJECT. With GitHub Actions:

    - 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

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:

{
  "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, 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

CodeMeaning
0Success
1Something else went wrong: the network, the server, a project that isn't there, a plan limit, a publish that failed
2The command line is wrong: an unknown command or option, a missing or extra argument, or a value that isn't allowed
3typemark check found errors (or warnings, with --strict), or typemark push stopped because of them
4You'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
5A file changed both here and on Typemark: run typemark pull, then try again
6This 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

CommandWhat it does
typemark loginSigns in through your browser
typemark logoutSigns out and revokes the sign-in
typemark whoamiShows who you're signed in as
typemark projectsLists 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 statusShows the site, the last publish, and your local changes
typemark deploymentsLists 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 pushUploads your changes and publishes them
typemark new <page>Creates a page and adds it to navigation
typemark devPreviews your docs locally, reloading on every save
typemark checkFinds problems before you push
typemark migrateConverts 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

VariableDefaultWhat it does
TYPEMARK_TOKENAn API token to use instead of typemark login
TYPEMARK_PROJECTThe linked projectThe project to use. Same as --project.
TYPEMARK_API_URLhttps://typemark.devThe Typemark server to talk to. Same as --api-url.
TYPEMARK_CONFIG_DIR~/.config/typemarkWhere typemark login keeps its sign-in (%APPDATA%\typemark on Windows)