Typemark CLI
Create or download a project, edit it in your own editor, check it, and publish from the terminal or CI.
2026年11月19日更新12分で読めます
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
Download the project
typemark projects # lists the projects you can open typemark pull acme-docs # downloads acme-docs into ./acme-docs cd acme-docsEdit and preview
typemark devOpens your site at
http://localhost:3333while you edit in any editor. See Preview locally.Check
typemark checkFinds problems before readers see them. See Checking your docs.
Publish
typemark push --waitUploads what you changed, added, or deleted as one change under your name, then publishes it like a save in the editor.
--waitwaits 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.
| 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
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 checkfinds 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.
| 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
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 pullto get their changes. - Someone changed the same file: nothing is pushed. The CLI lists the files. Run
typemark pullto 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:
| 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 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 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.
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.jsonis written. Your pages anddocs.jsonaren'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 (
--forceskips that check). Review the result withgit diff;git checkout -- . && git clean -fdundoes 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:
Create a token
Create an API token and store it as a CI secret named
TYPEMARK_TOKEN.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
| 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) |