@jtl-software/create-cloud-app

CLI for JTL Platform cloud apps. Scaffolds a new app project and registers/updates its manifest against the cloud.

Requirements

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

Commands

The CLI has two entry points:

• The default invocation (no arguments) scaffolds a new project.
• register registers or updates a manifest against the JTL Cloud.

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 app manifest
• 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

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 manifest.json
• An npm run register script that delegates to npx -y @jtl-software/create-cloud-app@latest register

register

Register a new app or update an existing app's manifest. Reads manifest.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://auth.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.

CI usage: keep your deployed manifest in sync with the repo

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

The register command supports 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.

Step 3: CI workflow

GitHub Actions example:

name: Update manifest

on:
  push:
    branches: [main]
    paths:
      - manifest.json

jobs:
  register:
    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

--yes keeps the run non-interactive. --tenant and --existing-app-id pin the target so the command can't accidentally touch a different tenant or app. The job only runs when manifest.json changes, so the deployed manifest tracks main.

After scaffolding

1. Register your manifest 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"

Documentation

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