@signageos/cli 2.4.1 → 2.5.0

package/docs/applet/index.md

@@ -0,0 +1,134 @@
+---
+id: applet-index
+title: applet
+sidebar_position: 20
+---
+# applet
+
+Applet development and management operations
+
+
+## Description
+
+Provides comprehensive commands for the complete applet development lifecycle including
+project generation, development, building, testing, uploading, and deployment to signageOS devices.
+
+## Usage
+
+```bash
+sos applet <subcommand> [options]
+```
+
+## Subcommands
+
+### generate
+
+Generate new signageOS applet projects with boilerplate code
+
+```bash
+sos applet generate [options]
+```
+
+[→ See detailed documentation](generate/)
+
+### upload
+
+Uploads current applet version
+
+```bash
+sos applet upload [options]
+```
+
+[→ See detailed documentation](upload/)
+
+### start
+
+Start local applet development server with live preview
+
+```bash
+sos applet start [options]
+```
+
+[→ See detailed documentation](start/)
+
+### test
+
+Applet test management
+
+```bash
+sos applet test <subcommand> [options]
+```
+
+[→ See detailed documentation](test/)
+
+### build
+
+Build applet locally for production deployment.
+
+```bash
+sos applet build [options]
+```
+
+[→ See detailed documentation](build/)
+
+
+## Examples
+
+```bash
+# Create new applet project
+sos applet generate --name my-applet
+
+# Start development server
+sos applet start
+
+# Build for production
+sos applet build
+
+# Upload to platform
+sos applet upload
+```
+
+## Since
+
+0.1.0
+
+## Global Options
+
+All commands support the following global options:
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--help` | `-h` | Display help information for any command |
+| `--version` | `-v` | Display the installed version of the CLI |
+| `--api-url` | `-u` | Override the API URL for REST requests |
+| `--profile` | | Use a specific profile from ~/.sosrc config |
+
+### Examples
+
+```bash
+# Show version
+sos --version
+
+# Get help for any command
+sos applet --help
+sos applet upload --help
+
+# Use custom API endpoint
+sos --api-url https://api.example.com applet upload
+
+# Use specific profile
+sos --profile production organization list
+```
+
+
+## Related Commands
+
+- [`sos applet generate`](generate/) - Generate new signageOS applet projects with boilerplate code
+- [`sos applet upload`](upload/) - Uploads current applet version
+- [`sos applet start`](start/) - Start local applet development server with live preview
+- [`sos applet test`](test/) - Applet test management
+- [`sos applet build`](build/) - Build applet locally for production deployment.
+
+## See Also
+
+- [Applet Documentation](https://developers.signageos.io/docs/applets/)

package/docs/applet/start/index.md

@@ -0,0 +1,104 @@
+---
+id: applet-start-index
+title: start
+sidebar_position: 23
+---
+# start
+
+Start local applet development server with live preview
+
+
+## Description
+
+Starts a local development server with hot reload functionality, allowing developers
+to preview their applets in a browser-based emulator. Supports both local development
+and device connection for testing on actual signageOS devices.
+
+:::tip Remarks
+The development server provides a browser-based emulator accessible at http://localhost:8090
+by default. Hot reload automatically refreshes the emulator when source code changes.
+:::
+
+## Usage
+
+```bash
+sos applet start [options]
+```
+
+## Options
+
+| Option                      | Description                                                                                                                                               | Default |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| `--no-default-organization` | Prevent using the defaultOrganizationUid from ~/.sosrc (boolean)                                                                                          |         |
+| `--organization-uid`        | Organization UID (string)                                                                                                                                 |         |
+| `--port`                    | Port where will the applet run (number)                                                                                                                   | `8090`  |
+| `--applet-path`             | Path to the applet file or the project folder depending on the entry file. Relative to the command or absolute. (string)                                  |         |
+| `--entry-file-path`         | Path to the applet entry file. Relative to the command or absolute. (string)                                                                              |         |
+| `--hot-reload`              | Enable hot reload and build of applet (boolean)                                                                                                           | `false` |
+| `--server-port`             | The custom server port for local machine server. Default is detected from currently running applet server. (number)                                       |         |
+| `--server-public-url`       | Public url of local machine server. Is useful when the local machine is behind a reverse proxy. (string)                                                  |         |
+| `--force`                   | Force start applet server even if it is already running on a different port. Kill the running server first. (boolean)                                     |         |
+| `--detach`                  | Detach the applet HTTP server process from the terminal. Useful when want to run more commands reusing the same http server for current applet. (boolean) | `false` |
+| `--forward-server-url`      | Url of forward server to connect to the device instead of the local network (LAN). (string)                                                               |         |
+
+## Examples
+
+```bash
+# Start development server with default settings
+sos applet start
+
+# Start with custom port and hot reload
+sos applet start --port 8080 --hot-reload
+
+# Start with specific organization
+sos applet start --organization-uid abc123
+
+# Start with custom applet path
+sos applet start --applet-path ./my-applet
+
+# Start with specific entry file
+sos applet start --entry-file-path index.html
+
+# Force restart if server is already running
+sos applet start --force
+
+# Run in detached mode
+sos applet start --detach
+```
+
+## Since
+
+0.1.0
+
+## Global Options
+
+All commands support the following global options:
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--help` | `-h` | Display help information for any command |
+| `--version` | `-v` | Display the installed version of the CLI |
+| `--api-url` | `-u` | Override the API URL for REST requests |
+| `--profile` | | Use a specific profile from ~/.sosrc config |
+
+### Examples
+
+```bash
+# Show version
+sos --version
+
+# Get help for any command
+sos applet --help
+sos applet upload --help
+
+# Use custom API endpoint
+sos --api-url https://api.example.com applet upload
+
+# Use specific profile
+sos --profile production organization list
+```
+
+
+## See Also
+
+- [Applet Development Documentation](https://developers.signageos.io/docs/applets/connect-to-device-cli/)

package/docs/applet/test/index.md

@@ -0,0 +1,91 @@
+---
+id: applet-test-index
+title: test
+sidebar_position: 24
+---
+# test
+
+Applet test management
+
+
+## Description
+
+Provides commands for testing applets on the signageOS platform, including
+uploading test configurations and running remote tests on actual devices.
+
+## Usage
+
+```bash
+sos applet test <subcommand> [options]
+```
+
+## Subcommands
+
+### upload
+
+Upload applet tests to the signageOS platform
+
+```bash
+sos applet test upload [options]
+```
+
+[→ See detailed documentation](upload/)
+
+### run
+
+Run applet tests on signageOS devices
+
+```bash
+sos applet test run [options]
+```
+
+[→ See detailed documentation](run/)
+
+
+## Examples
+
+```bash
+# Upload test configuration
+sos applet test upload
+
+# Run tests remotely
+sos applet test run
+```
+
+## Since
+
+0.10.0
+
+## Global Options
+
+All commands support the following global options:
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--help` | `-h` | Display help information for any command |
+| `--version` | `-v` | Display the installed version of the CLI |
+| `--api-url` | `-u` | Override the API URL for REST requests |
+| `--profile` | | Use a specific profile from ~/.sosrc config |
+
+### Examples
+
+```bash
+# Show version
+sos --version
+
+# Get help for any command
+sos applet --help
+sos applet upload --help
+
+# Use custom API endpoint
+sos --api-url https://api.example.com applet upload
+
+# Use specific profile
+sos --profile production organization list
+```
+
+
+## Related Commands
+
+- [`sos applet test upload`](upload/) - Upload applet tests to the signageOS platform
+- [`sos applet test run`](run/) - Run applet tests on signageOS devices

package/docs/applet/test/run/index.md

@@ -0,0 +1,82 @@
+---
+id: applet-test-run-index
+title: run
+sidebar_position: 26
+---
+# run
+
+Run applet tests on signageOS devices
+
+
+## Description
+
+Executes previously uploaded applet tests on remote signageOS devices. This command
+triggers test execution and provides real-time feedback on test progress and results.
+Tests can be run on specific devices or across multiple devices for comprehensive testing.
+
+## Usage
+
+```bash
+sos applet test run [options]
+```
+
+## Options
+
+| Option                      | Description                                                                               |
+| --------------------------- | ----------------------------------------------------------------------------------------- |
+| `--no-default-organization` | Prevent using the defaultOrganizationUid from ~/.sosrc (boolean)                          |
+| `--device-uid`              | Device UID (string)                                                                       |
+| `--organization-uid`        | Organization UID (string)                                                                 |
+| `--applet-uid`              | Applet UID (string)                                                                       |
+| `--test`                    | Specify the test identifiers/files to be run. If not specified, all will be run. (string) |
+| `--yes`                     | Allow to run applet test without confirmation step (boolean)                              |
+
+## Examples
+
+```bash
+# Run all applet tests
+sos applet test run --applet-uid my-applet --device-uid device123
+
+# Run specific tests
+sos applet test run --applet-uid my-applet --device-uid device123 --test "test1,test2"
+
+# Run without confirmation
+sos applet test run --applet-uid my-applet --device-uid device123 --yes
+```
+
+## Since
+
+0.10.0
+
+## Global Options
+
+All commands support the following global options:
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--help` | `-h` | Display help information for any command |
+| `--version` | `-v` | Display the installed version of the CLI |
+| `--api-url` | `-u` | Override the API URL for REST requests |
+| `--profile` | | Use a specific profile from ~/.sosrc config |
+
+### Examples
+
+```bash
+# Show version
+sos --version
+
+# Get help for any command
+sos applet --help
+sos applet upload --help
+
+# Use custom API endpoint
+sos --api-url https://api.example.com applet upload
+
+# Use specific profile
+sos --profile production organization list
+```
+
+
+## See Also
+
+- [Upload test configuration command](../upload/)

package/docs/applet/test/upload/index.md

@@ -0,0 +1,80 @@
+---
+id: applet-test-upload-index
+title: upload
+sidebar_position: 25
+---
+# upload
+
+Upload applet tests to the signageOS platform
+
+
+## Description
+
+Uploads test files for remote execution on signageOS devices. Test files are
+identified based on the test configuration in package.json and uploaded to
+the platform for automated testing. Supports incremental uploads with
+change detection and confirmation prompts.
+
+## Usage
+
+```bash
+sos applet test upload [options]
+```
+
+## Options
+
+| Option                      | Description                                                                                   |
+| --------------------------- | --------------------------------------------------------------------------------------------- |
+| `--no-default-organization` | Prevent using the defaultOrganizationUid from ~/.sosrc (boolean)                              |
+| `--organization-uid`        | Organization UID (string)                                                                     |
+| `--applet-uid`              | Applet UID (string)                                                                           |
+| `--yes`                     | Allow to upload new applet test or override existing test without confirmation step (boolean) |
+| `--verbose`                 | Outputs all files to upload (boolean)                                                         |
+
+## Examples
+
+```bash
+# Upload applet tests
+sos applet test upload
+
+# Upload tests with confirmation skip
+sos applet test upload --yes
+
+# Upload tests with verbose output
+sos applet test upload --verbose
+
+# Upload tests for specific applet
+sos applet test upload --applet-uid my-applet-uid
+```
+
+## Since
+
+0.10.0
+
+## Global Options
+
+All commands support the following global options:
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--help` | `-h` | Display help information for any command |
+| `--version` | `-v` | Display the installed version of the CLI |
+| `--api-url` | `-u` | Override the API URL for REST requests |
+| `--profile` | | Use a specific profile from ~/.sosrc config |
+
+### Examples
+
+```bash
+# Show version
+sos --version
+
+# Get help for any command
+sos applet --help
+sos applet upload --help
+
+# Use custom API endpoint
+sos --api-url https://api.example.com applet upload
+
+# Use specific profile
+sos --profile production organization list
+```

package/docs/applet/upload/index.md

@@ -0,0 +1,131 @@
+---
+id: applet-upload-index
+title: upload
+sidebar_position: 25
+---
+# upload
+
+Uploads current applet version
+
+
+## Description
+
+Uploads the current applet version to the signageOS platform, making it available
+for deployment to devices. The command supports both single-file and multi-file applets,
+with automatic version management and conflict detection.
+
+The upload process validates package.json requirements, creates or updates applet versions,
+and handles file packaging according to .sosignore, .npmignore, and .gitignore rules.
+
+## Usage
+
+```bash
+sos applet upload [options]
+```
+
+## Options
+
+| Option                      | Description                                                                                                                                                       |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--applet-path`             | Path to the applet file or the project folder depending on the entry file. Relative to the command or absolute. (string)                                          |
+| `--entry-file-path`         | Path to the applet entry file. Relative to the command or absolute. (string)                                                                                      |
+| `--no-default-organization` | Prevent using the defaultOrganizationUid from ~/.sosrc (boolean)                                                                                                  |
+| `--organization-uid`        | Organization UID (string)                                                                                                                                         |
+| `--applet-uid`              | Applet UID (string)                                                                                                                                               |
+| `--update-package-config`   | Force updating package.json with sos.appletUid value of created applet. It's useful when appletUid is passed using SOS_APPLET_UID environment variable. (boolean) |
+| `--yes`                     | Allow to upload new applet or override existing version without confirmation step (boolean)                                                                       |
+| `--verbose`                 | Outputs all files to upload (boolean)                                                                                                                             |
+
+## Examples
+
+```bash
+# Upload applet from current directory
+sos applet upload
+
+# Upload with specific applet path
+sos applet upload --applet-path ./dist
+
+# Upload with custom entry file
+sos applet upload --entry-file-path src/main.js
+
+# Upload with organization override
+sos applet upload --organization-uid abc123def456
+
+# Skip confirmation prompts
+sos applet upload --yes
+
+# Verbose output with detailed file information
+sos applet upload --verbose
+
+# Update package.json with new applet UID
+sos applet upload --update-package-config
+```
+
+## Advanced Usage
+
+### Environment Variables
+
+You can override certain values using environment variables:
+
+- **`SOS_APPLET_UID`**: Specify applet UID to upload to (overrides `sos.appletUid` in package.json)
+- **`SOS_APPLET_VERSION`**: Specify applet version to upload (overrides `version` in package.json)
+
+```bash
+# Upload to specific applet using environment variable
+SOS_APPLET_UID=abc123def456 sos applet upload
+
+# Upload with specific version
+SOS_APPLET_VERSION=1.2.3 sos applet upload
+```
+
+### File Handling
+
+- **Applet Creation**: If applet doesn't exist, it will be created automatically
+- **Version Management**: Applet version is read from `package.json`
+- **Applet UID Storage**: Generated applet UID is stored in `package.json` under `sos.appletUid`
+- **Ignore Files**: File exclusion priority (top to bottom): `.sosignore` > `.npmignore` > `.gitignore`
+- **Single Ignore File**: Only one ignore file is used, or none
+
+### Alternative Upload Methods
+
+```bash
+# Upload using npm script (recommended)
+npm run upload
+
+# Upload all files in applet directory (deprecated method)
+sos applet upload --applet-path=dist/index.html
+# Note: This will upload only the specified file and remove others from servers
+```
+
+
+## Since
+
+0.4.0
+
+## Global Options
+
+All commands support the following global options:
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--help` | `-h` | Display help information for any command |
+| `--version` | `-v` | Display the installed version of the CLI |
+| `--api-url` | `-u` | Override the API URL for REST requests |
+| `--profile` | | Use a specific profile from ~/.sosrc config |
+
+### Examples
+
+```bash
+# Show version
+sos --version
+
+# Get help for any command
+sos applet --help
+sos applet upload --help
+
+# Use custom API endpoint
+sos --api-url https://api.example.com applet upload
+
+# Use specific profile
+sos --profile production organization list
+```