@maccesar/titools 5.3.0 → 5.4.0

package/skills/ti-guides/references/cli-reference.md

@@ -1,716 +1,267 @@
-# Titanium CLI reference
+# CLI commands
 
-Reference for Titanium CLI commands, options, and configuration.
 
-<!-- TOC-START -->
-## Contents
+The CLI is `titanium`, and `ti` is the same binary. Ten commands.
 
-- [Environment setup](#environment-setup)
-- [Project commands](#project-commands)
-- [Build commands](#build-commands)
-- [Distribution commands](#distribution-commands)
-- [SDK management](#sdk-management)
-- [Configuration options](#configuration-options)
-- [Common issues](#common-issues)
-- [Command quick reference](#command-quick-reference)
-- [SDK version precedence](#sdk-version-precedence)
-- [References](#references)
+| Command      | Does                                               |
+| ------------ | -------------------------------------------------- |
+| `ti build`   | Builds a project, and installs and runs it         |
+| `ti clean`   | Removes previous build directories                 |
+| `ti config`  | Gets and sets CLI config options                   |
+| `ti create`  | Creates a project, module, or Apple Watch app      |
+| `ti info`    | Reports the development environment                |
+| `ti module`  | Lists installed modules                            |
+| `ti project` | Gets and sets `tiapp.xml` settings                 |
+| `ti sdk`     | Manages installed SDKs                             |
+| `ti serve`   | Serves a project through the Titanium Vite runtime |
+| `ti setup`   | Configures the CLI                                 |
 
-<!-- TOC-END -->
+Every command takes `--help`, and that output is generated from the CLI you
+have installed, so it is always the authority over this page.
 
-## Environment setup
+## Global options
 
-### Check environment
+These work on any command.
 
-```bash
-ti setup check
-```
-
-Reports configured tools and potential issues.
-
-### Setup wizard
-
-```bash
-ti setup
-ti setup <section>
-```
-
-Runs the interactive setup wizard. The `<section>` can be one of: quick, check, user, app, network, cli, sdk, ios, android, and paths.
+| Option                     | Effect                                                  |
+| -------------------------- | ------------------------------------------------------- |
+| `-d, --project-dir <path>` | The project to act on, instead of the working directory |
+| `-s, --sdk [version]`      | Build with a specific SDK rather than the newest        |
+| `--no-prompt`              | Never ask. **Required for scripting**                   |
+| `--no-banner`              | Drop the version banner                                 |
+| `--no-color`               | Drop ANSI colour                                        |
+| `--no-progress-bars`       | Drop progress bars                                      |
+| `-q, --quiet`              | Suppress output                                         |
+| `--config [json]`          | Mix a JSON object into the config for this run          |
+| `--config-file [file]`     | Use a different config file                             |
+| `--debug`                  | CLI's own debug logging                                 |
 
-### Get system info
-
-```bash
-ti info
-```
+`--no-prompt` turns a missing required option from a question into an error,
+which is what you want in CI and what makes a hung build impossible.
 
-Detailed environment info (SDKs, certificates, provisioning profiles).
+## ti build
 
-```bash
-ti info -p android  # Android-specific info
-ti info -p ios      # iOS-specific info
+```sh
+ti build --platform android
+ti build --platform ios --target device
 ```
 
-#### Info options
-
-| Option                 | Description                                                                                         |
-| ---------------------- | --------------------------------------------------------------------------------------------------- |
-| `-o, --output <value>` | Output format: report or json. Defaults to report.                                                  |
-| `-t, --types <value>`  | Comma-separated list of types: all, os, nodejs, titanium, ios, jdk, haxm, android. Defaults to all. |
-
-### Help
-
-Displays the help screen for the CLI or a specific command.
+`--platform` takes `android` or `ios`. `--target` defaults to `emulator` on
+Android and `simulator` on iOS.
 
-```bash
-ti help
-ti help <command>
-ti --help
-ti <command> --help
-```
+| Platform | Targets                                                                           |
+| -------- | --------------------------------------------------------------------------------- |
+| Android  | `emulator`, `device`, `dist-playstore`                                            |
+| iOS      | `simulator`, `device`, `dist-appstore`, `dist-adhoc`, `macos`, `dist-macappstore` |
 
-### Configure CLI
+Options worth knowing:
 
-```bash
-# Display current config
-ti config
+| Option                     | Effect                                |
+| -------------------------- | ------------------------------------- |
+| `-b, --build-only`         | Compile, do not install or run        |
+| `-f, --force`              | Full rebuild                          |
+| `-C, --device-id <id>`     | Which emulator, simulator or device   |
+| `-D, --deploy-type <type>` | `development`, `test` or `production` |
+| `--liveview`               | Reload the running app on save        |
+| `-l, --log-level <level>`  | `trace` to `error`                    |
+| `--skip-js-minify`         | Skip minification                     |
+| `--source-maps`            | Inline source maps for transpiled JS  |
 
-# Set option
-ti config cli.logLevel info
+Signing options are per platform: `-K/--keystore`, `-P/--store-password`,
+`-L/--alias` on Android; `-V/--developer-name`, `-R/--distribution-name`,
+`-P/--pp-uuid` on iOS. See
+[certificates and provisioning](https://titaniumsdk.com/docs/distribute/signing).
 
-# Append to path
-ti config -a paths.hooks "/path/to/hook"
+## ti create
 
-# Remove all Android options
-ti config -r android
+```sh
+ti create --type app --name Hello --id com.example.hello --platforms android,ios --workspace-dir .
 ```
 
-#### Config options
-
-| Option                 | Description                                                      |
-| ---------------------- | ---------------------------------------------------------------- |
-| `-a, --append`         | Append a value to a key containing a list of values.             |
-| `-r, --remove`         | Remove the specified config key and all its descendants.         |
-| `-o, --output <value>` | Output format: report, json, or json-object. Defaults to report. |
+`--type` is `app`, `module` or `applewatch`. With `--no-prompt`, **`--type` and
+`--workspace-dir` have no usable default** and must both be passed.
 
-Alternative methods:
-```bash
-# Pass JSON string
-ti build -p ios --config "{ paths: { hooks: '/path/to/hook' } }"
-
-# Pass JSON file
-ti build -p ios --config-file "/Users/me/customConfig.json"
-```
+`--alloy` runs `alloy new` on the project afterwards, which needs Alloy
+installed. `--template` takes a template name, a directory, a zip or a URL.
 
----
+`--platforms` accepts `android`, `ios` and `iphone`. `ios` targets iPhone and
+iPad; `iphone` targets iPhone only.
 
-## Project commands
-
-### Create project
-
-For Alloy projects (recommended):
-```bash
-ti create -t app --alloy --id <APP_ID> -n <APP_NAME> -p <PLATFORMS> -d <WORKSPACE> -u <URL>
-```
-
-Example (Alloy):
-```bash
-ti create -t app --alloy --id com.titaniumsdk.sample -n SampleProject -p android,ios -d ~/Documents/workspace -u https://titaniumsdk.com
-```
-
-For Classic Titanium projects:
-```bash
-ti create -t app --id <APP_ID> -n <APP_NAME> -p <PLATFORMS> -d <WORKSPACE> -u <URL>
-```
-
-Parameters:
-- `--alloy`: create an Alloy project (recommended for new projects)
-- `-t, --type`: project type: app (default), applewatch, module (or timodule)
-- `--id`: app ID (reverse domain notation)
-- `-n, --name`: app name
-- `-p, --platforms`: comma-separated platforms (`android`, `ios`, `ipad`, `iphone`)
-- `-d, --workspace-dir`: workspace directory
-- `-u, --url`: app URL
-- `-f, --force`: force creation even if the path already exists
-- `--template`: project template to use (name, directory, ZIP file, or remote ZIP URL)
-- `-s, --sdk`: Titanium SDK version to use
-
-Use `--alloy` for new projects. Use Classic (`--classic` or omitting `--alloy`) only for legacy projects.
-
-### Build project
-
-```bash
-ti build -p <PLATFORM> [OPTIONS]
-```
-
-### Project management
-
-```bash
-ti project [OPTIONS] [<key>] [<value>]
-```
+## ti info
 
-Gets and sets `tiapp.xml` settings. When called with a key, returns the value. When called with a key and value, sets the value in `tiapp.xml`.
-
-It also allows you to set deployment targets using a comma-separated list of platforms. If a platform is enabled for the first time, it will copy default resources into the project Resources folder without overwriting.
-
-Examples:
-```bash
-# Get a tiapp.xml value
-ti project sdk-version
-
-# Set a tiapp.xml value
-ti project sdk-version 12.2.0.GA
-
-# Set deployment targets (must list all desired platforms)
-ti project deployment-targets iphone,ipad,android
-```
-
-Tasks:
-- `scan`: scan a directory for Titanium projects
-
-Options:
-
-| Option                      | Description                                                              |
-| --------------------------- | ------------------------------------------------------------------------ |
-| `-o, --output <value>`      | Output format: report, json, or text. Defaults to report.                |
-| `--project-dir <directory>` | Directory containing the project. Defaults to current working directory. |
-
----
-
-## Build commands
-
-### Generic build options and flags
-
-| Option                          | Description                                                                                              |
-| ------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `-b, --build-only`              | Only perform the build; does not install or run the app.                                                 |
-| `-f, --force`                   | Force a clean rebuild.                                                                                   |
-| `--skip-js-minify`              | Bypass JavaScript minification. Simulator builds are never minified. Only supported for Android and iOS. |
-| `--log-level <level>`           | Minimum logging level: trace, debug, info, warn, error.                                                  |
-| `-p, --platforms <platform>`    | Target build platform: android or ios (iphone and ipad are accepted as synonyms for ios).                |
-| `-d, --project-dir <directory>` | Directory containing the project. Defaults to current working directory.                                 |
-| `-s, --sdk <version>`           | Titanium SDK version to build with.                                                                      |
-
-### Android emulator
-
-```bash
-ti build -p android [-C <EMULATOR_NAME>]
-```
-
-Example:
-```bash
-ti build -p android -C "Google Nexus 7 - 4.4.2 - API 19 - 800x1280"
-```
-
-List emulators: `ti info -p android`
-
-### Android device
-
-```bash
-ti build -p android -T device -C <DEVICE_ID>
-```
-
-Example:
-```bash
-ti build -p android -T device -C deadbeef
-```
-
-Omit `-C` if only one device is connected.
-
-### Android build options
-
-| Option                            | Description                                                                                           |
-| --------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `-A, --android-sdk <path>`        | Path to the Android SDK.                                                                              |
-| `-C, --device-id <name>`          | Name of the device or emulator. Use "all" with --target "device" to install on all connected devices. |
-| `-D, --deploy-type <type>`        | Controls optimization, encryption, analytics: development, test, production.                          |
-| `-K, --keystore <path>`           | Location of the keystore file.                                                                        |
-| `--key-password <keypass>`        | Password of the keystore private key. Defaults to --store-password value.                             |
-| `--liveview`                      | Start a LiveView session for live UI previews.                                                        |
-| `-L, --alias <alias>`             | Alias for the keystore.                                                                               |
-| `--no-launch`                     | Disable launching the app after installing.                                                           |
-| `-O, --output-dir <dir>`          | Output directory (used when target is dist-playstore).                                                |
-| `-P, --store-password <password>` | Password for the keystore.                                                                            |
-| `--sigalg <algorithm>`            | Digital signature algorithm: MD5withRSA, SHA1withRSA, SHA256withRSA.                                  |
-| `-T, --target <value>`            | Target: emulator, device, or dist-playstore.                                                          |
-
-### iOS simulator
-
-```bash
-ti build -p ios [-C <SIMULATOR_NAME>]
+```sh
+ti info
+ti info -t android --json
 ```
 
-Example:
-```bash
-ti build -p ios -C "iPad Retina"
-```
+`-t/--types` narrows to one area, and `--json` makes it machine-readable. This
+is the first command to run when a build breaks for no visible reason.
 
-### iOS device
+## ti sdk
 
-```bash
-ti build -p ios -T device -C <DEVICE_UDID> [-V "<CERT_NAME>" -P <PROFILE_UUID>]
+```sh
+ti sdk list
+ti sdk install 13.4.1.GA
+ti sdk uninstall 13.3.0.GA
 ```
 
-Example:
-```bash
-ti build -p ios -T device -C itunes -V "Loretta Martin (GE7BAC5)" -P "11111111-2222-3333-4444-555555555555"
-```
+`install` with no version takes the newest stable. `-b/--branch` installs from
+a CI branch.
 
-Omit `-V` and `-P` to be prompted.
-
-### iOS build options
-
-| Option                           | Description                                                                                            |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `-C, --device-id <name>`         | Name of the device or simulator. Use "all" with --target "device" to install on all connected devices. |
-| `-D, --deploy-type <type>`       | Controls optimization, encryption, analytics: development, test, production.                           |
-| `-F, --device-family <value>`    | Device family: iphone, ipad, or universal (default).                                                   |
-| `--force-copy`                   | Force files to be copied instead of symlinked (simulator builds only).                                 |
-| `-I, --ios-version <value>`      | iOS SDK version to build for. Default: latest installed.                                               |
-| `-K, --keychain <value>`         | Path to distribution keychain (for device/dist targets).                                               |
-| `--launch-bundle-id <id>`        | After installing in simulator, launch a different app (useful for test runners).                       |
-| `--launch-watch-app`             | Launch both the watch app and main app (simulator only).                                               |
-| `--launch-watch-app-only`        | Launch only the watch app (simulator only).                                                            |
-| `-O, --output-dir <dir>`         | Output directory (used when target is dist-adhoc).                                                     |
-| `-P, --pp-uuid <uuid>`           | Provisioning profile UUID (for device/dist targets).                                                   |
-| `-R, --distribution-name <name>` | iOS Distribution Certificate (for dist targets).                                                       |
-| `--sim-focus`                    | Focus the iOS Simulator after launching (default: true). Use --no-sim-focus to disable.                |
-| `-T, --target <value>`           | Target: simulator, device, dist-appstore, dist-adhoc, macos, or dist-macappstore.                            |
-| `-V, --developer-name <name>`    | iOS Developer Certificate (required for device target).                                                |
-| `-W, --watch-device-id <udid>`   | Watch simulator UDID (simulator only).                                                                 |
-| `--watch-app-name <name>`        | Name of the watch app to launch (simulator only).                                                      |
-| `-Y, --sim-type <type>`          | iOS Simulator type: iphone or ipad (simulator only).                                                   |
-
-### Clean build
-
-```bash
-ti clean [-p <PLATFORM>]
-```
+## ti config
 
-Examples:
-```bash
-ti clean          # All platforms
-ti clean -p ios   # iOS only
+```sh
+ti config                                   # print everything
+ti config android.sdkPath /path/to/sdk      # set one
+ti config paths.modules --append /path      # add to a list
+ti config paths.modules --remove /path      # take one out
 ```
 
-#### Clean options
-
-| Option                          | Description                                                              |
-| ------------------------------- | ------------------------------------------------------------------------ |
-| `-p, --platforms <platform>`    | A single platform to clean: android or ios.                              |
-| `-d, --project-dir <directory>` | Directory containing the project. Defaults to current working directory. |
-| `-s, --sdk <version>`           | Titanium SDK version.                                                    |
-| `--log-level <level>`           | Minimum logging level: trace, debug, info, warn, error.                  |
+See [CLI configuration](https://titaniumsdk.com/docs/reference/config) for the keys.
 
-### Module management
+## ti project
 
-```bash
-ti module [TASK] [OPTIONS]
-```
-
-Tasks:
-- `create`: create a new Titanium module
-- `list`: list installed Titanium modules
+Reads and writes `tiapp.xml` without a text editor, which is what to use in a
+release script:
 
-#### Module create
-
-```bash
-ti create -t module --id <MODULE_ID> -n <MODULE_NAME> -p <PLATFORMS> -d <WORKSPACE>
+```sh
+ti project version 1.2.0
+ti project --output json
 ```
 
-Parameters:
-- `-t, --type`: set to module (or timodule)
-- `--id`: module ID (reverse domain notation)
-- `-n, --name`: module name
-- `-p, --platforms`: target platforms
-- `-d, --workspace-dir`: workspace directory
-- `-f, --force`: force creation even if path already exists
-- `--template`: module template to use
-
-#### Module list
+## ti module
 
-Prints a list of installed modules.
-
-```bash
-ti module
+```sh
 ti module list
-ti module list --project-dir /path/to/project
-```
-
-Options:
-
-| Option                  | Description                                                                 |
-| ----------------------- | --------------------------------------------------------------------------- |
-| `-o, --output <value>`  | Output format: report, json, or grid. Defaults to report.                   |
-| `--project-dir <value>` | Directory of the project to analyze. Defaults to current working directory. |
-
-### Plugin management
-
-```bash
-ti plugin [TASK] [OPTIONS]
 ```
 
-#### Plugin list
+`list` is the only subcommand. It reports project, configured-path and global
+scopes, so it also answers which copy of a module a build will use.
 
-Prints a list of installed plugins.
+## ti clean
 
-```bash
-ti plugin
-ti plugin list
-ti plugin list --project-dir /path/to/project
+```sh
+ti clean
+ti clean --platforms android
 ```
 
-Options:
+Removes `build/`. Worth doing when a failure does not match the source.
 
-| Option                  | Description                                                                 |
-| ----------------------- | --------------------------------------------------------------------------- |
-| `-o, --output <value>`  | Output format: report, json, or grid. Defaults to report.                   |
-| `--project-dir <value>` | Directory of the project to analyze. Defaults to current working directory. |
+## ti setup
 
----
+An interactive wizard. `ti setup check` is the useful non-interactive part, and
+overlaps `ti info`.
 
-## Distribution commands
+## CLI configuration keys
 
-### Google Play (Android)
-
-```bash
-ti build -p android -T dist-playstore [-K <KEYSTORE> -P <PASSWORD> -L <ALIAS> -O <OUTPUT>]
-```
 
-Example:
-```bash
-ti build -p android -T dist-playstore -K ~/android.keystore -P secret -L foo -O ./dist/
-```
+The CLI stores its own settings, separately from any project. They live in
+`~/.titanium/config.json`, and `ti config` is how to read and write them.
 
-If key password differs from keystore password:
-```bash
---key-password <KEYPASS>
+```sh
+ti config                                  # everything
+ti config cli.logLevel                     # one key
+ti config cli.logLevel info                # set it
+ti config cli.logLevel --remove            # back to the default
 ```
 
-### Ad Hoc (iOS)
-
-```bash
-ti build -p ios -T dist-adhoc [-R <CERT_NAME> -P <PROFILE_UUID> -O <OUTPUT>]
-```
+The path is printed by `ti config --help`, so a machine that keeps it elsewhere
+will say so.
 
-Example:
-```bash
-ti build -p ios -T dist-adhoc -R "Pseudo, Inc." -P "FFFFFFFF-EEEE-DDDD-CCCC-BBBBBBBBBBBB" -O ./dist/
-```
+### Keys
 
-### App Store (iOS)
-
-```bash
-ti build -p ios -T dist-appstore [-R <CERT_NAME> -P <PROFILE_UUID>]
-```
-
-Example:
-```bash
-ti build -p ios -T dist-appstore -R "Pseudo, Inc." -P "AAAAAAAA-0000-9999-8888-777777777777"
-```
-
-Installs the package to Xcode Organizer.
-
-### Mac Catalyst (macOS Development)
-
-```bash
-ti build -p ios -T macos
-```
-
-Builds a Mac Catalyst version of your iOS app for local testing. The resulting `.app` bundle is located at:
-```
-build/iphone/build/Products/Debug-maccatalyst/AppName.app
-```
-
-For a production build:
-```bash
-ti build -p ios -T macos --deploy-type production
-```
-
-The release `.app` bundle will be at:
-```
-build/iphone/build/Products/Release-maccatalyst/AppName.app
-```
-
-### Mac App Store (Mac Catalyst Distribution)
-
-```bash
-ti build -p ios -T dist-macappstore [-R <CERT_NAME>]
-```
-
-Example:
-```bash
-ti build -p ios -T dist-macappstore -R "Apple Distribution: Your Name (TEAM_ID)"
-```
-
-**Important Notes:**
-- Requires a Mac App Store Distribution Certificate (not iOS Distribution)
-- The build creates an archive for Mac App Store distribution
-- The `.xcarchive` is installed in Xcode's Organizer
-- Uses `Release-maccatalyst` configuration
-- Destination: `generic/platform=macOS`
-- Code signing is set to Manual with identity `-`
-
-The target `dist-macappstore` is available in Titanium SDK 13.1.1.GA and later.
-
----
-
-## SDK management
-
-### List SDKs
-
-```bash
-ti sdk list
-```
-
-Options:
+### Paths
 
-| Option                 | Description                                        |
-| ---------------------- | -------------------------------------------------- |
-| `-b, --branches`       | Retrieve and print all branches.                   |
-| `-r, --releases`       | Retrieve and print all releases.                   |
-| `-o, --output <value>` | Output format: report or json. Defaults to report. |
+| Key              | What                                     |
+| ---------------- | ---------------------------------------- |
+| `paths.sdks`     | Extra directories to find SDKs in        |
+| `paths.modules`  | Extra directories to find modules in     |
+| `paths.plugins`  | Extra directories to find CLI plugins in |
+| `paths.commands` | Extra CLI commands                       |
+| `paths.hooks`    | Extra build hooks                        |
 
-### Select SDK
+These take lists, so they have `--append` and `--remove`:
 
-```bash
-ti sdk select [<version>]
+```sh
+ti config paths.modules --append ~/shared/modules
 ```
 
-Interactive selection of default SDK. This sets the SDK used to run CLI commands. If the `tiapp.xml` file does not contain an SDK version and the `app.sdk` setting is not set, the application will be built with this SDK.
-
-### Install SDK
+A path added here applies to every project on the machine, which makes a build
+depend on the machine. It is useful for a shared module cache and a liability
+for anything a colleague needs too.
 
-Downloads the latest Titanium SDK or a specific version.
-
-```bash
-ti sdk install [<version>] [--default] [--force] [--branch <branch_name>]
-```
+### Android
 
-`<version>` may be a specific version number (for example, `12.2.0.GA`), a URL to a ZIP file, or a local ZIP file path.
+| Key                                  | What                                       |
+| ------------------------------------ | ------------------------------------------ |
+| `android.sdkPath`                    | Where the Android SDK is                   |
+| `android.ndkPath`                    | Where the NDK is, if you build native code |
+| `android.buildTools.selectedVersion` | Pin build tools when the newest is too new |
 
-Options:
+`android.sdkPath` is what `ti setup android` writes, and it is the answer to
+"the build cannot find the Android SDK" - not an environment variable.
+`ANDROID_HOME` is **not** read by the app build; the detection order is this
+config key, then `ANDROID_SDK_ROOT`, then `ANDROID_SDK`, then `adb` on `PATH`.
 
-| Option                       | Description                          |
-| ---------------------------- | ------------------------------------ |
-| `-d, --default`              | Set as the default SDK.              |
-| `-f, --force`                | Force reinstallation.                |
-| `-k, --keep-files`           | Keep downloaded files after install. |
-| `-b, --branch <branch_name>` | Branch to install from, or "latest". |
+### iOS
 
-### Uninstall SDK
+| Key                    | What                             |
+| ---------------------- | -------------------------------- |
+| `ios.developerName`    | Default development certificate  |
+| `ios.distributionName` | Default distribution certificate |
 
-Uninstalls a specific Titanium SDK version.
+Setting these saves passing `--developer-name` on every device build.
 
-```bash
-ti sdk uninstall [<version>] [--force]
-```
+### CLI behaviour
 
-Options:
+| Key                      | Default | What                                  |
+| ------------------------ | ------- | ------------------------------------- |
+| `cli.logLevel`           | `trace` | Default verbosity                     |
+| `cli.colors`             | `true`  | ANSI colour                           |
+| `cli.progressBars`       | `true`  | Progress bars                         |
+| `cli.prompt`             | `true`  | Ask for missing values                |
+| `cli.width`              | `80`    | Wrap width                            |
+| `cli.completion`         | `false` | Shell completion                      |
+| `cli.httpProxyServer`    | empty   | Proxy for CLI requests                |
+| `cli.rejectUnauthorized` | `true`  | Verify TLS on CLI requests            |
+| `cli.ignoreDirs`         | a regex | Directories never copied into a build |
+| `cli.ignoreFiles`        | a regex | Files never copied into a build       |
 
-| Option        | Description                                |
-| ------------- | ------------------------------------------ |
-| `-f, --force` | Force uninstallation without confirmation. |
+> [!WARNING]
+> `cli.rejectUnauthorized false` disables certificate verification for
+> everything the CLI fetches, including SDK downloads. If a corporate proxy is
+> the reason, set `cli.httpProxyServer` instead and leave verification on.
 
-### Update SDK
+`cli.ignoreDirs` and `cli.ignoreFiles` are why `.git` and `.DS_Store` do not end
+up inside your app. Widen them to keep something else out; replacing them
+wholesale is how a `.git` directory ships to the store.
 
-Finds the latest version of the Titanium SDK and optionally installs it.
+### App
 
-```bash
-ti sdk update [--default] [--force] [--install] [--branch <branch_name>]
-```
+| Key             | What                               |
+| --------------- | ---------------------------------- |
+| `app.workspace` | Default directory for new projects |
+| `user.name`     | Name used in generated files       |
 
-Options:
-
-| Option                       | Description                 |
-| ---------------------------- | --------------------------- |
-| `-d, --default`              | Set as the default SDK.     |
-| `-f, --force`                | Force reinstallation.       |
-| `-i, --install`              | Install the latest version. |
-| `-b, --branch <branch_name>` | Branch to update from.      |
-
----
-
-## Configuration options
-
-### Android options
-
-| Option                               | Default     | Description                      |
-| ------------------------------------ | ----------- | -------------------------------- |
-| `android.sdkPath`                    | auto        | Android SDK path                 |
-| `android.ndkPath`                    | auto        | Android NDK path                 |
-| `android.adb.port`                   | 5037        | ADB port number                  |
-| `android.autoSelectDevice`           | true        | Auto-select device/emulator      |
-| `android.symlinkResources`           | true (OS X) | Symlink vs copy resources        |
-| `android.buildTools.selectedVersion` | max         | Build tools version              |
-| `android.javac.maxmemory`            | "3072M"     | JVM heap size                    |
-| `android.javac.source`               | "1.8"       | Java source version              |
-| `android.javac.target`               | "1.8"       | Java target version              |
-| `android.mergeCustomAndroidManifest` | false       | Merge custom AndroidManifest.xml |
-
-The `android.javac.source` and `android.javac.target` defaults were originally "1.6" in earlier SDK versions. Modern Titanium SDK requires Java 1.8 or higher. You can override these per-project in `tiapp.xml` using `<property name="android.javac.source" type="string">1.8</property>`.
-
-### iOS options
-
-| Option                 | Default     | Description                           |
-| ---------------------- | ----------- | ------------------------------------- |
-| `ios.developerName`    | -           | Developer certificate name            |
-| `ios.distributionName` | -           | Distribution certificate name         |
-| `ios.autoSelectDevice` | true        | Auto-select device/simulator          |
-| `ios.symlinkResources` | true (OS X) | Symlink vs copy resources             |
-| `ios.keychain`         | -           | Specific keychain to search for certs |
-| `ios.xcodePath`        | auto        | Path to Xcode installation            |
-
-### CLI options
-
-| Option                   | Default | Description                                   |
-| ------------------------ | ------- | --------------------------------------------- |
-| `cli.logLevel`           | trace   | Log level: error, warning, info, debug, trace |
-| `cli.colors`             | true    | Color output                                  |
-| `cli.progressBars`       | true    | Show progress bars                            |
-| `cli.prompt`             | true    | Prompt for missing info                       |
-| `cli.quiet`              | false   | Suppress all output                           |
-| `cli.rejectUnauthorized` | true    | Reject bad SSL certs                          |
-| `cli.width`              | 100     | Text wrap width                               |
-| `cli.failOnWrongSDK`     | false   | Fail on SDK mismatch                          |
-| `cli.hideCharEncWarning` | false   | Hide encoding warnings                        |
-| `cli.httpProxyServer`    | -       | Proxy server URL                              |
-
-### SDK options
-
-| Option                       | Description                        |
-| ---------------------------- | ---------------------------------- |
-| `sdk.defaultInstallLocation` | SDK install location (OS-specific) |
-| `sdk.selected`               | Selected SDK version (required)    |
+## Per-run overrides
 
-### Paths
+`--config` takes JSON and applies for that run only, which is the way to script
+something without changing the machine:
 
-| Option           | Description                    |
-| ---------------- | ------------------------------ |
-| `paths.commands` | Additional CLI command scripts |
-| `paths.hooks`    | CLI hook scripts               |
-| `paths.modules`  | Module search paths            |
-| `paths.plugins`  | Plugin search paths            |
-| `paths.sdks`     | SDK search paths               |
-| `paths.xcode`    | Xcode installation paths       |
-
-### Java options
-
-| Option                       | Description               |
-| ---------------------------- | ------------------------- |
-| `java.home`                  | JDK directory             |
-| `java.executables.java`      | java executable path      |
-| `java.executables.javac`     | javac executable path     |
-| `java.executables.jarsigner` | jarsigner executable path |
-| `java.executables.keytool`   | keytool executable path   |
-
-### Genymotion options
-
-| Option                              | Description                               |
-| ----------------------------------- | ----------------------------------------- |
-| `genymotion.enabled`                | Enable Genymotion support                 |
-| `genymotion.home`                   | Genymotion virtual machine data directory |
-| `genymotion.path`                   | Genymotion app directory                  |
-| `genymotion.executables.genymotion` | genymotion executable                     |
-| `genymotion.executables.player`     | player executable                         |
-| `genymotion.executables.vboxmanage` | vboxmanage executable                     |
-
-### Application options
-
-| Option                      | Description                 |
-| --------------------------- | --------------------------- |
-| `app.idprefix`              | Prefix for new app IDs      |
-| `app.publisher`             | Default publisher           |
-| `app.url`                   | Default company URL         |
-| `app.workspace`             | Default workspace directory |
-| `app.skipAppIdValidation`   | Skip app ID validation      |
-| `app.skipVersionValidation` | Skip version validation     |
-
----
-
-## Common issues
-
-### Android SDK not found
-
-```bash
-! sdk                Android SDK not found
-! targets            no targets found
-! avds               no avds found
+```sh
+ti build --platform android --config '{"cli":{"logLevel":"warn"}}'
 ```
 
-Solution:
-```bash
-ti config android.sdkPath /path/to/android-sdk
-```
+`--config-file` points at a different file entirely, which is how CI can carry
+its own settings without touching a developer's.
 
-### Xcode too old
+## What is not here
 
-```bash
-! Xcode 4.3 is too old and is no longer supported by Titanium SDK 3.3.0
-```
-
-Solution: install a newer Xcode from the Mac App Store.
+Anything about the app itself - id, name, version, permissions, modules - is in
+`tiapp.xml`, not here. See [tiapp.xml](https://titaniumsdk.com/docs/reference/tiapp-xml). The rule is
+that this file describes the machine and `tiapp.xml` describes the app, which
+is also why this one is not in version control and that one is.
 
-### Clean build issues
-
-```bash
-ti clean -p ios
-ti clean -p android
-```
-
-### ADB device issues
-
-```bash
-adb kill-server
-adb start-server
-adb devices
-```
+## Release scope
 
----
-
-## Command quick reference
-
-| Command                      | Description                                                                                  |
-| ---------------------------- | -------------------------------------------------------------------------------------------- |
-| `ti help`                    | Display help screen                                                                          |
-| `ti help <command>`          | Display help for a specific command                                                          |
-| `ti setup`                   | Run setup wizard                                                                             |
-| `ti setup check`             | Check environment setup                                                                      |
-| `ti setup <section>`         | Run specific setup section (quick, check, user, app, network, cli, sdk, ios, android, paths) |
-| `ti info`                    | Display system info                                                                          |
-| `ti info -p <PLATFORM>`      | Platform-specific info                                                                       |
-| `ti info -o json`            | Output system info as JSON                                                                   |
-| `ti config`                  | Display/set config                                                                           |
-| `ti config -o json`          | Output config as JSON                                                                        |
-| `ti create`                  | Create new project                                                                           |
-| `ti create -t module`        | Create new module                                                                            |
-| `ti build`                   | Build project                                                                                |
-| `ti build -b`                | Build only (no install/launch)                                                               |
-| `ti build -f`                | Force clean rebuild                                                                          |
-| `ti clean`                   | Clean build folder                                                                           |
-| `ti clean -p <PLATFORM>`     | Clean specific platform                                                                      |
-| `ti project`                 | Get/set tiapp.xml settings                                                                   |
-| `ti module list`             | List installed modules                                                                       |
-| `ti plugin list`             | List installed plugins                                                                       |
-| `ti sdk list`                | List installed SDKs                                                                          |
-| `ti sdk select`              | Select default SDK                                                                           |
-| `ti sdk install`             | Install latest SDK                                                                           |
-| `ti sdk install <version>`   | Install specific SDK                                                                         |
-| `ti sdk uninstall <version>` | Uninstall specific SDK                                                                       |
-| `ti sdk update`              | Check for SDK updates                                                                        |
-
----
-
-## SDK version precedence
-
-1. `tiapp.xml` `<sdk-version>` tag
-2. `--sdk` CLI option
-3. `app.sdk` config setting
-4. Selected SDK (`ti sdk select`)
-
----
-
-## References
-
-- Titanium CLI GitHub: https://github.com/tidev/titanium-cli
-- Android SDK Manager: http://developer.android.com/sdk
-- Xcode Downloads: https://apps.apple.com/us/app/xcode/id497799835?mt=12/
+CLI commands and SDK build support are versioned separately. `ti serve` belongs to the Vite integration: check installed `ti serve --help` and the runtime's supported SDK versions before adopting it in a released 13.4.1 project. Do not infer SDK 14 GA from a command listed by a newer CLI. For API contracts use the project's versioned reference.