CLI Reference

Use waid --help for the command overview and waid help <command> or waid <command> --help for focused options. waid version and waid --version print the installed CLI version.

text

waid <command> [options]
 
  login              Sign in to ICE through Splenta ID
  new <name>         Create a Vite + React + shadcn project
  dev                Run Vite and launch the Detir runtime
  build              Package a web or native app
  deploy             Build, install, and launch on iOS or Android
  app scan|sync      Scan app source or submit an ICE Develop candidate
  service scan|sync  Scan service source or submit an ICE Develop candidate
  session --json     Check the shared CLI/Studio ICE session
  apps               List registered apps visible to your account
  whoami, logout     Inspect or clear the stored ICE identity
  doctor             Check local tooling and signing
  devices            List iOS or Android devices
  signing-teams      List Xcode signing teams
  clean              Remove generated build artifacts
  migrate-config     Update an older waid.config.json
  actions, backend   Legacy helpers; use app/service for new work
  version            Print the CLI version

bash

waid login --env local
waid login --env staging --tenant <tenant-key>
waid session --json
waid whoami --json
waid logout

Login option	Behavior
`--env local\|staging\|prod`	Choose the ICE environment. Defaults to `local`; `WAID_ENV` also selects it.
`--tenant <key>`	Select the tenant for the session.
`--force`	Request a fresh grant instead of reusing a usable session.
`--browser`	Explicitly use the browser login flow.

Login uses Splenta ID. Local login defaults to file credential custody; hosted login defaults to the keychain. WAID_CREDENTIAL_STORE=keychain or file overrides that choice. session --json reports ready, signed_out, or unavailable; a temporary ICE outage retains the credentials.

new, dev, build, deploy, clean, migrate-config, app/service sync, and catalog inspection require a usable ICE session. Local app/service scans, help, version, and local tooling diagnostics do not.

--env selects the login environment. --mode selects the app's Vite configuration; build, dev, and deploy default to development. Release builds require an explicit --mode.

App and service lifecycle#

Command	Reads / writes	ICE session
`waid app scan`	Reads frontend source and writes action candidates for review.	Not required
`waid app sync`	Submits an immutable App candidate to ICE Develop.	Required
`waid service scan`	Regenerates service MCP and dataset artifacts from source and curation.	Not required
`waid service sync`	Checks generated artifacts and submits a Service candidate to ICE Develop.	Required

Sync is a Develop operation. Publication, tenant installation, access grants, and activation are separate steps in ICE. A successful sync does not make a candidate live or deploy the service.

`waid app scan`#

Run from the frontend root containing package.json and src/, or pass it with --in. In an older project with a web/ folder, scan that frontend folder.

bash

waid app scan
waid app scan --in ./frontend
waid app scan --in ./frontend --check

The scan writes waid/app/generated/candidates.json with names, source locations, and route hints for review. No running app, URL, or prior registration is needed. --check compares the existing report with source and fails if it is absent or stale.

Candidates are not callable actions. Author input schemas, consent policies, and scoped invoke handlers before exposing them in your app's action catalog.

`waid app sync`#

bash

waid login --env local --tenant <tenant-key>
waid app sync --in ./frontend

Option	Behavior
`--in <app-root>`	App source root; defaults to the current project.
`--tenant <key>`	Select an administered tenant.
`--mode <name>`	Must match the signed-in ICE environment.

The default mode follows the session: local → development, staging → staging, and prod → production. An incompatible explicit mode is rejected. The app's hosted URL comes from WAID_WEB_URL in the selected mode environment.

Callable actions require authored handlers and a public .well-known/waid/actions.json catalog. Keep the scan report current before sync. ICE stores an immutable Develop candidate; publish and install it separately.

`waid service scan`#

Run from the JVM service source root, or pass that directory explicitly:

bash

waid service scan
waid service scan --in ./backend

The scan reads Java MCP handlers, REST operations, and entity metadata. It refreshes waid/backend/generated/candidates.json, capability-profile.json, descriptors.json, and the dataset model when datasets are exposed.

Review exposure decisions in waid/backend/curation.json; new candidates start denied and existing decisions are preserved. After changing source or curation, run waid service scan again. Edit the curation file, not generated artifacts.

`waid service sync`#

bash

# Local source-only candidate; no installed release is required
waid login --env local --tenant <tenant-key>
waid service sync --in ./backend
 
# Staging candidate tied to a verified release
waid login --env staging --tenant <tenant-key>
waid service sync --in ./backend --release <verified-release-id>

Option	Behavior
`--in <service-root>`	Service root; defaults to the current source root.
`--tenant <key>`	Select an administered tenant.
`--release <id>`	Verified splentactl release ID; required for staging. Local sync can omit it for a source-only candidate.
`--url <origin>`	Override the service origin declared in its environment profile.

The default origin comes from splenta.service.public-base-url in src/main/resources/application-<env>.properties. Local sync can fall back to server.port in application.properties and use a loopback origin.

Sync checks generated artifacts before any remote write and fails on drift. Run waid service scan, review the changes, then retry. Production service sync is rejected; production uses the splentactl promotion flow. Sync does not activate catalogs, tenant access, service accounts, or trust.

`waid new <name>`#

Create a Vite + React + Tailwind + shadcn project with waid.config.json, package.json, and src/ at the project root. waid init is an alias.

bash

waid new my-app
cd my-app
npm install

Option	Behavior
`--template web\|mobile`	Choose the starter; `web` is the default.
`--app-name <name>`	Set the display name.
`--android-package <id>`	Set the Android identity.
`--ios-bundle-id <id>`	Set the iOS identity.
`--force`, `-f`	Remove an existing destination and recreate it.

`waid dev`#

Run the live Vite module graph and launch Detir. Web edits use Vite HMR; native configuration changes can require a rebuild or reinstall.

bash

waid dev --in .
waid dev --in . --port 5173 --no-launch
waid dev --target ios --dev-host <your-lan-ip>

Option	Behavior
`--in <dir>`	App source root. Defaults to the current project.
`--target desktop\|ios\|android`	Preview target. Defaults to desktop.
`--mode <name>`	Vite mode. Defaults to `development`.
`--port <port>`	Pin the Vite server port; otherwise derived from the project.
`--dev-host <lan-ip>`	Required for iOS; available as an Android LAN fallback.
`--runtime-dir <dir>`	Use a specific native runtime.
`--no-launch`	Start only the managed Vite server.

`waid build`#

With no target, stage a web build. Native targets are macos, windows, linux, ios, and android; desktop means the current host OS.

bash

waid build --src . --mode production
waid build --target macos --mode production
waid build --target ios --simulator
waid build --target ios --release --mode production
waid build --target android --release --mode production --format aab

Option	Behavior
`--src <dir>`	Vite project root. Defaults to the current directory.
`--target <platform>`	Native platform; omit for web.
`--mode <name>`	Vite mode. Defaults to `development`; required with `--release`.
`--runtime-dir <dir>`	Override the native runtime.
`--out <dir>`	Override the package output directory.
`--clean`	Recreate the generated native project before building.
`--debug` / `--release`	Debug build or signed release. iOS release exports an App Store IPA.
`--format apk\|aab`	Android package format; defaults to APK.
`--android-package <id>`	Override the Android application ID.
`--android-keystore <path>`	Keystore for an Android release.
`--ios-team <id>`, `--ios-bundle-id <id>`, `--ios-profile <name>`	iOS identity and signing overrides.
`--ios-device-udid <udid>`	Select the iOS device.
`--simulator`, `--ios-destination device\|simulator`	Choose the iOS build destination.
`--ios-allow-provisioning-updates`, `--ios-no-sign`	Permit Xcode provisioning updates or produce an unsigned iOS build.

macOS builds produce an .app and DMG under .waid/build/macos/. Build does not install the app. See platform builds for outputs and signing.

`waid deploy`#

Build if needed, sync an ICE candidate, then install and launch on a connected mobile device. macOS uses waid build --target macos.

bash

waid devices --target ios --json
waid deploy --target ios
waid deploy --target android --no-launch

Option	Behavior
`--target ios\|android`	Required mobile target.
`--src <dir>`	App source root.
`--mode <name>`	Vite mode; defaults to `development`.
`--tenant <key>`	Tenant used for candidate synchronization.
`--no-launch`	Install without launching.
`--ios-device-udid <udid>`, `--android-serial <serial>`	Select a device; a single connected device is selected automatically.
`--skip-ice-registration`	Install without registration; device SSO is disabled. The CLI still requires a usable ICE session.

Diagnostics and maintenance#

bash

waid doctor
waid doctor android
waid doctor ios-signing --ios-bundle-id com.example.app
waid devices --target android --json
waid signing-teams --json
waid migrate-config --src .

doctor provides a basic CLI check; its Android and iOS subcommands inspect the respective tooling and signing prerequisites. migrate-config rewrites an older waid.config.json into the current shape; review its changes before committing.

waid clean --dir <dir> previews removal; add --force to delete that directory. The default is build, so specify the generated output you intend to clean:

bash

waid clean --dir .waid/build
waid clean --dir .waid/build --force

Catalog inspection and legacy helpers#

bash

waid apps --json
waid actions list --app <app-id> --json

Both use the signed-in account. Get the app ID from waid apps.

actions and backend remain legacy helper groups. Use app/service scan and sync for new work. Consult waid help actions or waid help backend when maintaining an older workflow.

waid ice-request --path <path> [--method GET|POST] [--body <json>] is an advanced helper for allowlisted tenant-app requests to the session's ICE issuer; it is not a general HTTP client.

CLI Reference

Sign in and check your session#

App and service lifecycle#

waid app scan#

waid app sync#

waid service scan#

waid service sync#

waid new <name>#

waid dev#

waid build#

waid deploy#

Diagnostics and maintenance#

Catalog inspection and legacy helpers#

`waid app scan`#

`waid app sync`#

`waid service scan`#

`waid service sync`#

`waid new <name>`#

`waid dev`#

`waid build`#

`waid deploy`#