Skip to main content

Create your first app

Start with a TypeScript manifest, validate it against the target TWL Tool server, and preview the installation plan before deploying.

1. Install the SDK​

npm install @twl-tool/app-sdk

Create twl-tool.app.ts:

import {defineApp, ref, resources} from '@twl-tool/app-sdk';

export default defineApp({
  key: 'idea-library',
  name: 'Idea Library',
  version: '1.0.0',
  permissions: ['data-workspace.read'],
  ui: {
    defaultSurface: 'ideas',
    surfaces: [
      {
        key: 'ideas',
        label: 'Ideas',
        type: 'dataWorkspaceView',
        table: ref('dataWorkspaceTables', 'ideas'),
      },
    ],
  },
  resources: {
    dataWorkspaces: {
      main: resources.workspace({title: 'Idea Library'}),
    },
    dataWorkspaceBases: {
      main: resources.base({
        workspace: ref('dataWorkspaces', 'main'),
        title: 'Library',
      }),
    },
    dataWorkspaceTables: {
      ideas: resources.table({
        base: ref('dataWorkspaceBases', 'main'),
        title: 'Ideas',
        columns: {
          title: {type: 'single_line_text', required: true},
          sourceUrl: {type: 'url'},
          notes: {type: 'long_text'},
        },
      }),
    },
  },
});

Because spaces is omitted, defineApp() creates a root Space named Idea Library and places the compatible resources inside it.

2. Sign in​

npx twl-tool auth login --url https://twl-tool.example
npx twl-tool auth status --url https://twl-tool.example

Login opens the signed-in TWL Tool app and waits for an explicit approval. The saved credential is scoped to Apps Layer read and deploy operations.

3. Build and validate​

npx twl-tool build twl-tool.app.ts --out twl-tool.app.json
npx twl-tool validate twl-tool.app.ts --url https://twl-tool.example

The server is authoritative. Validation uses the platform schema exposed by the server, so it catches capability and resource rules that may be newer than your local SDK.

4. Plan and deploy​

npx twl-tool plan twl-tool.app.ts \
  --url https://twl-tool.example \
  --organization acme

npx twl-tool deploy twl-tool.app.ts \
  --url https://twl-tool.example \
  --organization acme

deploy plans first and applies the exact returned fingerprint. Review created and retained resources before approving a production change.

:::warning Keep credentials out of source Do not commit deployment tokens or paste them into command output. The CLI can use its saved credential or TWL_TOOL_TOKEN at runtime. :::