/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
CLI CLI Reference stx deploy

stx deploy

Deploy your documentation to the Syntext CDN.

7 min read

Deploy your documentation to Syntext's global CDN with automatic SSL and instant cache invalidation.

Usage

bash
stx deploy [options]

Options

FlagAliasTypeDefaultDescription
--dir <dir>-dstring.Documentation directory
--previewbooleanfalseDeploy as a preview (non-production)
--branch <branch>stringBranch name for a preview deploy. Requires --preview: without it, stx deploy stops with an error instead of deploying to production
--token <token>stringLogin token or project API key (for CI, overrides stx login)
--jsonbooleanfalseOutput result as JSON
--promote [buildId]stringPromote a preview deployment to production

Examples

Production Deployment

bash
stx deploy

Deploys to your production URL (e.g., your-project-docs.syntext.dev).

Preview Deployment

bash
stx deploy --preview

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

bash
stx deploy --preview --branch feature/new-api

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.

•
Pages in docs/ — everything in docs/.
•
Pages at the project root — your pages, _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.
•
Always — your config file, 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).

ErrorFix
OpenAPI spec(s) declared in your config but not foundFix 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:

text
✔ Deployed successfully!
Build: a1b2c3d4
URL: https://your-project-docs.syntext.dev
Pages: 47
Duration: 4523ms

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:

text
⠋ Waiting for build 1a2b3c4d (a push, commit abc1234, compiling) to finish...

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.

text
✖ Deploy failed
Build 9f8e7d6c is still queued after 20 minutes, behind build 1a2b3c4d. It stays queued and publishes when it runs; 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:

text
✖ Deploy failed
Superseded: build 5c4b3a29 was requested later and is already live, so this build did not publish

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:

text
{project-slug}-docs.syntext.dev

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:

1.
Open your project → Settings › Domains
2.
Enter your domain (e.g., docs.yourcompany.com) and click Add domain
3.
Configure DNS — the CNAME plus the TXT records listed under the domain:
text
CNAME docs → cname.syntext.dev
4.
SSL certificate is provisioned automatically

See Custom Domains for the full walkthrough.

Tip

Custom domains require the Starter plan or higher, and wildcard domains require Pro. See pricing for details.

Preview Deployments

Preview deployments are useful for:

•
PR reviews — Review doc changes before merging
•
Staging — Test with production-like environment
•
Client feedback — Share work-in-progress with stakeholders

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

yaml
name: Deploy Docs
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install stx
run: curl -fsSL https://get.syntext.dev | sh
- name: Deploy
run: |
if [ "${{ github.event_name }}" = "pull_request" ]; then
stx deploy --preview --branch "${{ github.head_ref }}" --token "$SYNTEXT_TOKEN"
else
stx deploy --token "$SYNTEXT_TOKEN"
fi
env:
SYNTEXT_TOKEN: ${{ secrets.SYNTEXT_TOKEN }}

GitLab CI

yaml
deploy:
image: ubuntu:latest
before_script:
- apt-get update && apt-get install -y curl
script:
- curl -fsSL https://get.syntext.dev | sh
- stx deploy --token "$SYNTEXT_TOKEN"
only:
- main

Authentication

stx deploy uses the credentials saved by stx login. In CI, pass a project API key with --token instead — it overrides stx login:

bash
stx deploy --token "$SYNTEXT_TOKEN"

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.

•
Instant — Syntext keeps the last 5 production deploys. If the version you pick is one of them, the live site switches straight back to it: nothing is rebuilt, and it doesn't count toward your monthly build quota. Search and the assistant update on the next build — until then they keep answering from the newest content, and that next build re-indexes everything.
•
Rebuild — if that deploy is no longer kept (or predates instant rollbacks), Syntext queues a new production build of that version instead. It counts toward the build quota like any build, and production switches once it deploys. Builds uploaded with 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:

•
Git-connected projects — revert the commit and push; the push deploys to production as usual.
•
Preview deployments — promote a known-good preview from Deployments › Previews → Promote, or from the CLI:
bash
stx deploy --promote <buildId>

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:

•
300+ locations worldwide
•
< 50ms TTFB in most regions
•
Automatic compression (gzip, brotli)
•
HTTP/3 support
•
DDoS protection included

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.

Was this page helpful? Yes No
Previous
Product
Resources
Company
© 2026 SyntextBuilt with Syntext