@outworx/cli

Push OpenAPI / Swagger / GraphQL specs to Outworx Docs from CI or your laptop.

npx @outworx/cli push openapi.yaml --project payments-api

Install

# One-shot (recommended for CI):
npx @outworx/cli push ...

# Or globally:
npm install -g @outworx/cli
outworx push ...

Requires Node.js 18.17+.

Authentication

Two token shapes — pick whichever matches your scope:

| Token | Prefix | Scope | Best for | | --- | --- | --- | --- | | Personal access token | otwx_pat_* | Account-wide; acts as the user who minted it | Multi-project CI, shared secrets, preview deploys | | Project upload token | otwx_* | Single project, spec upload only | Per-repo CI on one project |

Mint either one in Settings. Pass via --token or, recommended, the OUTWORX_TOKEN env var:

export OUTWORX_TOKEN=otwx_pat_...
outworx push openapi.yaml --project payments-api

Usage

Basic push to default version

outworx push openapi.yaml --project payments-api

Push to a specific version

outworx push openapi.yaml --project payments-api --version v2-beta

PR preview push (requires a PAT)

outworx push openapi.yaml \
  --project payments-api \
  --preview \
  --pr 42 \
  --commit "$GITHUB_SHA" \
  --branch "$GITHUB_HEAD_REF"

Preview pushes are filtered out of the public docs picker, never become the default, and expire 14 days after the PR closes.

Configuration

The CLI looks for outworx.json (or .outworxrc.json) in the current directory and walks up to the filesystem root, picking up the first match. Useful for pinning the project + base URL once per repo:

{
  "project": "payments-api",
  "version": "v1",
  "baseUrl": "https://docs.outworx.io"
}

Precedence (highest wins): CLI flag → env var → config file → built-in default.

Environment variables

| Var | Maps to | | --- | --- | | OUTWORX_TOKEN | --token | | OUTWORX_PROJECT | --project | | OUTWORX_BASE_URL | --base-url |

Exit codes

| Code | Meaning | | --- | --- | | 0 | Success | | 1 | User error — bad flag, missing file, 4xx response | | 2 | Network or transient API error (5xx, ECONNREFUSED). Safe to retry. | | 3 | Internal error — please open an issue with DEBUG=1 output |

GitHub Action

If you're using GitHub Actions, prefer the abdallaemadeldin/upload-spec-action wrapper instead — same flags, less YAML.

Docs

• CLI guide
• REST API reference
• Audit log guide