CLI reference

The CLI accepts TypeScript, JavaScript, or JSON manifests. TypeScript and TSX files are loaded directly; a module may export the manifest as default, app, or manifest.

Authentication

npx twl-tool auth login --url APP_URL
npx twl-tool auth status --url APP_URL
npx twl-tool auth logout --url APP_URL

Credential lookup order is --token, TWL_TOOL_TOKEN, then the saved credential for the requested server. Set TWL_TOOL_CONFIG_HOME to override the local credential directory.

When the UI and API use different origins, add --api-url API_URL or set TWL_TOOL_API_URL.

Authoring

npx twl-tool build twl-tool.app.ts --out twl-tool.app.json
npx twl-tool validate twl-tool.app.ts --url APP_URL
npx twl-tool plan twl-tool.app.ts --url APP_URL --organization ORG
npx twl-tool deploy twl-tool.app.ts --url APP_URL --organization ORG

Command	Network access	Purpose
build [manifest]	No	Compile a source manifest to JSON; defaults to twl-tool.app.ts and twl-tool.app.json
validate [manifest]	Yes	Validate against the target server and its current platform schema
plan [manifest]	Yes	Preview account-scoped creates, updates, retained resources, and blocked changes
deploy [manifest]	Yes	Install or upgrade an app after validation and planning

Add --allow-space-migration to plan or deploy only when you intend to allow a root Space migration.

Testing

npx twl-tool test twl-tool.tool.test.ts
npx twl-tool certify twl-tool.tool.test.ts --out certification.json

Clone a Space Template

npx twl-tool clone TEMPLATE_ID \
  --url APP_URL \
  --organization ORG \
  --out twl-tool.app.json \
  --key my-template-fork \
  --name "My Template Fork"

The clone is editable and retains source provenance. The developer-managed original remains unchanged.

pull is an alias for clone. Use --key, --name, and --version to override those fields in the cloned manifest, and --out to select its destination.

Export an account

npx twl-tool account-export \
  --url APP_URL \
  --organization ORG \
  --out account-config

The export writes the platform schema, app manifests, root Space snapshots, workflow definitions, and an inventory.json index. Add --include-rows to include Data Workspace rows in exported Space snapshots.

Browser listener operations

npx twl-tool browser-status --url APP_URL --organization ORG
npx twl-tool listener-discover-start discovery.json --url APP_URL --organization ORG
npx twl-tool listener-discover-snapshot SESSION_ID --url APP_URL --organization ORG
npx twl-tool listener-discover-stop SESSION_ID --url APP_URL --organization ORG
npx twl-tool listener-preview selector.json --url APP_URL --organization ORG
npx twl-tool listener-browser command.json --url APP_URL --organization ORG
npx twl-tool listener-command COMMAND_ID --url APP_URL --organization ORG
npx twl-tool listener-activate AUTOMATION_ID --url APP_URL --organization ORG
npx twl-tool listener-verify WATCHER_ID --url APP_URL --organization ORG --payload
npx twl-tool extension-actions --url APP_URL --organization ORG
npx twl-tool extension-action-run action.json --url APP_URL --organization ORG
npx twl-tool extension-action-status RUN_ID --url APP_URL --organization ORG

Discovery records matching network requests so you can design a browser_network_response listener. Preview tests a selector without activating it. Activation installs the listener; verification checks a watcher and optionally returns the captured payload.

Global options

Option	Alias	Used by
--out PATH	-o	build, test, certify, clone, pull, account-export
--url URL	—	Authentication and every server-backed command
--api-url URL	—	Override the API origin when it differs from the UI origin
--token TOKEN	—	Explicit credential; takes precedence over the environment and saved credential
--organization ID_OR_SLUG	-g	Account-scoped planning, deployment, export, clone, and browser operations
--key KEY	—	Override a cloned app key
--name NAME	—	Name an auth credential or override a cloned app name
--version VERSION	—	Override a cloned app version
--payload	—	Include the captured payload in listener verification
--include-rows	—	Include table rows in account-export
--allow-space-migration	—	Permit an intentional root Space migration during plan or deploy

Environment variables

Variable	Purpose
TWL_TOOL_TOKEN	Non-interactive authentication token
TWL_TOOL_API_URL	API-origin override
TWL_TOOL_CONFIG_HOME	Credential-store directory override

Token lookup order is --token, TWL_TOOL_TOKEN, then the saved credential for --url.