npx outworx push from any CI runner.
@outworx/cli is the CI-friendly way to publish specs. Zero install graph, ~30KB tarball, instant npx cold-start. Token-prefix sniffing routes PATs to the v1 API (preview pushes work) and upload tokens to the project endpoint. Three-line GitHub Action wrapper for Marketplace use.
$ npx @outworx/cli push openapi.yaml \
--project payments-api --preview \
--pr 247 --commit $GITHUB_SHA --branch $GITHUB_HEAD_REF
Pushing openapi.yaml (12.4 KB) → payments-api @ pr-247 (preview)
✓ Preview published.
Parsed: 47 endpoints, 12 schemas, 4 tags.
Preview: docs.outworx.io/payments-api/preview/247
$ echo $?
0
$
outworx/upload-spec-action@v10 deps
Hand-rolled argv parser
~30 KB
Total tarball size
3 lines
GitHub Action workflow YAML
0/1/2/3
Scriptable exit codes
Token-prefix routing
One CLI, two trust models.
Personal access tokens are account-scoped — they authorize whatever the owning user can do, across every project they own or collaborate on. Upload tokens are project-scoped — one verb, one project. The CLI sniffs the prefix and routes accordingly.
Personal access token
otwx_pat_*Routes to: POST /api/v1/projects/<slug>/versions
- Multi-project pushes from one token
- Preview pushes (`--preview --pr 42 --commit … --branch …`)
- Full v1 API surface (PATCH / DELETE / list)
- Audit-log events stamp `metadata.token_id`
Project upload token
otwx_*Routes to: POST /api/projects/<slug>/upload
- Single-project, single-verb scope
- Spec uploads only — no other API access
- Rotatable freely without affecting account access
- Preview pushes are rejected upfront with a clear error
Scriptable exit codes
CI can pattern-match the exit code, not the log line.
Every failure mode maps to a stable exit code. Workflows decide retry policy without parsing stdout. The composite GitHub Action passes through whatever the CLI returned, so your if: failure() rules see the underlying signal.
`exit 1` for user error: bad flag, missing spec file, validation failure. Don't retry — fix the input.
`exit 2` for transient errors: 4xx/5xx, network timeout, ECONNREFUSED. Safe to retry with backoff.
`exit 3` for internal errors: unexpected throws. Set `DEBUG=1` to capture the stack trace.
| Code | Meaning | CI retry |
|---|---|---|
| 0 | Success — spec uploaded, version updated | — |
| 1 | User error — bad flag, missing file, validation | No (fix input) |
| 2 | Transient — 4xx/5xx, network, timeout | Yes (with backoff) |
| 3 | Internal — unexpected throw, set DEBUG=1 | Investigate |
Config precedence
Flag wins. Env wins. Config wins. Default loses.
Standard four-level resolution. The config-file walker discovers outworx.json or .outworxrc.json upward from cwd — same eslint-style discovery your team already understands. Monorepo with one config at the root works without per-package configuration.
| Priority | Source | Example |
|---|---|---|
| #1 | --flag | outworx push spec.yaml --project payments-api |
| #2 | Env var | OUTWORX_PROJECT=payments-api |
| #3 | Config file | outworx.json → { "project": "payments-api" } |
| #4 | Default | (no default for required values) |
Plan tiers
CLI is free. Some flags need a paid plan.
Free
Full CLI
- `outworx push <spec>` to any project you own
- Account-level PATs
- GitHub Action wrapper
- Auto-sync on every commit to main
Pro
+ PR previews
- Everything in Free
- `--preview` push for PR deploys
- 5 active previews per project
- Preview banner with PR / commit / branch
Business
+ audit
- Everything in Pro
- 20 active previews per project
- Every CLI push writes an audit-log row
- `metadata.token_id` for forensic trace
Pairs well with
PR Preview Deploys
The `--preview` flag is what turns a regular push into a per-PR docs URL. Three lines in your workflow YAML; reviewers click through.
Spec Diff
Pair the CLI push with the spec-diff Action so every PR gets both the rendered preview AND a breaking-change comment in one workflow.
Audit Log
API tokens used by the CLI stamp `metadata.token_id` on every event. A leaked-token trace is one indexed query — not a log scan.
Three lines in your workflow. Done.
CLI is free on every plan. Mint a personal access token, drop the GitHub Action into .github/workflows/docs.yml, and your spec stays in sync forever.