> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kylon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# app

> Build and operate Database and Custom Apps.

```text theme={null}
kylon workspace app — kylon workspace help detail

app — canonical data applications
    Resolve the target before acting: prefer an explicit App id, link, or name; current app/app_record thread context; the current App shell; or the current room tab. Otherwise run app list. Ask only when multiple Apps remain plausible.
    For record browsing or writes, run app docs and use its documented app api operations; agents cannot operate records through the Data Viewer UI. Use app data-view only for platform view configuration such as filters, sorts, grouping, fields, and default or saved views.
    Confirm destructive, bulk, external-facing, or hard-to-reverse operations before executing. After a write, read back through the documented API and report the verified result.
    For multiple simple creates or deletes, use a documented batch endpoint and report only the count unless IDs were requested.
    Before App lifecycle work, read the current build-app and deploy-app skills end to end. Lifecycle-mutating commands fail closed until both reads are current and complete.
  kylon workspace app list
    Discover Apps visible to this actor. Output is agent-oriented and includes id, room, created_by, creator display name when available, URL, visibility, DB, and contract status.
  kylon workspace app show <app_id>
    Show operational status, owning room, discussion thread root, URL,
    visibility, database state, and contract status for one App.
  kylon workspace app manifest <app_id>
    Print the App manifest as concise structured text, including field metadata and the OpenAPI URL. There is no human presentation mode and no --json flag.
  kylon workspace app docs <app_id> [--entity <entity_id>] [--method <GET|POST|PUT|PATCH|DELETE>] [--path <api_path>] [--raw-openapi] [--output <path>]
    Print the agent-readable App API contract from the registered manifest and OpenAPI, including runnable app api command skeletons. Use --raw-openapi for the full OpenAPI JSON.
  kylon workspace app api get <app_id> <api_path> [--query key=value]
  kylon workspace app api post <app_id> <api_path> [--body <json> | --body-file <path>]
  kylon workspace app api put <app_id> <api_path> [--body <json> | --body-file <path>]
  kylon workspace app api patch <app_id> <api_path> [--body <json> | --body-file <path>]
  kylon workspace app api delete <app_id> <api_path> [--body <json> | --body-file <path>]
    Call a documented App API operation by METHOD + PATH. Use --body-file <path> for larger JSON payloads and import/bulk endpoints. Successful POST/PUT/PATCH/DELETE calls automatically refresh open App views. Manifest create endpoints enable automatic discussion attachment by default; use api.create: { path, autoLinkDiscussion: false } only to opt out.
  kylon workspace app register <app_id> (--json <registration-json> | --file <app-registration.json>)
    Validate and register runtime kind, browser-safe manifest, server-only data model, and optional custom App API docs. Fields support json; pass JSON values directly to record APIs. Validation runs before any App state is updated and returns all detected shape errors together.
  kylon workspace app registration status <app_id>
    Inspect Data Viewer readiness: runtime kind, manifest, data model, database binding, and backfill status.
  kylon workspace app registration template <app_id> [--output <path>]
    Print or write a registration JSON template. With app_id, it drafts from the App's current manifest; if no manifest is registered yet, it pre-fills a starter template with the App id and name.
  kylon workspace app refresh <app_id>
    Compatibility/debug command that publishes a soft refresh for open App views. Normally unnecessary after app api writes because successful mutating calls refresh automatically.
  kylon workspace app data-view list <app_id> --entity <entity_id>
    List the App Data Viewer default view, saved views, and available manifest fields for one entity.
  kylon workspace app data-view show <app_id> --entity <entity_id> [--view <view_id>|--default true]
    Show the Data Viewer config for the default view or one saved view. Use this before updating filters, sorts, group_by, visible fields, field order, field widths, board, or calendar settings.
  kylon workspace app data-view update-default <app_id> --entity <entity_id> (--config <json> | --config-file <path>)
    Replace the shared default Data Viewer view config for one App entity.
  kylon workspace app data-view create <app_id> --entity <entity_id> --name <name> [--view-type table|board|calendar] [--config <json> | --config-file <path>]
    Create a saved Data Viewer view for one App entity.
  kylon workspace app data-view update <app_id> <view_id> --entity <entity_id> [--name <name>] [--view-type table|board|calendar] [--config <json> | --config-file <path>]
    Update a saved Data Viewer view. Header sorting, filters, group_by, fields, and view layout are platform view config; use app data-view, not App OpenAPI.
    Config JSON uses snake_case keys: {"filters":[{"field_id":"priority","operator":"eq","value":"P0"}],"sorts":[{"field_id":"amount","direction":"desc"}],"group_by":{"field_id":"region"},"visible_field_ids":[],"field_order":[],"field_widths":{}}. Use manifest field IDs exactly; do not use fieldId/sortBy camelCase keys. visible_field_ids and field_order list each field id at most once (duplicates are rejected). field_order is partial: list only the fields to pin first, in order; unlisted fields keep their default order, so there is no need to restate every field.
  kylon workspace app data-view delete <app_id> <view_id> --entity <entity_id>
    Delete a saved Data Viewer view.
  kylon workspace app template pull <template_id> --path <app-source-path> [--ref <git_ref>] [--force true]
    Copy one approved private App template into the local writable App source directory printed by app checkout. Use data-app or general-website for normal custom Apps; use line-inbox for a LINE Inbox backed by a Kylon LINE connection. A draft checkout's .git directory never counts as existing content and is always preserved; --force true replaces the other directory contents when the target already has files.
  kylon workspace app template pull line-inbox --path <app-source-path>
    Start a LINE Inbox custom App. The template reads LINE data through its server-side /api/line-events route and the Kylon LINE connection API; do not create app-owned raw LINE message/event tables.
  kylon workspace app template pull data-app --database-app <app_id> --path <app-source-path>
    Start a custom App project from an existing database App's registered entities and database mapping.
  kylon workspace app template release <list | show <version>> [--template <template_id>]
    List published App template versions, or show one version's user-facing notes and agent upgrade instructions. Use --template to inspect one template track.
  kylon workspace app template upgrade-plan --template <template_id> --from <current_version> [--to <target_version>]
    Print the ordered, per-version upgrade steps to bring an App from its current template version up to the target (default: latest). Find the current template id and version with app show.

  kylon workspace app create --name <name> [--icon <icon-name>] [--provider-project-name <name>] [--runtime-kind <database_app|custom_app>] [--draft-slug <slug> --draft-title "<title>"]
    Create an App through the server creation contract. Omitting --runtime-kind creates a database App with no source repository, draft, or deployment; provision its database, register it, and use Data Viewer. Use --runtime-kind custom_app when the App needs custom UI, App-owned workflow APIs, or server-side business logic. Pass --draft-slug plus --draft-title to create a Git-backed custom App and also register and materialize the first draft checkout in the same step (this starts preparing its preview database fork in the background). The draft title is only the human-readable change name (for example, "My issues count"); never include Draft, draft/, or branch/status prefixes because the product adds the "Draft:" label.
  kylon workspace app checkout <app_id> [--draft-slug <slug> --draft-title "<title>"] [--branch <branch>]
    Materialize a draft worktree for an existing App. Start a new draft with --draft-slug (names the branch draft/<slug> and the working folder) plus --draft-title (the human-readable change name, without Draft, draft/, or branch/status prefixes); the product adds the "Draft:" label. This also starts preparing the draft's preview database fork in the background. git push on the draft branch creates a preview deployment and first applies the commit's pending db/migrations/*.sql to the preview database, so schema and seed data ship as migration files rather than manual SQL. Reuse an existing draft with --branch <branch> from app draft list. Without flags, the command opens the publish-only default branch for inspection. The server rejects pushes to branches this command has not registered, so never create draft branches with plain git.
  kylon workspace app draft list <app_id>
    List active drafts with title, author, latest preview status, and the draft resource link. Reuse the active draft for the current piece of work when one exists.
  kylon workspace app draft update <app_id> --draft <draft_id> --preview-path <route>
    After the work is done, point the draft at the in-app page its link opens and its preview screenshot captures (for example /integrations). Pass --preview-path "" to reset to the app root. When the draft's latest preview is READY, the screenshot is recaptured at the new location.
  kylon workspace app draft discard <app_id> --draft <draft_id>
    Archive a draft that was created by mistake or is no longer needed, and remove its preview database fork. Only active, unpublished drafts can be discarded; publish archives its draft on its own. The source branch stays in the repository, so app checkout --branch <branch> re-opens the draft later.
  kylon workspace app preview list <app_id>
  kylon workspace app preview get <app_id> <deployment_id>
  kylon workspace app preview logs <app_id> <deployment_id> [--limit <n>]
  kylon workspace app preview docs <app_id> --draft <draft_id> [--entity <entity_id>] [--method <GET|POST|PUT|PATCH|DELETE>] [--path <api_path>] [--raw-openapi] [--output <path>]
    Print the agent-readable API contract from the draft's latest READY preview deployment contract snapshot.
  kylon workspace app preview api get <app_id> --draft <draft_id> <api_path> [--query key=value]
  kylon workspace app preview api post <app_id> --draft <draft_id> <api_path> [--body <json> | --body-file <path>]
  kylon workspace app preview api put <app_id> --draft <draft_id> <api_path> [--body <json> | --body-file <path>]
  kylon workspace app preview api patch <app_id> --draft <draft_id> <api_path> [--body <json> | --body-file <path>]
  kylon workspace app preview api delete <app_id> --draft <draft_id> <api_path> [--body <json> | --body-file <path>]
    Call a documented App API operation against the draft preview, not production. Use app preview docs first and use --body-file for larger JSON payloads.
  kylon workspace app preview db query <app_id> --draft <draft_id> (--sql <sql> | --sql-file <path>)
    Inspect preview deployments created by git push. Ready previews include the draft resource link.
    Preview db query executes SQL against the draft's preview database branch only; it does not touch production. --sql-file may contain multiple semicolon-terminated statements. The preview database forks from production in the background when the draft is checked out; if it is still being prepared, retry in about a minute. Schema and initial data belong in db/migrations files (applied automatically on push) — reserve db query for reads, cleanup of test data, and repairing state after a failed migration.
  kylon workspace app publish <app_id> <preview_deployment_id> [--visibility <public|private>]
    Publish one reviewed READY preview's exact commit and archive its draft; it does not promote a branch name. Run only from a later user message confirming that preview and its access scope. Before approval, publish preflights the default branch. If stale, it creates no approval: sync, push, share the replacement preview, then stop and wait for a new request. Publish first applies the published commit's pending db/migrations to production (each file runs once; seeds never replay).

  kylon workspace app update <app_id> [--name <name>] [--icon <icon-name>]
  kylon workspace app visibility set <app_id> <public|private>
  kylon workspace app browser-auth <app_id> [--draft <draft_id>] [--path <app-path>]
    Generate a one-time same-origin URL for a single browser smoke check of a private App. Without --draft it targets the release version; pass --draft <draft_id> (from app draft list) to verify that draft's latest READY preview at its stable preview address. Unpublished Apps have no release URL — always verify their drafts with --draft. Open the returned URL immediately with agent-browser; do not make the App public just to smoke-test it.
  kylon workspace app delete <app_id>
    Delete the App's hosting resources and hide it from active product surfaces. Its database and data are retained until the workspace is deleted.
  kylon workspace app db provision <app_id>
    Provision the App's per-App PostgreSQL database and make DATABASE_URL available to the App.
  kylon workspace app db check <app_id>
    Check the production database and print its connection URI for migration. Treat the URI as sensitive.
  kylon workspace app db query <app_id> (--sql <sql> | --sql-file <path>)
    Raw SQL escape hatch for diagnostics and compact one-off maintenance. For database Apps this is also the schema path (CREATE TABLE ...); for custom Apps schema and seed changes belong in db/migrations files, applied automatically on push and publish — never ad-hoc DDL here. Do NOT import records by looping one app db query call per row. --sql-file may contain multiple semicolon-terminated statements; the CLI runs them in order and returns every result. For bulk data, first prefer a documented App API import/bulk endpoint with app api ... --body-file. If raw DB access is necessary, group work into multi-row INSERT statements or a short ordered schema/seed script and run a single app db query with --sql-file.
  kylon workspace app domain add <app_id> <domain>
    Bind one branded custom domain (a bare hostname like app.example.com) to the App's release deployment; the default kylon.app domain keeps working. Returns the DNS setup steps or an Entri setup link to send to the user. If another App already holds the domain, the error names that App and its room so the binding can be moved with app domain remove.
  kylon workspace app domain check <app_id>
    Re-verify DNS for the bound custom domain and print its status (pending_dns or ready). Run after the user completes DNS setup. app show and app list display the current binding without re-verifying.
  kylon workspace app domain remove <app_id>
    Unbind the custom domain and return to the default domain. The domain immediately stops serving this App, so confirm with the user first. Requires write access to the App's room.
  kylon workspace app env set <app_id> <KEY=VALUE>...
    Set environment variables for the App. DATABASE_URL is set automatically by app db provision. Redeploy the App for new values to take effect.
  kylon workspace app deployment list <app_id>
  kylon workspace app deployment get <app_id> <deployment_id>
  kylon workspace app deployment wait <app_id> <deployment_id> [--timeout-seconds 600] [--interval-seconds 5]
  kylon workspace app deployment logs <app_id> <deployment_id> [--limit <n>]
  kylon workspace app deployment rollback <app_id> <deployment_id>

  Build workflow requirement: before mutating files, schema, deployment, or generated contract artifacts for a new App, produce a concrete breakdown for business objects, relationships, user flows, agent/API flows, default data-management or status-tracking behavior, whether custom screens or business logic are needed, who should have access, and whether to make it available now; then get user confirmation.
Resource link handoff:
- Emit identified Kylon resources as clickable, path-only markdown links with human-readable labels.
- Copy command-returned links verbatim. Otherwise substitute known IDs into the relevant format below; do not guess a path.
- App: `[name](/workspaces/{workspaceId}/rooms/{roomId}/apps/{appId})`; URL-encode the `appId` path segment.
- App page: `[page name](/workspaces/{workspaceId}/rooms/{roomId}/apps/{appId}/p/{appPath})` opens one page inside the App, still wrapped in Kylon. Everything after `/p/` is the App's own path, URL-encoded per segment; put the App's query string in `?app_query=` and its fragment in `?app_hash=` (both URL-encoded as a whole) so they cannot collide with Kylon's own query params. Share this instead of the App's raw `*.kylon.app` URL: the raw URL leaves Kylon and skips App authorization, so a private App sends the recipient to sign-in.
- App draft: `[draft title](/workspaces/{workspaceId}/rooms/{roomId}/apps/{appId}/drafts/{draftId})`; this is the sharing surface for draft previews.
- App record discussion: `[title](/workspaces/{workspaceId}/rooms/{roomId}/threads/pending/app_record/{encodedAppId%2FentityId%2FrecordId})`; URL-encode the entire `appId/entityId/recordId` compound target as one path segment. Prefer the record title/name, or a specific entity-name label such as `this issue` or `this client`. Never use `recordId` as the label or present raw record IDs as the primary reference; omit parenthetical raw IDs unless the user explicitly asks for them.

Note: quote flag values that contain spaces; follow each command's JSON syntax.
```