create-coline-app

Scaffold, push, and iterate on apps for the Coline App Store.

npx create-coline-app my-app
npx create-coline-app my-app --template integration
cd my-app && npm install && npm run check

| Template | What you get | | --- | --- | | backendless (default) | Hosted React app with a file type, a Kairo tool, and three UI examples | | editor | A file type with a React block editor: autosave, conflict handling, previews, search | | integration | Full stack: GitHub OAuth connection, webhook endpoint, resumable sync job, hourly schedule, dashboard | | external-backend | Tools and screens served by your own Node server, signed by Coline |

Every template keeps the same agent guidance, design skills, and UI examples, and passes npm run check on a clean install. preview.seed.ts can export options (fake net.fetch responses, connections already made); preview runs queued background jobs automatically.

Two binaries ship from this package:

• create-coline-app <dir> — scaffolds a self-contained backendless app: a defineApp config with a Kairo tool, a file type with tree surfaces, a working React home using @colineapp/ui, mobile/tree fallback rendering, agent guidance, and local validation through coline-app check.
• coline-app push | dev — builds the logic bundle with esbuild, extracts the manifest through the two-artifact model (plan §6.2), bundles installed client dependencies and CSS when the manifest declares React surfaces, and uploads to POST /api/v1/apps/{key}/versions with a workspace API key (apps.write scope). dev watches and re-pushes stamped versions.

The CLI bundles the client locally. Coline validates, rebuilds, and hashes the uploaded artifact before serving it in the sandbox.

npm run check checks types, the manifest, logic, and React bundle without an upload. The starter does not include a test suite or runner. Add behavioral tests with @colineapp/sdk/testing and configure a test command as needed.

The generated project includes AGENTS.md and .agents/skills/coline-app-development/SKILL.md. Those files are deliberately specific to the installed public packages so coding agents can work without reading Coline's private product repository.

SDK 0.4 / CLI 2.5 workflow

Run coline-app check before pushing: it checks types, the manifest, hosted logic, and the React bundle without uploading. dev --internal updates one development version; install it in the workspace and reload after changes. The CLI bundles from the app's installed dependencies and preserves imported CSS and inline assets. App-specific Tailwind v4 utilities compile automatically with CLI 2.5. Import @colineapp/ui/styles.css and then ./app.css; use complete class names.

The starter includes a React home and editor, tree mobile fallback, and a tool. Use coline.tools.invoke or actions.invokeTool to run the same declared tool from UI that Kairo runs. Save with expectedVersion to detect concurrent edits. Homes/editors can write within grants; previews and server render handlers cannot. createTestWorkspace(app).client() tests the interactive contract and grantedPermissions simulates revoked consent.

New tasks, calendar, messages, and references capabilities require their explicit manifest permissions and retain the invoking user's workspace access. Use files.list({ scope: "workspace" }) for shared files; document writes stay with the owning app. Collections are install-private. A native mobile React runtime is separate work.

Agent UI workflow (experimental)

Generated apps include original Coline-specific development, design, and review skills under .agents/skills, plus plain AGENTS.md and a CLAUDE.md pointer. The UI examples cover a request queue/detail panel, editorial board, and settings. Their state is local: adapt the layout, then connect the real SDK capabilities.

npm run preview                           # local notes app with seeded data
npm run preview -- --pattern triage        # also board / settings
npx playwright install chromium            # once, for screenshot capture
npm run screenshots                       # .coline/screenshots/report.json

Preview binds a random loopback port and uses the published SDK test workspace and real sandbox bridge. It does not need credentials or upload anything. Theme/state controls and live source reload make iteration cheap. preview.seed.ts can seed capabilities without importing fixtures into the production entry.

The screenshot command captures light/dark × desktop/mobile × five states and reports browser errors, page overflow, and unlabelled fields. It exits nonzero on those issues. Inspect images and exercise interactions before calling the UI finished. This is not a visual-quality score or a hosted authorization, realtime, or performance test. Models without image/tool support need human visual review.

CLI 2.5.1 scaffolds UI 0.4.1 and uses FilterMenu in the reference examples. Prefer the shared raised tabs, buttons and animated dialogs. Updating dependencies requires rebuilding and pushing a new version before installed apps receive it.

CLI 2.6.0 scaffolds SDK/runtime/UI 0.5.0, including Coline-provided AI jobs. Use model discovery and the SDK's watchAiJob; do not scaffold provider API keys.

Upload origin safety

Set COLINE_BASE_URL to the trusted Coline HTTPS origin. Local development also accepts HTTP on localhost, 127.0.0.1, and [::1]. Paths, URL credentials, queries, fragments, and remote plain HTTP are rejected before building or sending. Uploads never follow redirects. Correct the configured origin if a redirect is reported. Upload requests time out after 60 seconds; check the developer console before retrying because the server may already have committed the version. Keep COLINE_API_KEY in the environment rather than shell command arguments.