@cribl/apps

The CLI that scaffolds a new Cribl app and migrates an existing one forward to the current scaffold contract.

What it is

@cribl/apps covers two workflows for building a Cribl app (a Vite + React + TypeScript UI that runs embedded in Cribl):

• create scaffolds a brand-new app from scratch.
• upgrade moves an app that was scaffolded by an older version of this tool forward to the current scaffold contract, without touching any file you own.

Once an app exists, it also provides package — the build-and-pack step the app's own npm run package script calls — so a scaffolded app doesn't need its own packaging scripts.

Requirements

Node >=22.22.2.

Invocation

create and upgrade always run through npx @cribl/apps@latest:

npx @cribl/apps@latest create my-app

A bare npx @cribl/apps (no @latest) can resolve to a stale copy already sitting in your local npx cache instead of the current release, so pin @latest on every create and upgrade invocation. upgrade in particular has to run from the running copy, not the app's pinned devDependency — a published version carries neither the migrations nor the assets of versions published after it, so it can never move the app forward. upgrade bumps the pin (and installs the matching node_modules) as part of what it does.

package is different: it runs inside an existing app and resolves the version pinned in that app's devDependencies instead of npx-ing a fresh copy. This is deliberate — it means the app, not your shell, controls when it builds against a newer version of the tool:

# from inside an existing app
npx @cribl/apps@latest upgrade
npm run package

Command reference

| Command | Purpose | Operates on | |---|---|---| | create [directory] | Scaffold a new Cribl app | the target [directory] (defaults to .) | | upgrade [directory] | Upgrade an existing app to the current scaffold contract | the app [directory] (defaults to .) | | package | Build the app and pack it into a .tgz | the current directory (an existing app) | | version | Print the @cribl/apps package version | n/a |

create flags

| Flag | Description | Default | |---|---|---| | --app-id | App id | the target directory's name | | --display-name | Human-readable display name | — | | --openapi-url | URL to download openapi.json from | — (optional; a failed download is a warning, not a failure — create still succeeds) | | --description | Package description | — | | --author | Package author | — | | --app-version | Package version (X.Y.Z) | 1.0.0 | | --min-logstream-version | Minimum Cribl platform version | — | | --purpose | What this app does — plain text, injected into App.tsx | — | | --purpose-base64 | Same as --purpose, base64-encoded — use this when your purpose text spans multiple lines and needs to survive being pasted into a single command line | — | | --open-in | Open the scaffolded app in an IDE once setup completes (cursor or claude) | — |

--purpose and --purpose-base64 are mutually exclusive.

Examples

Scaffold a new app:

npx @cribl/apps@latest create my-app --display-name "My App" --app-version 1.0.0

Upgrade an existing app in place:

cd my-app
npx @cribl/apps@latest upgrade

Build and pack an app for install, bumping the version as you go:

npm run package              # bumps the patch version (1.0.0 -> 1.0.1)
npm run package -- --minor   # bumps the minor version (1.0.1 -> 1.1.0)
npm run package -- --version 2.0.0

What create produces

A Vite + React + TypeScript app containing:

• src/ — app source, with your --purpose already injected
• config/policies.yml and config/proxies.yml
• vite.config.ts
• AGENTS.md — guidance for coding agents working in the app
• README.md — a template for the app's own marketplace listing

There is no scripts/ directory. The app takes @cribl/apps as a devDependency, pinned to an exact version, which is where its packaging (npm run package) and live-preview logic live instead.

Upgrade behavior

apps upgrade is forward-only and idempotent:

• It never downgrades — an app built with a newer @cribl/apps than the one you're running is rejected before any write.
• It never touches files you own (src/, free-form config); it only rewrites platform-managed surfaces like vite.config.ts's packaging import, package.json's package script, and the @cribl/apps devDependency pin.
• Running it again with the same @cribl/apps version is a no-op; running a newer version raises the pin (and reinstalls node_modules to match) even when the scaffold contract itself is already current.
• If a managed surface has been edited in a way the migration doesn't recognize, it stops cleanly with the offending file named in the error, and leaves the app untouched — never a half-migrated app.

License

Apache-2.0