@ossy/cli

Unified CLI for the Ossy platform: app dev/build and CMS workflows.

Commands

| Command | Description | |---------|-------------| | init [dir] | Scaffold a new Ossy app (default: current directory) | | dev | Start dev server with watch (uses src/*.page.jsx or src/pages.jsx, src/config.js) | | build | Production build | | publish | Queue a container deployment via @ossy/deployment-tools (temporary; see below), then upload resourceTemplates and site build artifacts (S3 presign + CMS resource) when workspaceId is set | | cms upload | Upload resource templates only (same API as publish’s upload step) | | cms validate | Validate ossy config and resource templates |

App: dev & build

npx @ossy/cli dev
npx @ossy/cli build

Options: --pages, --config, --destination. See @ossy/app for details.

Publish (container / website)

Publishes a site by sending a deployment request to your platform queue (same as npx @ossy/deployment-tools deployment deploy). Run from the website package directory (where src/config.js lives) so domain/platform can be read automatically.

Temporary: no execution of src/config.js for CMS steps

After deploy succeeds, publish still needs workspaceId, apiUrl (optional, for absolute URLs), and resourceTemplates from src/config.js. Those values are not loaded with import() anymore: running the real config in plain Node would execute imports such as @ossy/themes, which are only meant to be resolved during ossy build (Rollup).

Instead, the CLI uses a temporary pipeline:

• workspaceId and apiUrl — read with string-literal regexes (same idea as deploy hints).
• resourceTemplates — parsed with @babel/parser from export default { … } when that array is JSON-like literals only (no function calls, variables, spreads, or template literals in that subtree).

If resourceTemplates cannot be extracted, template upload is skipped. This is a stopgap until publish is driven by build output or platform events (see Future direction).

Future direction (planned)

The explicit deployment deploy step (SQS / deployment queue from @ossy/deployment-tools) is intended to go away: the platform should react to a website upload / artifact event (e.g. after the container image or site bundle is published) and roll out without the CLI calling deploy. When that exists, publish can shrink to CMS-only steps (resource templates + site artifacts), or those can move to separate workflows entirely. Treat the current deploy + follow-ups combo as temporary coupling.

Details:

cd packages/my-website
npx @ossy/cli publish \
  --username <github-username> \
  --authentication <github-or-deploy-token> \
  --cms-authentication <ossy-api-jwt> \
  --platforms-path ../infrastructure/platforms.json \
  --deployments-path ../infrastructure/deployments.json

• --cms-authentication — Ossy API JWT (from the app’s API tokens) for POST /resource-templates and site-artifacts. If omitted, --authentication is used for CMS calls too (only works when that value is already a valid Ossy JWT). In GitHub Actions, set repo secret OSSY_API_KEY and pass --cms-authentication explicitly; the deploy token is usually not valid for the API.

Unifying deploy and CMS authentication (future)

--authentication and --cms-authentication exist because deployment deploy (via @ossy/deployment-tools) and the Ossy HTTP API currently expect different credentials (e.g. GitHub / queue token vs Ossy-signed JWT). They could be merged into one flag (or a single env secret in CI) if either: (1) deploy is no longer invoked from the CLI and publish is only CMS/API work, or (2) the deploy path is changed to accept the same Ossy-issued token the API uses. That lines up with Future direction (platform-driven rollouts instead of queue + dual tokens).

API and worker packages can use the same pattern: a minimal src/config.js with string-literal domain (and optional platform) matching deployments.json, then run publish from packages/api or packages/worker with --skip-resource-templates and --skip-site-artifacts (no website workspaceId / build/ flow).

• --domain / --platform — Optional if src/config.js contains string literals domain: '…' and platform: '…' (or targetDeploymentPlatform).
• --config — Path to another config.js if not ./src/config.js.
• If platform is omitted but domain is set (from flags or config), it is inferred from deployments.json when that domain appears under exactly one targetDeploymentPlatform.
• --all — Runs deployment deploy-all for the platform; requires --platform or platform in config.
• Resource templates — After a successful deploy, the CLI reads workspaceId / resourceTemplates from ./src/config.js (or --config) using the static extraction described above (not import()). If workspaceId is set and resourceTemplates is a non-empty array, they are POSTed to {api}/resource-templates with the workspaceId header (same as the CMS). Skipped when --skip-resource-templates is set, or when workspaceId / resourceTemplates are missing or not extractable.
• Site artifacts — Uses the same static workspaceId / apiUrl extraction as resource templates. If workspaceId is set and build/ exists next to src/ (i.e. run npm run build first), the CLI calls /site-artifacts/presign-batch, PUTs each file to S3, then /site-artifacts/commit-batch so a @ossy/platform/site-artifact-batch resource is created in the CMS. Skipped with --skip-site-artifacts, when there is no build/, or when workspaceId is missing. Override the build output directory with --site-artifacts-build-dir (absolute or cwd-relative).
• --api-url — Optional API base for CMS calls (e.g. https://api.ossy.se/api/v0). Otherwise OSSY_API_URL, else an absolute apiUrl from config, else https://api.ossy.se/api/v0. Relative app apiUrl values (e.g. /@ossy) are ignored unless you pass --api-url or set OSSY_API_URL.

Requires network access so npx can run @ossy/deployment-tools.

CMS: upload

Upload resource templates to your workspace so they can be used in the UI.

npx @ossy/cli cms upload --authentication <cms-api-token> --config src/config.js
# optional: --api-url https://api.ossy.se/api/v0  (or set OSSY_API_URL)

When --config is omitted, ./src/config.js is used if it exists (same as publish).

Config consistency

• App (dev, build), CMS (cms upload / cms validate), and publish all use --config (-c) for the app / workspace config file (src/config.js by default when present).

Workflow example

Prefer publish so deploy and template upload run together (see Publish above). For template-only updates, cms upload still works.

name: "[CMS] Upload resource templates"

on:
  workflow_dispatch:

jobs:
  upload-resource-templates:
    name: Upload resource templates
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: "16"
      - name: Upload
        run: |
          npx --yes @ossy/cli cms upload \
            --authentication ${{ secrets.OSSY_API_KEY }} \
            --config src/config.js

cms validate

Validate an ossy config file before uploading:

npx @ossy/cli cms validate --config src/config.js

When --config is omitted, ./src/config.js is used if it exists.

Arguments

| Argument | Description | Required | |----------|-------------|----------| | --authentication, -a | Your CMS API token | Yes (upload only) | | --config, -c | App config (workspaceId, resourceTemplates, …) | Optional if ./src/config.js exists | | --api-url | API base URL for upload (…/api/v0) | No |

init

Scaffold a new Ossy app:

npx @ossy/cli init
npx @ossy/cli init my-app

Creates src/pages.jsx, src/config.js, and package.json (if missing).