Preview a build

soxom preview is the headline CLI command. It takes your local openapi.yaml + soxom.yaml, packages them up, ships them to Soxom, runs the same generators a production build would, and downloads the resulting SDK to your machine. No commit, no push, no PR — just a fast loop while you iterate on your spec.

End-to-end flow

1. Bundle. The CLI walks your project directory and tars up openapi.yaml, soxom.yaml, and any local files referenced by $ref.

2. Upload. The bundle is uploaded to Soxom’s API as a single pre-authenticated PUT.

3. Build. Soxom enqueues a preview build using the same worker pipeline that powers production builds. Logs stream back to your terminal in real time.

4. Download. On success, Soxom returns a presigned URL for the generated SDK archive. The CLI downloads and extracts it into your output directory.

A preview build looks just like a normal build to the platform — same generator, same soxom.yaml semantics, same diagnostics. The only difference is that it’s tagged is_preview = true, doesn’t open a PR, and is garbage-collected after seven days.

Usage

soxom preview --target typescript

From the project root. The CLI picks up your auth token from soxom login (see Authenticate).

Flags

Flag	Description
--target <lang>	Required. One of typescript, python, java, go.
--out <dir>	Output directory. Defaults to ./previews/{language}/{sdk-name}-{UTC timestamp}.
--org <slug>	Organization slug to bill the preview to. Defaults to the only org you belong to.
--project <slug>	Project slug. Defaults to inferring from soxom.yaml’s sdk.name.

The output dir’s timestamp is UTC in YYYYMMDDTHHMMSSZ format, so directory listings sort chronologically.

Multi-file specs and $ref

The CLI follows local $refs when bundling — anything under your project directory referenced from openapi.yaml (or recursively from referenced files) is included in the upload.

Caution

Only local refs are supported. http://, https://, and file:// refs are rejected at bundle time with a clear error. If your spec depends on external schemas, pre-bundle them locally (e.g. with redocly bundle or openapi-format) before running soxom preview.

This restriction exists for two reasons: the preview pipeline must be reproducible (external URLs may change between runs), and Soxom doesn’t fetch arbitrary URLs from your build environment for security.

Bundle limits

Limit	Value
Compressed size	50 MB
File count	200 files

If you hit either limit, the CLI errors out before uploading. Almost everyone with reasonable spec hygiene stays well under both — the limits exist to catch accidental tar-up of node_modules or build artifacts. Add those paths to .gitignore; soxom preview honors it.

Subscription requirement

Preview builds run against the production generators and consume compute, so you need an active subscription (any paid plan) on the Organization you’re previewing against. The CLI returns a clear error and links you to the dashboard if your org isn’t on a paid plan.

The free tier intentionally doesn’t include previews — push to a Config Repository instead. See Plans & Billing for the breakdown.

Streaming logs

Preview builds stream the generator’s stdout/stderr live, so you see the same output a production build would write to the dashboard’s Builds view:

[10:42:01] queued build sxb_01HV…
[10:42:03] starting generator (typescript@2.4.1)
[10:42:03] parsing spec
[10:42:04] running schema synthesis
[10:42:05] writing src/api.ts
[10:42:06] running tsc
[10:42:08] build succeeded
[10:42:08] downloading artifact (1.2 MB)
[10:42:09] extracted to ./previews/typescript/petstore-sdk-20260529T104209Z

Ctrl+C cancels the build server-side; partial output isn’t downloaded.

Common errors

”Bundle exceeds 50 MB”

You’re almost certainly shipping something accidentally — check that node_modules, build outputs, or large fixtures aren’t being picked up. Add them to .gitignore.

”External $ref not allowed”

See above — pre-bundle external schemas.

”Active subscription required”

Either your org isn’t on a paid plan, or your subscription has lapsed. Manage it from the dashboard.

”Quota exceeded for preview builds”

Each plan has a soft monthly limit on preview builds. The error message includes the cap and your current usage; upgrade or wait until the next billing cycle.

”Bundle could not be extracted”

The server rejected the tar. Usually means a symlink escapes the project root, or the archive contains absolute paths. Re-run with --debug for the full server-side diagnostic.

Next steps

• Command reference
• Errors & Troubleshooting
• Workflow — Config Repository — when to preview vs. when to push.