@signageos/cli 4.0.1 → 4.0.3

package/dist/Applet/Build/appletBuildCommand.js

@@ -22,6 +22,7 @@ const appletFacade_1 = require("../appletFacade");
 const log_1 = require("@signageos/sdk/dist/Console/log");
 const debug_1 = __importDefault(require("debug"));
 const appletValidation_1 = require("../appletValidation");
+const runControlHelper_1 = require("../../RunControl/runControlHelper");
 const Debug = (0, debug_1.default)('@signageos/cli:Applet:Build:appletBuildCommand');
 exports.OPTION_LIST = [organizationFacade_1.NO_DEFAULT_ORGANIZATION_OPTION, organizationFacade_1.ORGANIZATION_UID_OPTION, appletFacade_1.APPLET_UID_OPTION];
 /**
@@ -61,8 +62,11 @@ exports.appletBuild = (0, commandDefinition_1.createCommandDefinition)({
             const organizationUid = yield (0, organizationFacade_1.getOrganizationUidOrDefaultOrSelect)(options);
             const organization = yield (0, organizationFacade_1.getOrganization)(organizationUid);
             const restApi = yield (0, helper_1.createOrganizationRestApi)(organization);
+            const config = yield (0, runControlHelper_1.loadConfig)();
             const dev = (0, dist_1.createDevelopment)({
                 organizationUid: organization.uid,
+                url: (0, helper_1.getApiUrl)(config),
+                accessToken: config.accessToken,
             });
             const appletUid = yield (0, appletFacade_1.getAppletUid)(restApi, options);
             const appletVersion = yield (0, appletFacade_1.getAppletVersion)(currentDirectory);

package/dist/Applet/Start/appletStartCommand.js

@@ -21,6 +21,8 @@ const commandDefinition_1 = require("../../Command/commandDefinition");
 const organizationFacade_1 = require("../../Organization/organizationFacade");
 const dist_1 = require("@signageos/sdk/dist");
 const wait_1 = __importDefault(require("../../Timer/wait"));
+const runControlHelper_1 = require("../../RunControl/runControlHelper");
+const helper_1 = require("../../helper");
 const appletServerHelper_1 = require("../appletServerHelper");
 const log_1 = require("@signageos/sdk/dist/Console/log");
 const parameters_1 = require("../../parameters");
@@ -102,8 +104,11 @@ exports.appletStart = (0, commandDefinition_1.createCommandDefinition)({
             const entryFileAbsolutePath = yield (0, appletUploadCommandHelper_1.getAppletEntryFileAbsolutePath)(currentDirectory, options);
             const entryFileRelativePath = (0, appletUploadCommandHelper_1.getAppletEntryFileRelativePath)(entryFileAbsolutePath, appletPath);
             const emulatorUid = yield (0, emulatorFacade_1.loadEmulatorOrCreateNewAndReturnUid)(organizationUid);
+            const config = yield (0, runControlHelper_1.loadConfig)();
             const dev = (0, dist_1.createDevelopment)({
                 organizationUid,
+                url: (0, helper_1.getApiUrl)(config),
+                accessToken: config.accessToken,
             });
             const emulatorServerPort = (_a = options[PORT_OPTION.name]) !== null && _a !== void 0 ? _a : DEFAULT_PORT;
             const hotReloadEnabled = options[appletServerHelper_1.HOT_RELOAD_OPTION.name];

package/dist/Device/Connect/connectCommand.js

@@ -20,6 +20,7 @@ const helper_1 = require("../../helper");
 const commandDefinition_1 = require("../../Command/commandDefinition");
 const sdk_1 = require("@signageos/sdk");
 const wait_1 = __importDefault(require("../../Timer/wait"));
+const runControlHelper_1 = require("../../RunControl/runControlHelper");
 const appletServerHelper_1 = require("../../Applet/appletServerHelper");
 const debug_1 = __importDefault(require("debug"));
 const appletUploadCommandHelper_1 = require("../../Applet/Upload/appletUploadCommandHelper");
@@ -106,8 +107,11 @@ exports.connect = (0, commandDefinition_1.createCommandDefinition)({
             const organizationUid = yield (0, organizationFacade_1.getOrganizationUidOrDefaultOrSelect)(options);
             const organization = yield (0, organizationFacade_1.getOrganization)(organizationUid);
             const restApi = yield (0, helper_1.createOrganizationRestApi)(organization);
+            const config = yield (0, runControlHelper_1.loadConfig)();
             const dev = (0, sdk_1.createDevelopment)({
                 organizationUid: organization.uid,
+                url: (0, helper_1.getApiUrl)(config),
+                accessToken: config.accessToken,
             });
             const appletUid = yield (0, appletFacade_1.getAppletUid)(restApi, options);
             const appletVersion = yield (0, appletFacade_1.getAppletVersion)(currentDirectory);

package/docs/ci-cd-setup/index.md

@@ -0,0 +1,240 @@
+---
+id: ci-cd-setup
+title: CI/CD Pipeline Setup
+sidebar_position: 1
+---
+# CI/CD Pipeline Setup
+
+How to configure the signageOS CLI for automated pipelines (GitLab CI, GitHub Actions, and other CI/CD tools) where interactive login is not possible.
+
+## Overview
+
+On a **local development machine**, you authenticate by running `sos login`, which interactively prompts for your username and password, generates a personal API security token, and stores it in `~/.sosrc`.
+
+In a **CI/CD pipeline**, there is no interactive terminal. Instead, you generate a long-lived API security token ahead of time and provide it to the pipeline via the `~/.sosrc` configuration file or environment variables.
+
+## Step 1: Generate an API Security Token
+
+Before configuring your pipeline, generate a personal API security token:
+
+1. Log in to [signageOS Box](https://box.signageos.io)
+2. Navigate to **Settings** → **Profile** → **API Tokens**
+3. Create a new token (account-wide or organization-scoped, depending on your needs)
+4. Copy the **Token ID** (identification) and **Token secret** values — you will need both
+
+
+## Step 2: Configure Authentication
+
+You have two options — choose whichever fits your pipeline best.
+
+### Option A: Configuration File (`~/.sosrc`)
+
+Create the `~/.sosrc` file in the CI runner's home directory with your credentials in INI format:
+
+```ini
+apiUrl=https://api.signageos.io
+identification=527f75f50ce2f3cxxxxx
+apiSecurityToken=7dc58dc275c87283cddf78bc41755cb5f7fxxxxx
+```
+
+The file supports the following fields:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `apiUrl` | Yes | signageOS API endpoint (typically `https://api.signageos.io`) |
+| `identification` | Yes | Token ID from your security token |
+| `apiSecurityToken` | Yes | The security token secret |
+| `defaultOrganizationUid` | No | Default organization UID for commands that require one |
+
+> **Security:** The CLI writes this file with permissions `0600` (owner read/write only). Make sure your pipeline step preserves these permissions.
+
+### Option B: Environment Variables
+
+Instead of writing a file, you can set environment variables that override `~/.sosrc` values:
+
+| Environment Variable | Overrides |
+|---------------------|-----------|
+| `SOS_API_URL` | `apiUrl` |
+| `SOS_API_IDENTIFICATION` | `identification` |
+| `SOS_API_SECURITY_TOKEN` | `apiSecurityToken` |
+| `SOS_ORGANIZATION_UID` | `defaultOrganizationUid` |
+
+Environment variables take precedence over the configuration file, so you can combine both approaches (e.g., a base `.sosrc` with env var overrides for specific jobs).
+
+## Pipeline Examples
+
+### GitLab CI
+
+Store your credentials as [CI/CD variables](https://docs.gitlab.com/ee/ci/variables/) in your project or group settings (masked and protected).
+
+```yaml
+# .gitlab-ci.yml
+
+variables:
+  SOS_API_URL: "https://api.signageos.io"
+
+stages:
+  - deploy
+
+deploy-applet:
+  stage: deploy
+  image: node:20
+  before_script:
+    - npm install -g @signageos/cli
+    # Write ~/.sosrc from CI/CD variables
+    - |
+      cat > ~/.sosrc <<EOF
+      apiUrl=${SOS_API_URL}
+      identification=${SOS_API_IDENTIFICATION}
+      apiSecurityToken=${SOS_API_SECURITY_TOKEN}
+      EOF
+    - chmod 600 ~/.sosrc
+  script:
+    - sos applet upload
+```
+
+Alternatively, using only environment variables (no file needed):
+
+```yaml
+deploy-applet:
+  stage: deploy
+  image: node:20
+  variables:
+    SOS_API_URL: "https://api.signageos.io"
+    # SOS_API_IDENTIFICATION and SOS_API_SECURITY_TOKEN come from CI/CD settings
+  before_script:
+    - npm install -g @signageos/cli
+  script:
+    - sos applet upload
+```
+
+### GitHub Actions
+
+Store your credentials as [repository secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets).
+
+```yaml
+# .github/workflows/deploy.yml
+
+name: Deploy Applet
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install signageOS CLI
+        run: npm install -g @signageos/cli
+
+      - name: Configure signageOS credentials
+        run: |
+          cat > ~/.sosrc <<EOF
+          apiUrl=https://api.signageos.io
+          identification=${{ secrets.SOS_API_IDENTIFICATION }}
+          apiSecurityToken=${{ secrets.SOS_API_SECURITY_TOKEN }}
+          EOF
+          chmod 600 ~/.sosrc
+
+      - name: Deploy applet
+        run: sos applet upload
+```
+
+Or using environment variables:
+
+```yaml
+      - name: Deploy applet
+        env:
+          SOS_API_URL: "https://api.signageos.io"
+          SOS_API_IDENTIFICATION: ${{ secrets.SOS_API_IDENTIFICATION }}
+          SOS_API_SECURITY_TOKEN: ${{ secrets.SOS_API_SECURITY_TOKEN }}
+        run: sos applet upload
+```
+
+## Using Profiles in CI/CD
+
+If your pipeline needs to operate against multiple signageOS environments (e.g., staging and production), use profiles (see [`sos login`](/cli/login/) documentation):
+
+```ini
+[profile staging]
+apiUrl=https://api.staging.signageos.io
+identification=xxxxxxxxxxxxxxxxxxxx
+apiSecurityToken=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+[profile production]
+apiUrl=https://api.signageos.io
+identification=yyyyyyyyyyyyyyyyyyyy
+apiSecurityToken=yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
+```
+
+Then target a specific profile per job:
+
+```bash
+# Deploy to staging
+sos --profile staging applet upload
+
+# Deploy to production
+sos --profile production applet upload
+```
+
+You can also select a profile via the `SOS_PROFILE` environment variable:
+
+```bash
+export SOS_PROFILE=production
+sos applet upload
+```
+
+## Setting a Default Organization
+
+Some CLI commands operate on a specific organization. To avoid interactive prompts in CI/CD, set the default organization:
+
+**In `~/.sosrc`:**
+```ini
+apiUrl=https://api.signageos.io
+identification=527f75f50ce2f3cxxxxx
+apiSecurityToken=7dc58dc275c87283cddf78bc41755cb5f7fxxxxx
+defaultOrganizationUid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+```
+
+**Or via environment variable:**
+```bash
+export SOS_ORGANIZATION_UID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+```
+
+## Troubleshooting
+
+### "Identification or token is missing"
+
+The CLI cannot find valid credentials. Verify that:
+- The `~/.sosrc` file exists and contains both `identification` and `apiSecurityToken`
+- Or the `SOS_API_IDENTIFICATION` and `SOS_API_SECURITY_TOKEN` environment variables are set
+- The token has not expired or been revoked
+
+### "No API URL is defined"
+
+The CLI needs an API URL. Ensure either:
+- `apiUrl` is set in `~/.sosrc`
+- Or `SOS_API_URL` environment variable is defined
+
+### "Your authentication token is outdated"
+
+The `identification` value does not match the expected format (20-character hex string). Regenerate the token via [signageOS Box](https://box.signageos.io/settings) or re-run `sos login` on your local machine and copy the new values.
+
+## Security Best Practices
+
+- **Never commit credentials** to your repository. Use CI/CD secret variables or a secrets manager.
+- **Use masked variables** in GitLab CI / GitHub Actions so tokens don't appear in job logs.
+- **Scope tokens appropriately** — prefer organization-scoped tokens when your pipeline only needs access to a single organization.
+- **Rotate tokens periodically** and revoke unused ones via signageOS Box settings.
+
+## See Also
+
+- [`sos login`](/cli/login/) — Interactive authentication for local development
+- [Global Options](/cli/) — `--profile` and `--api-url` flags

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signageos/cli",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "main": "./dist/index.js",
   "author": "signageOS.io <dev@signageos.io>",
   "files": [
@@ -87,7 +87,7 @@
   "dependencies": {
     "@signageos/cli-common": "0.1.0",
     "@signageos/file": "2.0.1",
-    "@signageos/sdk": "2.6.1",
+    "@signageos/sdk": "2.7.0",
     "archiver": "7.0.1",
     "chalk": "2.4.2",
     "child-process-promise": "2.1.3",