app

kylon workspace app — kylon workspace help detail

app — canonical data applications
    Resolve target: prefer an explicit App id, link, or name; then current app/app_record thread context, App shell. Otherwise run app list; ask only when multiple Apps remain plausible.
    For records: app docs plus documented app api operations. Data Viewer UI cannot operate records; app data-view is only for platform view config.
    Confirm destructive/bulk/external/hard-to-reverse operations before executing. Verify writes through the documented API. For simple creates/deletes, use a documented batch endpoint; report count unless IDs were requested.
    Before lifecycle work, read current build-app and deploy-app skills end to end. Mutations fail closed until both reads are complete/current.
  kylon workspace app list
    List visible Apps with id, Room, created_by, URL, visibility, DB, and contract status.
  kylon workspace app show <app_id>
    Show status, owning Room, discussion root, URL, visibility, DB, and contract.
  kylon workspace app move <app_id> --to-room <room_id> [--detach-discussions]
    Move a database App and its declared Automations to another writable Room. Custom Apps and legacy Table replacements are refused. If source-Room discussions are linked to the App, its records, or owned Automations, retry with --detach-discussions only after confirming those links may be removed; the messages and replies stay in the source Room.
  Declare Automations for either App kind in the registration document's "automations" array; app register applies it. Never edit generated/app-registration.json: builds replace it. A git build's uploaded "automations" contract wins, so publish/rollback follow its commit.
    [{"key":"daily","name":"Daily","trigger":{"kind":"cron","expr":"0 2 * * *","timezone":"UTC"},"target":{"kind":"prompt","message":"Close invoices"},"delivery":{"publish":true}}]
    key is stable: lowercase letters, digits, hyphens. Renaming name preserves it; changing key retires it and creates another.
    trigger: {"kind":"cron","expr":"..."} or {"kind":"record_change","entity":"<manifest entity id>","events":["insert","update","delete"],"when":{"where":{"status":"blocked"}}}. Cron meets the Automation (workflow create) minimum and needs a future run. Entities must be in this manifest; when narrows which changes fire.
    target: {"kind":"prompt","message":"..."} or {"kind":"code","source":"..."}; code requires @kylon/workflow-sdk. delivery: {"publish":true} posts results; omit for internal-only.
    New declarations are PAUSED; workflow resume enables them. Omit "automations" to preserve declarations; [] retires all. Declaration errors do not fail register/publish; output names them and --check reports drift.
  kylon workspace app automations <app_id> [--check true]
    Compare declarations with live Automations. Live Room rows bill individually; pause/resume/manual trigger need no deploy. workflow update/rollback/delete cannot change declaration-owned definitions.
    States: in sync; stale (live definition older; apply again); missing (declared not live; reason named); orphaned (live undeclared; apply to archive). --check true reports drift only.
    Draft rows are inspectable, never auto-fire, and retire on publish/discard. Manual triggers use PRODUCTION records, not preview DB; treat them as real runs.
  kylon workspace app manifest <app_id>
    Print manifest fields and OpenAPI URL; no human mode or --json.
  kylon workspace app docs <app_id> [--entity <entity_id>] [--method <GET|POST|PUT|PATCH|DELETE>] [--path <api_path>] [--raw-openapi] [--output <path>]
    Print App API contract/skeletons; --raw-openapi returns 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 documented METHOD + PATH. Use --body-file <path> for larger JSON payloads and import/bulk endpoints. Successful POST/PUT/PATCH/DELETE calls automatically refresh views. Create endpoints auto-attach unless api.create sets autoLinkDiscussion:false. Kylon attaches the created App record to the top-level trigger thread when the response has record_id; repair: thread attach --target app_record:<app_id>/<entity_id>/<record_id> --root current|<root_message_id>.
  kylon workspace app register <app_id> (--json <registration-json> | --file <app-registration.json>) [--check]
    Replace full registration, not a patch. Omitted docs/custom-App model clear; omitted automations preserve. Validates shape, tables, columns and zero-row reads before saving; 4s DB budget. Failure saves nothing; --check never saves. JSON fields take JSON values.
  kylon workspace app registration status <app_id>
    Show stored setup, not live database health.
  kylon workspace app registration template <app_id> [--output <path>]
    Export stored registration/mappings (manage access); unregistered Apps get a scaffold. Fill placeholders first.
  kylon workspace app refresh <app_id>
    Publish a soft refresh for open App views; normally unnecessary after app api writes.
  kylon workspace app data-view list <app_id> --entity <entity_id>
    List default/saved views and manifest fields.
  kylon workspace app data-view show <app_id> --entity <entity_id> [--view <view_id>|--default true]
    Inspect config before updating.
  kylon workspace app data-view update-default <app_id> --entity <entity_id> (--config <json> | --config-file <path>)
    Replace shared default config.
  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 view.
  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 view. Filters, sorts, group_by, fields, and 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 exact manifest field IDs; do not use fieldId/sortBy camelCase keys. visible_field_ids and field_order reject duplicates. field_order is partial: listed fields pin first; unlisted fields keep default order.
  kylon workspace app data-view delete <app_id> <view_id> --entity <entity_id>
    Delete a view.
  kylon workspace app template pull <template_id> --path <app-source-path> [--ref <git_ref>] [--force true]
    Copy an approved private template into the local writable App source directory printed by app checkout. Use data-app or general-website normally; line-inbox for a LINE Inbox backed by a Kylon LINE connection. A draft checkout's .git alone is not existing content and is always preserved; --force true replaces other content.
  kylon workspace app template pull line-inbox --path <app-source-path>
    Start a LINE Inbox custom App using its server-side /api/line-events route and 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 from a database App's registered entities/mapping.
  kylon workspace app template release <list | show <version>> [--template <template_id>]
    List versions or show notes/upgrade steps; --template selects a track.
  kylon workspace app template upgrade-plan --template <template_id> --from <current_version> [--to <target_version>]
    Print per-version steps to the target (default latest); app show gives the current template id/version.
  kylon workspace app template prepare <app_id> --source <app-checkout-path> --path <new-staging-path>
    Make a filtered, separately editable staging copy and run an advisory safety preflight. The original App checkout is never modified; submit re-runs the authoritative review on the staged bytes.
  kylon workspace app template submit <app_id> --slug <id> --title "<name>" --path <src> [--description ...] [--category <c>] [--version 1.0.0]
    Share sanitized App source as a preview template from a live user request. A new id lands active/listed at 1.0.0; later versions are exact-addressable and do not change the owner-controlled default. Needs template.yaml; credentials, real contacts and deploy URLs reject it.
  kylon workspace app template bundle <list | show <bundle_id> | audit <bundle_id>> [--shared true]
    Inspect staged/shared bundles; owner audit preserves consent, review and hash provenance.
  kylon workspace app template bundle share <bundle_id>@<exact-version>
    Direct Human request only. The URL allows unsigned cross-environment downloads; revocation cannot recall them. Never share private data.
  kylon workspace app template bundle links <bundle_id>
    List link metadata without revealing bearer tokens.
  kylon workspace app template bundle revoke <bundle_id> <share_link_id>
    Revoke future downloads; direct Human request only.
  kylon workspace app template pull --bundle <bundle_id>[@version] --path <src> [--force true]
    Copy a shared bundle; --force replaces existing source. Omit @version for its default.
  kylon workspace app template pull --share-url <url> --path <src> [--force true]
    Import only from a canonical P2 API URL; verifies size, format, hash and safety before writing.
    Unlisting hides discovery but preserves direct pulls. Withdrawal invalidates all references and cleans up snapshots.
  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>"] [--pin]
    Omitting --runtime-kind creates a database App: no source repository, draft, or deployment; provision/register/use Data Viewer. Use --runtime-kind custom_app for custom UI, App-owned Automation APIs, or server logic. Draft flags create a Git-backed custom App and also register it, materialize the first draft checkout, and start its preview DB fork. The title is a human change name (for example "My issues count"); never include Draft, draft/, or branch/status prefixes; the product adds the "Draft:" label. Pass --pin only when the user asked for a personal sidebar shortcut.
  kylon workspace app checkout <app_id> [--draft-slug <slug> --draft-title "<title>"] [--branch <branch>]
    Materialize a draft worktree. New flags create draft/<slug>, follow the title rule above, and start its preview DB fork. git push on the draft branch creates a preview after pending db/migrations/*.sql; ship schema/seeds there, not manual SQL. Reuse an existing draft with --branch <branch> from app draft list. No flags opens the publish-only default branch for inspection. Never use plain git; the server rejects unregistered branches.
  kylon workspace app draft list <app_id>
    List active drafts with preview status and links. 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>
    Set the draft link/screenshot route (for example /integrations); "" resets root. A READY preview is recaptured.
  kylon workspace app draft discard <app_id> --draft <draft_id>
    Archive an active unpublished draft and remove its preview DB fork. Publish also archives it; app checkout --branch can re-open the source branch.
  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 API contract from the latest READY preview 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 draft-preview API, never production; read app preview docs first.
  kylon workspace app preview db query <app_id> --draft <draft_id> (--sql <sql> | --sql-file <path>)
    Ready previews include a draft link. Preview db query executes SQL against the draft's preview database, never production; --sql-file accepts multiple statements. The fork starts from production at checkout; retry in about a minute if preparing. Put schema/initial data in db/migrations; use this for reads, test cleanup, or migration repair.
  kylon workspace app publish <app_id> <preview_deployment_id> [--visibility <private|workspace|public>]
    Publish a reviewed READY preview's exact commit and archive its draft, never a branch name. Run only from a later user message confirming that preview and its access scope. Preflight the default branch before approval. If stale, it creates no approval: sync, push, share the replacement, then stop and wait for a new request. Pending production migrations run once; seeds never replay.
  kylon workspace app approval revoke <app_id> [--agent <agent_id>]
    Revoke standing App publish approval. A Human caller executes directly
    under their own RBAC; an Agent sends the triggering Human a bound action
    that revokes this Agent's approval. --agent disambiguates Human calls when
    more than one Agent has approval for the App and is invalid for Agent calls.
  kylon workspace app update <app_id> [--name <name>] [--icon <icon-name>]
  kylon workspace app visibility set <app_id> <private|workspace|public>
  kylon workspace app browser-auth <app_id> [--draft <draft_id>] [--path <app-path>]
    One-time same-origin URL for a private App. Default: release; --draft: READY preview and required if unpublished. Open immediately with agent-browser; do not make the App public just to smoke-test it.
  kylon workspace app delete <app_id>
    Delete hosting and hide the App. Its database and data remain until workspace deletion.
  kylon workspace app db provision <app_id>
    Provision the per-App PostgreSQL DB and DATABASE_URL.
  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 reset <app_id> --draft <draft_id>
    Reset an unpublished preview DB to latest production state. Push applies migrations to preview; publish to production; a per-DB journal runs each once. Applied migration files are immutable by checksum: add a numbered file, or reset the draft to rewrite them against a clean preview.
  kylon workspace app db query <app_id> (--sql <sql> | --sql-file <path>)
    SQL for maintenance; custom_app schema/seeds belong in db/migrations, never ad-hoc DDL. For bulk prefer app api --body-file or multi-row INSERT. Do NOT loop app db query per row. --sql-file runs semicolon-separated statements in order. The standalone CLI sends the complete script in one request; transaction support depends on the provider.
  kylon workspace app domain add <app_id> <domain>
    Bind a bare hostname; the default remains. Return DNS steps or Entri link. On conflict, the error names that App and its room so app domain remove can move it.
  kylon workspace app domain check <app_id>
    Recheck DNS: pending_dns or ready. app show/list do not recheck.
  kylon workspace app domain remove <app_id>
    Return to default. The custom domain immediately stops serving this App, so confirm with the user first; requires Room write access.
  kylon workspace app env set <app_id> <KEY=VALUE>...
    Set env vars. DATABASE_URL is set automatically by app db provision; redeploy to apply.
  kylon workspace app connections list <app_id>
    List grants; server routes use only these, and new Apps have none.
  kylon workspace app connections grant <app_id> <connection_id>
    Grant a source-agent connection; the agent must already be able to run it.
  kylon workspace app connections revoke <app_id> <connection_id>
    Stop server access; revocation is idempotent.
  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>

  Before mutating a new App's files, schema, deployment, or generated contracts, propose its objects/relations, user and agent/API flows, default data/status behavior, custom UI/logic need, access, and whether to release now; 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})`; URL-encode each App-path segment, plus the whole query in `?app_query=` and fragment in `?app_hash=`. Share this instead of a raw `*.kylon.app` URL: raw URLs leave Kylon, skip App authorization, and send private-App recipients to sign-in.
- App draft: `[draft title](/workspaces/{workspaceId}/rooms/{roomId}/apps/{appId}/drafts/{draftId})`; use this to share a preview.
- App record discussion: `[title](/workspaces/{workspaceId}/rooms/{roomId}/threads/pending/app_record/{encodedAppId%2FentityId%2FrecordId})`; URL-encode the entire `appId/entityId/recordId` compound target. Prefer its title/name or a specific entity-name label such as `this issue` or `this client`. Never use `recordId` as the label; omit parenthetical raw IDs unless the user explicitly asks.

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