unity-cli@v1.6.0 (#47)

- fix floating license activations
  - added `activate-license --json` optional arg for json output of floating license token
  - added `return-license -t <token> | --token <token>` arg. Required for returning floating license
- added `license-context` to get the license context details
- added `licensing-logs` to get the path to the license client log
- fix macOS editor `run` with Rosetta editor env ags (uses base args as all the other platforms)
- updated GitHub annotation handling for richer, clickable annotations in the Checks UI
  - added unit tests
  - added docs
- refactor editor logging features
  -  ***experimental!*** introduced `--log-level` to `run <args>` to only log the utp messages and print tables for builds timing and error logs and unit tests
- bump deps

Author: StephenHodgson

README.md

@@ -28,6 +28,9 @@ A powerful command line utility for the Unity Game Engine. Automate Unity projec
       - [Run Unity Editor Commands](#run-unity-editor-commands)
     - [Unity Package Manager](#unity-package-manager)
       - [Sign a Unity Package](#sign-a-unity-package)
+- [Logging](#logging)
+  - [Local cli](#local-cli)
+  - [Github Actions](#github-actions)
 
 ## Features
 
@@ -88,6 +91,7 @@ unity-cli license-version
 - `-p`, `--password`: Password for the Unity account. Required when activating a personal or professional license.
 - `-s`, `--serial`: License serial number. Required when activating a professional license.
 - `-c`, `--config`: Path to the configuration file, or base64 encoded JSON string. Required when activating a floating license.
+- `--json`: Prints the last line of output as JSON string.
 - `--verbose`: Enable verbose output.
 
 ```bash
@@ -99,12 +103,29 @@ unity-cli activate-license --license personal --email <your-email> --password <y
 `return-license [options]`: Return a Unity license.
 
 - `-l`, `--license`: License type (personal, professional, floating)
+- `-t`, `--token`: Floating license token. Required when returning a floating license.
 - `--verbose`: Enable verbose output.
 
 ```bash
 unity-cli return-license --license personal
 ```
 
+#### License Context
+
+`license-context`: Prints the current license context information.
+
+```bash
+unity-cli license-context
+```
+
+#### Licensing Logs
+
+`licensing-logs`: Prints the Unity licensing logs.
+
+```bash
+unity-cli licensing-logs
+```
+
 #### Unity Hub
 
 ##### Hub Version
@@ -259,9 +280,15 @@ unity-cli open-project
 - `--unity-editor <unityEditor>` The path to the Unity Editor executable. If unspecified, `--unity-project` or the `UNITY_EDITOR_PATH` environment variable must be set.
 - `--unity-project <unityProject>` The path to a Unity project. If unspecified, the `UNITY_PROJECT_PATH` environment variable will be used, otherwise no project will be specified.
 - `--log-name <logName>` The name of the log file.
-- `--verbose` Enable verbose logging.
+- `--log-level <logLevel>` Override the logger verbosity (`debug`, `info`, `minimal`, `warning`, `error`). Defaults to `info`.
+- `--verbose` Enable verbose logging. (Deprecated, use `--log-level <value>` instead)
 - `<args...>` Arguments to pass directly to the Unity Editor executable.
 
+> [!NOTE]
+> When setting the `--log-level` option to `minimal`, only the unity telemetry logs will be shown in the console output. All other logs will be written to the log file. This option is only supported when running the command locally in the terminal. ***This options is still experimental and may change in future releases.***
+>
+> When running in CI environments the logger will automatically print the full logs to the console no matter the log level.
+
 ```bash
 unity-cli run --unity-project <path-to-project> -quit -batchmode -executeMethod StartCommandLineBuild
 ```
@@ -288,3 +315,37 @@ unity-cli run --unity-project <path-to-project> -quit -batchmode -executeMethod
 ```bash
 unity-cli sign-package --package <path-to-package-folder> --email <your-email> --password <your-password> --organization <your-organization-id>
 ```
+
+## Logging
+
+### Local cli
+
+`unity-cli` keeps regular terminal runs simple:
+
+- Writes everything to `stdout` with ANSI colors (yellow warnings, red errors) so you can scan logs quickly.
+- `startGroup`/`endGroup` just print headers and content, and don't include any foldouts or collapsing behavior and is meant for CI environments only.
+
+### Github Actions
+
+When `GITHUB_ACTIONS=true`, the logger emits GitHub workflow commands automatically:
+
+- Defaults to `info` level; add `--verbose` (or temporarily set `ACTIONS_STEP_DEBUG=true`) to surface `debug` lines.
+- `Logger.annotate(...)` escapes `%`, `\r`, and `\n`, then includes `file`, `line`, `endLine`, `col`, `endColumn`, and `title` metadata so annotations are clickable in the Checks UI.
+- `startGroup`/`endGroup` become `::group::` / `::endgroup::` blocks.
+- Helper methods (`CI_mask`, `CI_setEnvironmentVariable`, `CI_setOutput`, `CI_appendWorkflowSummary`) write to the corresponding GitHub-provided files, so secrets stay masked and workflow outputs update automatically.
+
+The same command line you run locally therefore produces colorized console output on your machine and rich annotations once it runs inside Actions.
+
+### Additional CI Environments
+
+At the moment, only GitHub Actions is supported for enhanced logging. If you would like to see support for additional CI environments, please open a pull request or feature request on the GitHub repository.
+
+#### Roadmap
+
+- [ ] Support Azure DevOps logging commands
+- [ ] Support GitLab CI logging commands
+- [ ] Support Bitbucket Pipelines logging commands
+- [ ] Support Jenkins logging commands
+- [ ] Support CircleCI logging commands
+- [ ] Support Travis CI logging commands
+- [ ] Support TeamCity logging commands

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@rage-against-the-pixel/unity-cli",
-  "version": "1.5.5",
+  "version": "1.6.0",
   "description": "A command line utility for the Unity Game Engine.",
   "author": "RageAgainstThePixel",
   "license": "MIT",
@@ -49,7 +49,7 @@
   },
   "dependencies": {
     "@electron/asar": "^4.0.1",
-    "@rage-against-the-pixel/unity-releases-api": "^1.0.3",
+    "@rage-against-the-pixel/unity-releases-api": "^1.0.4",
     "commander": "^14.0.2",
     "glob": "^11.1.0",
     "semver": "^7.7.3",

package.json

@@ -44,6 +44,7 @@ program.command('activate-license')
     .option('-s, --serial <serial>', 'License serial number. Required when activating a professional license.')
     .option('-c, --config <config>', 'Path to the configuration file, or base64 encoded JSON string. Required when activating a floating license.')
     .option('--verbose', 'Enable verbose logging.')
+    .option('--json', 'Prints the last line of output as JSON string.')
     .action(async (options) => {
         if (options.verbose) {
             Logger.instance.logLevel = LogLevel.DEBUG;
@@ -80,19 +81,25 @@ program.command('activate-license')
             }
         }
 
-        await client.Activate({
+        const token = await client.Activate({
             licenseType,
             servicesConfig: options.config,
             serial: options.serial,
             username: options.email,
             password: options.password
         });
+
+        if (licenseType === LicenseType.floating && token && options.json) {
+            process.stdout.write(`\n${JSON.stringify({ token: token })}\n`);
+        }
+
         process.exit(0);
     });
 
 program.command('return-license')
     .description('Return a Unity license.')
     .option('-l, --license <license>', 'License type (personal, professional, floating)')
+    .option('-t, --token <token>', 'Token received when acquiring a floating license lease. Required when returning a floating license.')
     .option('--verbose', 'Enable verbose logging.')
     .action(async (options) => {
         if (options.verbose) {
@@ -116,7 +123,36 @@ program.command('return-license')
             process.exit(1);
         }
 
-        await client.Deactivate(licenseType);
+        let token: string | undefined = options.token;
+
+        if (licenseType === LicenseType.floating) {
+            if (!token || token.length === 0) {
+                token = await PromptForSecretInput('Token: ');
+            }
+
+            if (!token || token.length === 0) {
+                Logger.instance.error('Token is required when returning a floating license. Use -t or --token to specify it.');
+                process.exit(1);
+            }
+        }
+
+        await client.Deactivate(licenseType, token);
+        process.exit(0);
+    });
+
+program.command('license-context')
+    .description('Display the context information of the Unity Licensing Client.')
+    .action(async () => {
+        const client = new LicensingClient();
+        await client.Context();
+        process.exit(0);
+    });
+
+program.command('licensing-logs')
+    .description('Print the path to the Unity Licensing Client log files.')
+    .action(async () => {
+        const client = new LicensingClient();
+        process.stdout.write(`${client.logPath()}\n`);
         process.exit(0);
     });
 
@@ -359,14 +395,57 @@ program.command('run')
     .option('--unity-editor <unityEditor>', 'The path to the Unity Editor executable. If unspecified, --unity-project or the UNITY_EDITOR_PATH environment variable must be set.')
     .option('--unity-project <unityProject>', 'The path to a Unity project. If unspecified, the UNITY_PROJECT_PATH environment variable will be used, otherwise no project will be specified.')
     .option('--log-name <logName>', 'The name of the log file.')
-    .option('--verbose', 'Enable verbose logging.')
+    .option('--log-level <logLevel>', 'Set the logging level (debug, info, minimal, warning, error).')
+    .option('--verbose', 'Enable verbose logging. Deprecated, use --log-level instead.')
     .allowUnknownOption(true)
     .argument('<args...>', 'Arguments to pass to the Unity Editor executable.')
     .action(async (args: string[], options) => {
         if (options.verbose) {
+            Logger.instance.warn('The --verbose option is deprecated. Please use "--log-level <value>" instead.');
             Logger.instance.logLevel = LogLevel.DEBUG;
         }
 
+        let requestedLogLevel: LogLevel | undefined;
+
+        if (options.logLevel) {
+            const levelStr: string = options.logLevel?.toString()?.trim().toLowerCase();
+
+            switch (levelStr) {
+                case 'debug':
+                    requestedLogLevel = LogLevel.DEBUG;
+                    break;
+                case 'ci':
+                    requestedLogLevel = LogLevel.CI;
+                    break;
+                case 'minimal':
+                    requestedLogLevel = LogLevel.UTP;
+                    break;
+                case 'info':
+                    requestedLogLevel = LogLevel.INFO;
+                    break;
+                case 'warning':
+                    requestedLogLevel = LogLevel.WARN;
+                    break;
+                case 'error':
+                    requestedLogLevel = LogLevel.ERROR;
+                    break;
+                default:
+                    Logger.instance.warn(`Unknown log level: ${levelStr}. Using default log level.`);
+                    break;
+            }
+        }
+
+        if (requestedLogLevel === LogLevel.UTP) {
+            if (process.env.GITHUB_ACTIONS === 'true') {
+                Logger.instance.warn('The "minimal" log level is not supported in CI environments. Falling back to CI log output.');
+                Logger.instance.logLevel = LogLevel.CI;
+            } else {
+                Logger.instance.logLevel = LogLevel.UTP;
+            }
+        } else if (requestedLogLevel) {
+            Logger.instance.logLevel = requestedLogLevel;
+        }
+
         Logger.instance.debug(JSON.stringify({ options, args }));
 
         let unityEditor: UnityEditor | undefined;