@jtl-software/create-cloud-app

CLI for JTL Platform cloud apps. Scaffolds a new app project, registers it against the cloud, and pushes its store listing.

Requirements

Node.js 24 (current LTS) or newer. The scaffolded project sets the same floor via engines.node.

Commands

The CLI has three entry points:

• The default invocation (no arguments) scaffolds a new project.
• register registers or updates the app's identity (app.json) against the JTL Cloud — do this when you start building.
• listing pushes the app's store listing (listing.json) — do this once you're done building and ready to publish.

Registration and listing are two independent resources on two independent files. register must happen first — listing pushes against the app that register created and will fail with a clear error if it hasn't run yet.

npm create @jtl-software/cloud-app@latest

Scaffold a new app interactively.

npm create @jtl-software/cloud-app@latest

You'll be prompted for:

• App name: directory name, package name, and manifest identifier
• Description: placed in the listing
• Backend: Node.js (Express + TypeScript) or .NET (ASP.NET Core + FastEndpoints)
• Frontend: React (Vite + Tailwind + JTL Platform UI)

Then:

cd my-app
npm install
npm run register
npm run dev

Pass --legacy to scaffold the backend for the legacy Ory M2M flow instead of the Zitadel service account (compat testing only, node backend only):

npm create @jtl-software/cloud-app@latest -- --legacy

npm run register then writes the app's Ory client credentials, and the backend mints its M2M token against the Ory auth host. Everything else is unchanged: the backend still verifies the incoming app token and reads the tenant id from it.

The generated project includes:

• A monorepo wired up with Turborepo
• A frontend with welcome pages explaining each app mode and manifest mapping
• A backend with JWT verification, tenant connection, and ERP API proxy
• A ready-to-register app.json (identity: technicalName, version, lifecycle, capabilities)
• A ready-to-push listing.json (store metadata: name, description, media, pricing, etc.)
• An npm run register script that delegates to npx -y @jtl-software/create-cloud-app@latest register
• An npm run listing script that delegates to npx -y @jtl-software/create-cloud-app@latest listing

register

Register a new app or update an existing app's manifest. Reads app.json from the current working directory and pushes it to the App Service.

npx @jtl-software/create-cloud-app register

By default the command is interactive: it opens a browser for OAuth login, then prompts for tenant and whether to update an existing app or create a new one.

Flags:

| Flag | Description | | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | --api-host <url> | API host. Default https://api.jtl-cloud.com. | | --auth-host <url> | OAuth host. Default https://id.jtl-cloud.com. The CLI picks the matching client ID for the known prod/QA/dev hosts. | | --hub-host <url> | Hub host (used in printed links). Default https://hub.jtl-cloud.com. | | --client-id <id> | Override the OAuth client ID. Only needed for custom auth hosts. | | --scope <scope> | OAuth scope. Default openid offline_access. | | --reauth | Skip the cached token and open the browser again. Useful after switching accounts. | | --yes, -y | Non-interactive mode. Auto-confirms prompts and fails if any choice is ambiguous (e.g. multiple tenants match). Required for CI. | | --tenant <id-or-slug> | Select a tenant by ID or slug (case-insensitive). | | --existing-app-id <id> | Update the app with this ID instead of prompting. Errors if it doesn't match this manifest's technical name. | | --new | Force-create a new app even if a matching one exists. Mutually exclusive with --existing-app-id. | | --on-collision <overwrite\|print\|cancel> | What to do when an existing credentials file would be overwritten during provisioning. print writes the secret to stdout instead of the file. Required in --yes mode if a collision is possible. |

Tokens are cached under ~/.config/jtl-cli/tokens.json (mode 0600). Override the path with the JTL_CLI_TOKEN_CACHE_FILE environment variable.

listing

Push the app's store listing. Reads listing.json and the technicalName from app.json (both in the current working directory), then pushes the listing for that app.

npx @jtl-software/create-cloud-app listing

Like register, it's interactive by default: OAuth login, then a tenant prompt. It also asks two questions about the listing itself — distribution type (PUBLIC/PRIVATE) and default locale — pre-filled from whatever's already in listing.json and written back there once answered, so re-running listing later remembers your choice. Unlike register, there's no create-vs-update choice or local credential file to write — a listing is always pushed against the app register already created, keyed by technicalName. If no registered app matches, the command fails with a message telling you to run register first.

Flags: --api-host, --auth-host, --hub-host, --client-id, --scope, --reauth, --yes/-y, --tenant — same meaning as the equivalent register flags above. There's no --existing-app-id, --new, or --on-collision since listing has nothing to disambiguate or overwrite locally.

CI usage: keep your deployed app.json and listing.json in sync with the repo

A common setup is to commit app.json and listing.json to source control and have CI push them to the cloud whenever they change, so the deployed app always matches what's on main.

Both register and listing support this. You need three things:

1. Pin the tenant and app ID so the run is deterministic.
2. Run with --yes so prompts don't block.
3. Seed the OAuth token cache so login doesn't open a browser.

Step 1: capture a refresh token locally

Run register once on your machine while signed in as the user (or service account) you want CI to act as:

cd path/to/your/app
npx @jtl-software/create-cloud-app register --scope "openid offline_access"

After it completes, ~/.config/jtl-cli/tokens.json contains an entry with a refresh_token. Copy that file's contents and store it as a CI secret (e.g. JTL_CLI_TOKENS).

The cached token will be silently refreshed on every CI run, so it stays valid as long as CI runs often enough that the refresh token doesn't expire.

Step 2: look up your tenant and app ID

You can read them off the previous interactive run (the CLI prints both). The tenant slug is the stable, human-friendly identifier. The app ID is a UUID printed in the "Review" section — only register needs it; listing only needs the tenant, since it resolves the app by technicalName.

Step 3: CI workflow

GitHub Actions example — one job per file, each triggered only when its own file changes:

name: Update app.json and listing.json

on:
  push:
    branches: [main]
    paths:
      - app.json
      - listing.json

jobs:
  register:
    if: contains(github.event.head_commit.modified, 'app.json')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - name: Write token cache
        env:
          JTL_CLI_TOKENS: ${{ secrets.JTL_CLI_TOKENS }}
        run: |
          mkdir -p "$RUNNER_TEMP/jtl-cli"
          printf '%s' "$JTL_CLI_TOKENS" > "$RUNNER_TEMP/jtl-cli/tokens.json"
          chmod 600 "$RUNNER_TEMP/jtl-cli/tokens.json"
      - name: Update manifest
        env:
          JTL_CLI_TOKEN_CACHE_FILE: ${{ runner.temp }}/jtl-cli/tokens.json
        run: |
          npx -y @jtl-software/create-cloud-app@latest register \
            --yes \
            --tenant my-tenant-slug \
            --existing-app-id 00000000-0000-0000-0000-000000000000

  listing:
    if: contains(github.event.head_commit.modified, 'listing.json')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - name: Write token cache
        env:
          JTL_CLI_TOKENS: ${{ secrets.JTL_CLI_TOKENS }}
        run: |
          mkdir -p "$RUNNER_TEMP/jtl-cli"
          printf '%s' "$JTL_CLI_TOKENS" > "$RUNNER_TEMP/jtl-cli/tokens.json"
          chmod 600 "$RUNNER_TEMP/jtl-cli/tokens.json"
      - name: Update listing
        env:
          JTL_CLI_TOKEN_CACHE_FILE: ${{ runner.temp }}/jtl-cli/tokens.json
        run: |
          npx -y @jtl-software/create-cloud-app@latest listing \
            --yes \
            --tenant my-tenant-slug

Note listing doesn't take --existing-app-id — it only needs --tenant to pin the target, since the app is resolved by technicalName.

--yes keeps each job non-interactive, and the if: conditions mean only the file that actually changed gets pushed — an app.json-only commit doesn't re-push an unchanged listing, and vice versa.

After scaffolding

1. Register your app's identity in the Partner Portal or with npm run register
2. Add your Client ID and Secret to the backend config
3. Install the app from JTL-Cloud Hub under "Apps in development"
4. Once you're done building, push the store listing with npm run listing

Documentation

• JTL Developer Platform
• Partner Portal
• JTL-Cloud Hub