@norbix.ai/cli 0.2.0 → 0.3.0

package/README.md

@@ -40,6 +40,7 @@ norbix scheduler list
 | `norbix config list/get/set/unset` | Manage the local config file |
 | `norbix db find/get/count/insert/update/delete/aggregate` | Work with database collections |
 | `norbix files list/info/upload/download/sign/delete/publish/unpublish` | Upload, download, manage and publish files |
+| `norbix files integrations test <id>` | Check that a files integration really works (live upload/read/list/delete probe) |
 | `norbix users list/get/invite/block/unblock/delete` | Manage project users (membership) |
 | `norbix env list/use/delete` | Manage project environments |
 | `norbix logs list/trail` | Read project logs, follow one correlation ID |
@@ -148,7 +149,7 @@ norbix files download invoices/2026/invoice.pdf
 
 Or pass `--integration <id>` (env var: `NORBIX_FILES_INTEGRATION_ID`).
 
-### The eight file commands
+### The file commands
 
 | Command | What it does |
 | --- | --- |
@@ -160,6 +161,7 @@ Or pass `--integration <id>` (env var: `NORBIX_FILES_INTEGRATION_ID`).
 | `norbix files delete <path> [--yes]` | Delete one file. Asks first unless you pass `--yes`. |
 | `norbix files publish <path> [--folder]` | Give the file — or the whole folder — a link anyone can open, and print it. |
 | `norbix files unpublish <path> [--folder]` | Take that link away again. |
+| `norbix files integrations test <id>` | Check that the storage behind an integration really works. See below. |
 
 Upload and download take more than one step, so the file bytes never pass
 through Norbix:
@@ -212,6 +214,27 @@ Four rules worth knowing:
 * Every dead link answers the same plain `404`: unknown, renamed, unpublished,
   deleted. A more precise answer would tell a stranger that the file is there.
 
+### Testing an integration
+
+`norbix files integrations test <id>` runs a live probe against the storage
+behind the integration: it uploads a small file, reads it, lists its folder and
+deletes it again. One line per step:
+
+```sh
+norbix files integrations test 55555555-5555-5555-5555-555555555555
+# UploadFile   OK
+# GetFile      FAILED
+#                - NoSuchKey: the object was not found
+# GetAllFiles  NOT_TESTED
+# DeleteFile   NOT_TESTED
+#  ›   Error: The files integration test failed: GetFile FAILED (2 later steps not tested).
+```
+
+`NOT_TESTED` means the step was skipped because an earlier one failed. The
+command exits `0` only when every step is `OK`, so it works in a script or a
+CI job. `--json` prints the steps as data and keeps the same exit code. The
+probe writes to the storage, so the key needs the `files:create` permission.
+
 ## Tests
 
 ```sh

package/dist/commands/files/integrations/test.js

@@ -0,0 +1,85 @@
+import { Args } from '@oclif/core';
+import { BaseCommand } from '../../../base.js';
+import { callTestFilesIntegration, normaliseResult, } from '../../../lib/filesIntegrationTest.js';
+export default class FilesIntegrationsTest extends BaseCommand {
+    static description = `Check that a files integration really works
+
+Runs a live probe against the storage: uploads a small file, reads it, lists
+its folder and deletes it again. Prints one line per step — OK, FAILED or
+NOT_TESTED (skipped because an earlier step failed) — with the errors of a
+failed step. Exits non-zero unless every step is OK.
+
+Needs the files:create permission, because the probe writes to the storage.`;
+    static examples = [
+        '<%= config.bin %> files integrations test 55555555-5555-5555-5555-555555555555',
+        '<%= config.bin %> files integrations test 55555555-5555-5555-5555-555555555555 --json',
+    ];
+    static args = {
+        id: Args.string({ required: true, description: 'Files integration ID' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(FilesIntegrationsTest);
+        const ctx = this.resolveContext(flags);
+        // Builds nothing itself, but it is what refuses early and with a useful
+        // sentence when there is no project, region or credentials.
+        this.client(flags);
+        // TODO(10b-API-TEST): switch to `client.api.files.testFilesIntegration`
+        // once @norbix.ai/ts releases it (sdk-ts PR #44) — see the lib file.
+        const res = await callTestFilesIntegration(ctx, args.id);
+        const output = summarise(args.id, res);
+        if (this.jsonEnabled()) {
+            // oclif prints the returned value; the exit code still tells a script
+            // whether the integration works.
+            if (!output.ok)
+                process.exitCode = 2;
+            return output;
+        }
+        for (const line of render(output.steps))
+            this.log(line);
+        if (!output.ok) {
+            this.error(failureMessage(output));
+        }
+        this.log(`\nAll ${output.steps.length} steps passed.`);
+        return output;
+    }
+}
+function summarise(id, res) {
+    const steps = (res.items ?? []).map((item) => ({
+        operation: item.operation,
+        result: normaliseResult(item.result),
+        errors: item.errors ?? [],
+    }));
+    const errors = (res.responseStatus?.errors ?? [])
+        .map((e) => e.message ?? e.errorCode ?? '')
+        .filter(Boolean);
+    const gatewayOk = res.responseStatus?.isSuccess !== false;
+    if (!gatewayOk && errors.length === 0) {
+        errors.push('the gateway answered isSuccess: false without an error message');
+    }
+    const ok = gatewayOk && steps.length > 0 && steps.every((s) => s.result === 'OK');
+    return { filesIntegrationId: id, ok, steps, errors };
+}
+function render(steps) {
+    const width = Math.max(0, ...steps.map((s) => s.operation.length));
+    const lines = [];
+    for (const step of steps) {
+        lines.push(`${step.operation.padEnd(width)}  ${step.result}`);
+        for (const error of step.errors)
+            lines.push(`${' '.repeat(width)}    - ${error}`);
+    }
+    return lines;
+}
+function failureMessage(output) {
+    if (output.errors.length > 0) {
+        return `The files integration test was refused: ${output.errors.join('; ')}`;
+    }
+    if (output.steps.length === 0) {
+        return 'The gateway returned no test steps, so nothing was proven.';
+    }
+    const notOk = output.steps.filter((s) => s.result !== 'OK');
+    const failed = notOk.filter((s) => s.result !== 'NOT_TESTED');
+    const skipped = notOk.length - failed.length;
+    const named = (failed.length > 0 ? failed : notOk).map((s) => `${s.operation} ${s.result}`).join(', ');
+    const tail = failed.length > 0 && skipped > 0 ? ` (${skipped} later step${skipped === 1 ? '' : 's'} not tested)` : '';
+    return `The files integration test failed: ${named}${tail}.`;
+}

package/dist/lib/filesIntegrationTest.js

@@ -0,0 +1,57 @@
+import { NorbixAuthError, NorbixError, NorbixValidationError } from '@norbix.ai/ts';
+/** The API version the SDK talks by default. Kept in one place. */
+const API_VERSION = 'v2';
+export async function callTestFilesIntegration(ctx, filesIntegrationId) {
+    const token = ctx.bearerToken ?? ctx.apiKey;
+    const headers = new Headers({ Accept: 'application/json' });
+    if (token)
+        headers.set('Authorization', `Bearer ${token}`);
+    if (ctx.projectId) {
+        headers.set('norbix-project-id', ctx.projectId);
+        headers.set('X-CM-ProjectId', ctx.projectId);
+    }
+    if (ctx.accountId) {
+        headers.set('norbix-account-id', ctx.accountId);
+        headers.set('X-CM-AccountId', ctx.accountId);
+    }
+    if (ctx.env && ctx.env !== 'PROD')
+        headers.set('norbix-env', ctx.env);
+    if (ctx.region)
+        headers.set('nb-region', ctx.region);
+    const base = ctx.apiUrl.endsWith('/') ? ctx.apiUrl.slice(0, -1) : ctx.apiUrl;
+    const url = `${base}/${API_VERSION}/files/${encodeURIComponent(filesIntegrationId)}/test`;
+    const response = await fetch(url, { headers, method: 'POST' });
+    const text = await response.text();
+    let raw;
+    if (text) {
+        try {
+            raw = JSON.parse(text);
+        }
+        catch {
+            raw = text;
+        }
+    }
+    if (!response.ok)
+        throw errorFrom(response.status, raw, url);
+    return (raw && typeof raw === 'object' ? raw : {});
+}
+/** Same mapping as the SDK transport: 401/403 → auth, 400 → validation, else NorbixError. */
+function errorFrom(status, raw, url) {
+    const body = raw && typeof raw === 'object' ? raw : undefined;
+    const payload = body?.responseStatus ?? body;
+    const message = payload?.message ??
+        body?.responseStatus?.errors?.find((e) => e.message)?.message ??
+        `Request failed with status ${status}`;
+    const opts = { code: payload?.errorCode, message, raw, status, url };
+    if (status === 401 || status === 403)
+        return new NorbixAuthError(opts);
+    if (status === 400)
+        return new NorbixValidationError(opts);
+    return new NorbixError(opts);
+}
+/** `Failed` / `NotTested` / `NOT_TESTED` → `FAILED` / `NOT_TESTED`. */
+export function normaliseResult(result) {
+    if (!result)
+        return 'UNKNOWN';
+    return result.replaceAll(/([a-z])([A-Z])/g, '$1_$2').replaceAll(/[\s-]+/g, '_').toUpperCase();
+}

package/oclif.manifest.json

@@ -4607,18 +4607,18 @@
         "unarchive.js"
       ]
     },
-    "env:delete": {
+    "files:delete": {
       "aliases": [],
       "args": {
-        "name": {
-          "description": "Environment name (PROD cannot be deleted)",
-          "name": "name",
+        "remote": {
+          "description": "Remote file path",
+          "name": "remote",
           "required": true
         }
       },
-      "description": "Delete a non-PROD environment (cascades its integrations)",
+      "description": "Delete one file",
       "examples": [
-        "<%= config.bin %> env delete STAGING --yes"
+        "<%= config.bin %> files delete invoices/2026/invoice.pdf --yes"
       ],
       "flags": {
         "json": {
@@ -4682,6 +4682,15 @@
           "multiple": false,
           "type": "option"
         },
+        "integration": {
+          "char": "i",
+          "description": "Files integration ID",
+          "env": "NORBIX_FILES_INTEGRATION_ID",
+          "name": "integration",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "yes": {
           "char": "y",
           "description": "Skip the confirmation prompt",
@@ -4692,7 +4701,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "env:delete",
+      "id": "files:delete",
       "pluginAlias": "@norbix.ai/cli",
       "pluginName": "@norbix.ai/cli",
       "pluginType": "core",
@@ -4702,16 +4711,28 @@
       "relativePath": [
         "dist",
         "commands",
-        "env",
+        "files",
         "delete.js"
       ]
     },
-    "env:list": {
+    "files:download": {
       "aliases": [],
-      "args": {},
-      "description": "List the project's environments (PROD is always first)",
+      "args": {
+        "remote": {
+          "description": "Remote file path",
+          "name": "remote",
+          "required": true
+        },
+        "file": {
+          "description": "Local target file (default: remote file name in current folder)",
+          "name": "file",
+          "required": false
+        }
+      },
+      "description": "Download a file to disk (via a signed URL)",
       "examples": [
-        "<%= config.bin %> env list"
+        "<%= config.bin %> files download invoices/2026/invoice.pdf",
+        "<%= config.bin %> files download invoices/2026/invoice.pdf ./local-copy.pdf"
       ],
       "flags": {
         "json": {
@@ -4774,11 +4795,20 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "integration": {
+          "char": "i",
+          "description": "Files integration ID",
+          "env": "NORBIX_FILES_INTEGRATION_ID",
+          "name": "integration",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "env:list",
+      "id": "files:download",
       "pluginAlias": "@norbix.ai/cli",
       "pluginName": "@norbix.ai/cli",
       "pluginType": "core",
@@ -4788,24 +4818,22 @@
       "relativePath": [
         "dist",
         "commands",
-        "env",
-        "list.js"
+        "files",
+        "download.js"
       ]
     },
-    "env:use": {
+    "files:info": {
       "aliases": [],
       "args": {
-        "name": {
-          "description": "Environment name (e.g. PROD, TEST)",
-          "name": "name",
+        "remote": {
+          "description": "Remote file path",
+          "name": "remote",
           "required": true
         }
       },
-      "description": "Set the default environment for future commands.\n\nWritten to the active session when you are logged in; with --profile it is\nwritten into that profile in ~/.norbix/config; otherwise to the [default]\nprofile. Override per command with --env.",
+      "description": "Show metadata for one file",
       "examples": [
-        "<%= config.bin %> env use TEST",
-        "<%= config.bin %> env use PROD",
-        "<%= config.bin %> env use STAGING --profile fitskin-prod"
+        "<%= config.bin %> files info invoices/2026/invoice.pdf"
       ],
       "flags": {
         "json": {
@@ -4868,11 +4896,20 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "integration": {
+          "char": "i",
+          "description": "Files integration ID",
+          "env": "NORBIX_FILES_INTEGRATION_ID",
+          "name": "integration",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "env:use",
+      "id": "files:info",
       "pluginAlias": "@norbix.ai/cli",
       "pluginName": "@norbix.ai/cli",
       "pluginType": "core",
@@ -4882,22 +4919,23 @@
       "relativePath": [
         "dist",
         "commands",
-        "env",
-        "use.js"
+        "files",
+        "info.js"
       ]
     },
-    "files:delete": {
+    "files:list": {
       "aliases": [],
       "args": {
-        "remote": {
-          "description": "Remote file path",
-          "name": "remote",
-          "required": true
+        "path": {
+          "description": "Folder path (default: root)",
+          "name": "path",
+          "required": false
         }
       },
-      "description": "Delete one file",
+      "description": "List files in a folder of a files integration",
       "examples": [
-        "<%= config.bin %> files delete invoices/2026/invoice.pdf --yes"
+        "<%= config.bin %> files list --integration 66b2...",
+        "<%= config.bin %> files list invoices/2026"
       ],
       "flags": {
         "json": {
@@ -4969,18 +5007,11 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
-        },
-        "yes": {
-          "char": "y",
-          "description": "Skip the confirmation prompt",
-          "name": "yes",
-          "allowNo": false,
-          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "files:delete",
+      "id": "files:list",
       "pluginAlias": "@norbix.ai/cli",
       "pluginName": "@norbix.ai/cli",
       "pluginType": "core",
@@ -4991,27 +5022,22 @@
         "dist",
         "commands",
         "files",
-        "delete.js"
+        "list.js"
       ]
     },
-    "files:download": {
+    "files:publish": {
       "aliases": [],
       "args": {
         "remote": {
-          "description": "Remote file path",
+          "description": "Remote file path, or folder prefix with --folder",
           "name": "remote",
           "required": true
-        },
-        "file": {
-          "description": "Local target file (default: remote file name in current folder)",
-          "name": "file",
-          "required": false
         }
       },
-      "description": "Download a file to disk (via a signed URL)",
+      "description": "Make a file (or a whole folder) readable by anyone holding its link — no sign-in needed",
       "examples": [
-        "<%= config.bin %> files download invoices/2026/invoice.pdf",
-        "<%= config.bin %> files download invoices/2026/invoice.pdf ./local-copy.pdf"
+        "<%= config.bin %> files publish invoices/2026/invoice.pdf",
+        "<%= config.bin %> files publish invoices --folder"
       ],
       "flags": {
         "json": {
@@ -5075,6 +5101,12 @@
           "multiple": false,
           "type": "option"
         },
+        "folder": {
+          "description": "Publish the whole folder prefix instead of one file",
+          "name": "folder",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "integration": {
           "char": "i",
           "description": "Files integration ID",
@@ -5087,7 +5119,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "files:download",
+      "id": "files:publish",
       "pluginAlias": "@norbix.ai/cli",
       "pluginName": "@norbix.ai/cli",
       "pluginType": "core",
@@ -5098,10 +5130,10 @@
         "dist",
         "commands",
         "files",
-        "download.js"
+        "publish.js"
       ]
     },
-    "files:info": {
+    "files:sign": {
       "aliases": [],
       "args": {
         "remote": {
@@ -5110,9 +5142,9 @@
           "required": true
         }
       },
-      "description": "Show metadata for one file",
+      "description": "Get a temporary signed download URL for a file",
       "examples": [
-        "<%= config.bin %> files info invoices/2026/invoice.pdf"
+        "<%= config.bin %> files sign invoices/2026/invoice.pdf --expires 3600"
       ],
       "flags": {
         "json": {
@@ -5184,11 +5216,18 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "expires": {
+          "description": "URL lifetime in seconds",
+          "name": "expires",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "files:info",
+      "id": "files:sign",
       "pluginAlias": "@norbix.ai/cli",
       "pluginName": "@norbix.ai/cli",
       "pluginType": "core",
@@ -5199,22 +5238,22 @@
         "dist",
         "commands",
         "files",
-        "info.js"
+        "sign.js"
       ]
     },
-    "files:list": {
+    "files:unpublish": {
       "aliases": [],
       "args": {
-        "path": {
-          "description": "Folder path (default: root)",
-          "name": "path",
-          "required": false
+        "remote": {
+          "description": "Remote file path, or folder prefix with --folder",
+          "name": "remote",
+          "required": true
         }
       },
-      "description": "List files in a folder of a files integration",
+      "description": "Take away a file's (or a folder's) public link",
       "examples": [
-        "<%= config.bin %> files list --integration 66b2...",
-        "<%= config.bin %> files list invoices/2026"
+        "<%= config.bin %> files unpublish invoices/2026/invoice.pdf",
+        "<%= config.bin %> files unpublish invoices --folder"
       ],
       "flags": {
         "json": {
@@ -5278,6 +5317,12 @@
           "multiple": false,
           "type": "option"
         },
+        "folder": {
+          "description": "Unpublish the whole folder prefix, and every link inside it",
+          "name": "folder",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "integration": {
           "char": "i",
           "description": "Files integration ID",
@@ -5290,7 +5335,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "files:list",
+      "id": "files:unpublish",
       "pluginAlias": "@norbix.ai/cli",
       "pluginName": "@norbix.ai/cli",
       "pluginType": "core",
@@ -5301,22 +5346,27 @@
         "dist",
         "commands",
         "files",
-        "list.js"
+        "unpublish.js"
       ]
     },
-    "files:publish": {
+    "files:upload": {
       "aliases": [],
       "args": {
+        "file": {
+          "description": "Local file to upload",
+          "name": "file",
+          "required": true
+        },
         "remote": {
-          "description": "Remote file path, or folder prefix with --folder",
+          "description": "Remote path (default: file name in the root folder)",
           "name": "remote",
-          "required": true
+          "required": false
         }
       },
-      "description": "Make a file (or a whole folder) readable by anyone holding its link — no sign-in needed",
+      "description": "Upload a local file (three steps: get signed URL, PUT bytes, commit).",
       "examples": [
-        "<%= config.bin %> files publish invoices/2026/invoice.pdf",
-        "<%= config.bin %> files publish invoices --folder"
+        "<%= config.bin %> files upload ./invoice.pdf",
+        "<%= config.bin %> files upload ./invoice.pdf invoices/2026/invoice.pdf"
       ],
       "flags": {
         "json": {
@@ -5380,12 +5430,6 @@
           "multiple": false,
           "type": "option"
         },
-        "folder": {
-          "description": "Publish the whole folder prefix instead of one file",
-          "name": "folder",
-          "allowNo": false,
-          "type": "boolean"
-        },
         "integration": {
           "char": "i",
           "description": "Files integration ID",
@@ -5394,11 +5438,18 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "content-type": {
+          "description": "MIME type (default: guessed from extension)",
+          "name": "content-type",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "files:publish",
+      "id": "files:upload",
       "pluginAlias": "@norbix.ai/cli",
       "pluginName": "@norbix.ai/cli",
       "pluginType": "core",
@@ -5409,21 +5460,21 @@
         "dist",
         "commands",
         "files",
-        "publish.js"
+        "upload.js"
       ]
     },
-    "files:sign": {
+    "env:delete": {
       "aliases": [],
       "args": {
-        "remote": {
-          "description": "Remote file path",
-          "name": "remote",
+        "name": {
+          "description": "Environment name (PROD cannot be deleted)",
+          "name": "name",
           "required": true
         }
       },
-      "description": "Get a temporary signed download URL for a file",
+      "description": "Delete a non-PROD environment (cascades its integrations)",
       "examples": [
-        "<%= config.bin %> files sign invoices/2026/invoice.pdf --expires 3600"
+        "<%= config.bin %> env delete STAGING --yes"
       ],
       "flags": {
         "json": {
@@ -5487,26 +5538,17 @@
           "multiple": false,
           "type": "option"
         },
-        "integration": {
-          "char": "i",
-          "description": "Files integration ID",
-          "env": "NORBIX_FILES_INTEGRATION_ID",
-          "name": "integration",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "expires": {
-          "description": "URL lifetime in seconds",
-          "name": "expires",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
+        "yes": {
+          "char": "y",
+          "description": "Skip the confirmation prompt",
+          "name": "yes",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "files:sign",
+      "id": "env:delete",
       "pluginAlias": "@norbix.ai/cli",
       "pluginName": "@norbix.ai/cli",
       "pluginType": "core",
@@ -5516,23 +5558,16 @@
       "relativePath": [
         "dist",
         "commands",
-        "files",
-        "sign.js"
+        "env",
+        "delete.js"
       ]
     },
-    "files:unpublish": {
+    "env:list": {
       "aliases": [],
-      "args": {
-        "remote": {
-          "description": "Remote file path, or folder prefix with --folder",
-          "name": "remote",
-          "required": true
-        }
-      },
-      "description": "Take away a file's (or a folder's) public link",
+      "args": {},
+      "description": "List the project's environments (PROD is always first)",
       "examples": [
-        "<%= config.bin %> files unpublish invoices/2026/invoice.pdf",
-        "<%= config.bin %> files unpublish invoices --folder"
+        "<%= config.bin %> env list"
       ],
       "flags": {
         "json": {
@@ -5582,31 +5617,16 @@
           "description": "Account ID (needed for account-scoped hub endpoints)",
           "env": "NORBIX_ACCOUNT_ID",
           "helpGroup": "GLOBAL",
-          "name": "account",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "profile": {
-          "description": "Use this profile from ~/.norbix/config (ignores the login session)",
-          "env": "NORBIX_PROFILE",
-          "helpGroup": "GLOBAL",
-          "name": "profile",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "folder": {
-          "description": "Unpublish the whole folder prefix, and every link inside it",
-          "name": "folder",
-          "allowNo": false,
-          "type": "boolean"
+          "name": "account",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         },
-        "integration": {
-          "char": "i",
-          "description": "Files integration ID",
-          "env": "NORBIX_FILES_INTEGRATION_ID",
-          "name": "integration",
+        "profile": {
+          "description": "Use this profile from ~/.norbix/config (ignores the login session)",
+          "env": "NORBIX_PROFILE",
+          "helpGroup": "GLOBAL",
+          "name": "profile",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -5614,7 +5634,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "files:unpublish",
+      "id": "env:list",
       "pluginAlias": "@norbix.ai/cli",
       "pluginName": "@norbix.ai/cli",
       "pluginType": "core",
@@ -5624,28 +5644,24 @@
       "relativePath": [
         "dist",
         "commands",
-        "files",
-        "unpublish.js"
+        "env",
+        "list.js"
       ]
     },
-    "files:upload": {
+    "env:use": {
       "aliases": [],
       "args": {
-        "file": {
-          "description": "Local file to upload",
-          "name": "file",
+        "name": {
+          "description": "Environment name (e.g. PROD, TEST)",
+          "name": "name",
           "required": true
-        },
-        "remote": {
-          "description": "Remote path (default: file name in the root folder)",
-          "name": "remote",
-          "required": false
         }
       },
-      "description": "Upload a local file (three steps: get signed URL, PUT bytes, commit).",
+      "description": "Set the default environment for future commands.\n\nWritten to the active session when you are logged in; with --profile it is\nwritten into that profile in ~/.norbix/config; otherwise to the [default]\nprofile. Override per command with --env.",
       "examples": [
-        "<%= config.bin %> files upload ./invoice.pdf",
-        "<%= config.bin %> files upload ./invoice.pdf invoices/2026/invoice.pdf"
+        "<%= config.bin %> env use TEST",
+        "<%= config.bin %> env use PROD",
+        "<%= config.bin %> env use STAGING --profile fitskin-prod"
       ],
       "flags": {
         "json": {
@@ -5708,27 +5724,11 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
-        },
-        "integration": {
-          "char": "i",
-          "description": "Files integration ID",
-          "env": "NORBIX_FILES_INTEGRATION_ID",
-          "name": "integration",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "content-type": {
-          "description": "MIME type (default: guessed from extension)",
-          "name": "content-type",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "files:upload",
+      "id": "env:use",
       "pluginAlias": "@norbix.ai/cli",
       "pluginName": "@norbix.ai/cli",
       "pluginType": "core",
@@ -5738,8 +5738,8 @@
       "relativePath": [
         "dist",
         "commands",
-        "files",
-        "upload.js"
+        "env",
+        "use.js"
       ]
     },
     "logs:list": {
@@ -10306,12 +10306,19 @@
         "show.js"
       ]
     },
-    "push:device:register": {
+    "files:integrations:test": {
       "aliases": [],
-      "args": {},
-      "description": "Register a device so push campaigns can reach it\n\nA device belongs to a user, so --user is required. --os is the operating\nsystem the token came from; the backend uses it to pick a provider.",
+      "args": {
+        "id": {
+          "description": "Files integration ID",
+          "name": "id",
+          "required": true
+        }
+      },
+      "description": "Check that a files integration really works\n\nRuns a live probe against the storage: uploads a small file, reads it, lists\nits folder and deletes it again. Prints one line per step — OK, FAILED or\nNOT_TESTED (skipped because an earlier step failed) — with the errors of a\nfailed step. Exits non-zero unless every step is OK.\n\nNeeds the files:create permission, because the probe writes to the storage.",
       "examples": [
-        "<%= config.bin %> push device register --user usr_123 --token dGVzdA== --os iOS"
+        "<%= config.bin %> files integrations test 55555555-5555-5555-5555-555555555555",
+        "<%= config.bin %> files integrations test 55555555-5555-5555-5555-555555555555 --json"
       ],
       "flags": {
         "json": {
@@ -10374,56 +10381,11 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
-        },
-        "user": {
-          "description": "User ID the device belongs to",
-          "name": "user",
-          "required": true,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "token": {
-          "description": "Device token from the platform",
-          "name": "token",
-          "required": true,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "os": {
-          "description": "Operating system, e.g. iOS or Android",
-          "name": "os",
-          "required": true,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "device-id": {
-          "description": "Stable device identifier",
-          "name": "device-id",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "model": {
-          "description": "Device model, e.g. iPhone 15",
-          "name": "model",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "name": {
-          "description": "The device's own name",
-          "name": "name",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "push:device:register",
+      "id": "files:integrations:test",
       "pluginAlias": "@norbix.ai/cli",
       "pluginName": "@norbix.ai/cli",
       "pluginType": "core",
@@ -10433,9 +10395,9 @@
       "relativePath": [
         "dist",
         "commands",
-        "push",
-        "device",
-        "register.js"
+        "files",
+        "integrations",
+        "test.js"
       ]
     },
     "push:integration:default": {
@@ -10932,7 +10894,139 @@
         "integration",
         "test.js"
       ]
+    },
+    "push:device:register": {
+      "aliases": [],
+      "args": {},
+      "description": "Register a device so push campaigns can reach it\n\nA device belongs to a user, so --user is required. --os is the operating\nsystem the token came from; the backend uses it to pick a provider.",
+      "examples": [
+        "<%= config.bin %> push device register --user usr_123 --token dGVzdA== --os iOS"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "project": {
+          "description": "Project ID",
+          "env": "NORBIX_PROJECT_ID",
+          "helpGroup": "GLOBAL",
+          "name": "project",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "env": {
+          "description": "Project environment (e.g. PROD, TEST)",
+          "env": "NORBIX_ENV",
+          "helpGroup": "GLOBAL",
+          "name": "env",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "region": {
+          "description": "Region code (e.g. nb-eu-germany)",
+          "env": "NORBIX_REGION",
+          "helpGroup": "GLOBAL",
+          "name": "region",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-key": {
+          "description": "API key (overrides profile and session)",
+          "env": "NORBIX_API_KEY",
+          "helpGroup": "GLOBAL",
+          "name": "api-key",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "account": {
+          "description": "Account ID (needed for account-scoped hub endpoints)",
+          "env": "NORBIX_ACCOUNT_ID",
+          "helpGroup": "GLOBAL",
+          "name": "account",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "profile": {
+          "description": "Use this profile from ~/.norbix/config (ignores the login session)",
+          "env": "NORBIX_PROFILE",
+          "helpGroup": "GLOBAL",
+          "name": "profile",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "user": {
+          "description": "User ID the device belongs to",
+          "name": "user",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "token": {
+          "description": "Device token from the platform",
+          "name": "token",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "os": {
+          "description": "Operating system, e.g. iOS or Android",
+          "name": "os",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "device-id": {
+          "description": "Stable device identifier",
+          "name": "device-id",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "model": {
+          "description": "Device model, e.g. iPhone 15",
+          "name": "model",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "name": {
+          "description": "The device's own name",
+          "name": "name",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "push:device:register",
+      "pluginAlias": "@norbix.ai/cli",
+      "pluginName": "@norbix.ai/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "push",
+        "device",
+        "register.js"
+      ]
     }
   },
-  "version": "0.2.0"
+  "version": "0.3.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norbix.ai/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Norbix CLI — manage your Norbix projects from the terminal. Built on the official TypeScript SDK.",
   "author": "UAB Isidos",
   "license": "MIT",
@@ -92,7 +92,12 @@
         "description": "Work with database collections (find, insert, update, delete)"
       },
       "files": {
-        "description": "Upload, download and manage files"
+        "description": "Upload, download and manage files",
+        "subtopics": {
+          "integrations": {
+            "description": "Check the storage behind a files integration"
+          }
+        }
       },
       "env": {
         "description": "Manage project environments (PROD, TEST, ...)"