stx deploy
Deploy your documentation to the Syntext CDN.
Deploy your documentation to Syntext's global CDN with automatic SSL and instant cache invalidation.
Usage
Options
| Flag | Alias | Type | Default | Description |
|---|---|---|---|---|
--dir <dir> | -d | string | . | Documentation directory |
--preview | boolean | false | Deploy as a preview (non-production) | |
--branch <branch> | string | Branch name for a preview deploy. Requires --preview: without it, stx deploy stops with an error instead of deploying to production | ||
--token <token> | string | Login token or project API key (for CI, overrides stx login) | ||
--json | boolean | false | Output result as JSON | |
--promote [buildId] | string | Promote a preview deployment to production |
Examples
Production Deployment
Deploys to your production URL (e.g., your-project-docs.syntext.dev).
Preview Deployment
Without --branch (or with --branch main), the preview goes to preview--your-project-docs.syntext.dev — every branchless preview shares that address, so pass --branch in CI.
Branch Preview
Creates a branch-specific preview at feature-new-api--your-project-docs.syntext.dev. If <branch>--<subdomain> would be longer than 63 characters, the branch part is shortened and ends in a short code (for example …-page-m-e202f7--your-project-docs.syntext.dev) so the address stays valid; shorter branches keep their exact address. The deploy result prints the URL to use.
What gets uploaded
Your pages can live in docs/ or at the project root, next to syntext.json. stx deploy uploads them either way: it uses docs/ when that folder has .md or .mdx pages at its top level, otherwise the project root — the same rule as builds from a connected repository.
docs/ — everything in docs/._meta.json, _redirects.json and images, from any folder under the root. Folders and files that are not docs are left out: node_modules/, .git/, dist/, .next/, out/, build/, other dot folders, anything your .gitignore ignores, source code, package.json and lockfiles.docs.json, public/, your _syntext/ custom code, every OpenAPI spec the openapi key names (in any folder) and GraphQL, gRPC and AsyncAPI schemas. Without an openapi key, openapi.json, openapi.yaml or openapi.yml at the project root is uploaded if present.Never uploaded: .env files (.env, .env.local, …), private keys and certificates (*.pem, *.key, *.p12, *.pfx, id_rsa and similar) and credential files (credentials.json, .npmrc, .netrc).
| Error | Fix |
|---|---|
OpenAPI spec(s) declared in your config but not found | Fix the path in openapi, or add the file. Nothing is uploaded until every spec it names exists. |
Your pages are at the project root, and the files to upload from it come to … MB (the limit is 100 MB). | Move your pages into a docs/ folder, or add large files you don't need to .gitignore. |
Deployment Output
stx deploy uploads your source files — your pages, public/, the config and your _syntext/ custom code — then waits while the server builds and publishes them. The spinner shows each stage — Queued..., Preparing source..., Parsing documentation..., Compiling pages..., Deploying to CDN... — and ends with:
Waiting behind another build
Builds of one project run one at a time. If another build of the project is already running — typically the GitHub webhook's build of the merge you just pushed — your deploy waits for it, and the spinner names it:
The CLI waits up to 20 minutes in the queue, then up to 10 minutes for your build itself once it starts. If either wait runs out, it stops waiting and exits with code 1, but the build is not lost: it stays queued or keeps running on the server and publishes when it finishes. Follow it in the dashboard under Deployments.
If the build is cancelled while you wait, the CLI stops with the server's reason and exits with code 1. That includes a production build that was superseded — a production build requested after yours went live first, so yours did not publish over it:
See Build order. With --json, the message is the error field of { "success": false, "error": "…" }. Waiting behind another build needs CLI v0.8.1 or later (brew upgrade stx); earlier versions gave up after 2 minutes, often while the build was still queued.
Default Domain
Every project gets a free subdomain:
The slug is derived from your project name. For example, "My API" becomes my-api-docs.syntext.dev.
Custom Domains
Add a custom domain in the dashboard:
docs.yourcompany.com) and click Add domainSee Custom Domains for the full walkthrough.
Custom domains require the Starter plan or higher, and wildcard domains require Pro. See pricing for details.
Preview Deployments
Preview deployments are useful for:
Previews apply CSS from _syntext/, but never run its scripts or head.html — see Previews.
A preview's search index is dropped 14 days after the branch's last preview build (at most 10 are kept per project); search on that preview then returns no results until it builds again.
CI/CD Integration
GitHub Actions
GitLab CI
Authentication
stx deploy uses the credentials saved by stx login. In CI, pass a project API key with --token instead — it overrides stx login:
Create the key in your project → Settings › API keys in the dashboard (https://app.syntext.dev/projects/<project-id>/settings/api-keys) with the build scope. The full key is shown only once, right after you create it. The CLI does not read an API key from an environment variable on its own — keep it in a CI secret and pass it with --token, as in the examples above.
Rollbacks
To put an earlier production version back live, open Deployments, choose Roll back on a build that deployed (or on the Serving production card), and confirm Roll back production. From the API, use Roll Back Deployment.
stx deploy can only be rebuilt from the newest upload on their branch; for older ones, redeploy that version from the CLI.An instant rollback never races a build: while a build of the project is running, or a production build is queued, it is refused (409 build_in_progress) and nothing changes. Cancel that build from Deployments — or wait for it — then roll back. A production build you start after a rollback replaces it when it deploys, like any newer deploy.
You can also restore an earlier version the usual ways:
Promote queues a new production build from the files that preview was deployed with, and counts toward the build quota.
Global delivery
Your doc site is served from a global CDN:
Static assets are cached indefinitely with content-based hashes. HTML is revalidated on every request, so a deploy is visible on the next request — no purge step.