@switchbot/openapi-cli 3.0.0 → 3.1.0

package/dist/commands/config.js

@@ -1,4 +1,6 @@
 import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import readline from 'node:readline';
 import { execFileSync } from 'node:child_process';
 import { stringArg } from '../utils/arg-parsers.js';
@@ -251,6 +253,24 @@ Files are written with mode 0600. Profiles live under ~/.switchbot/profiles/<nam
         }
         else {
             console.log(chalk.green('✓ Credentials saved'));
+            // Keychain-first hint: proactively suggest storing in OS keychain when
+            // the user is on a supported platform and saved to file (default path).
+            try {
+                const { selectCredentialStore } = await import('../credentials/keychain.js');
+                const store = await selectCredentialStore();
+                if (store.describe().backend === 'file') {
+                    const platform = process.platform;
+                    if (platform === 'darwin' || platform === 'win32') {
+                        console.error(chalk.grey('Tip: Your OS supports a native keychain. Run `switchbot auth keychain store` to move credentials off the plain config file for better security.'));
+                    }
+                    else if (platform === 'linux') {
+                        console.error(chalk.grey('Tip: If you have GNOME Keyring (secret-tool) installed, run `switchbot auth keychain store` to store credentials more securely.'));
+                    }
+                }
+            }
+            catch {
+                // Keychain probe failed — silently skip the tip
+            }
         }
     });
     config
@@ -294,4 +314,63 @@ Files are written with mode 0600. Profiles live under ~/.switchbot/profiles/<nam
             console.log(bits.join(' '));
         }
     });
+    // switchbot config agent-profile [--write]
+    config
+        .command('agent-profile')
+        .description('Emit (or write) an agent-safe profile template with conservative rate limits and audit logging.')
+        .option('--write', 'Write the template to ~/.switchbot/profiles/agent.json (requires --profile agent config set-token to add credentials).')
+        .option('--force', 'Overwrite an existing agent.json when used with --write.')
+        .addHelpText('after', `
+Outputs a starter profile.json suitable for AI agent / MCP integration:
+  - dailyCap: 100 (conservative; prevents runaway automation)
+  - label: "agent"
+  - description: "AI agent profile — conservative limits + audit enabled"
+  - defaults: { auditLog: true }  (enables audit logging by default)
+
+After writing, add credentials:
+  $ switchbot --profile agent config set-token <token> <secret>
+
+Then use the profile:
+  $ switchbot --profile agent devices list
+`)
+        .action((opts) => {
+        const template = {
+            label: 'agent',
+            description: 'AI agent profile — conservative limits + audit enabled',
+            limits: {
+                dailyCap: 100,
+            },
+            defaults: {
+                auditLog: true,
+            },
+        };
+        if (opts.write) {
+            const dir = path.join(os.homedir(), '.switchbot', 'profiles');
+            const dest = path.join(dir, 'agent.json');
+            if (!opts.force && fs.existsSync(dest)) {
+                exitWithError({ code: 2, kind: 'usage', message: `Agent profile already exists: ${dest}. Use --force to overwrite.` });
+            }
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+            }
+            fs.writeFileSync(dest, JSON.stringify(template, null, 2), { mode: 0o600 });
+            if (isJsonMode()) {
+                printJson({ ok: true, path: dest, template });
+            }
+            else {
+                console.log(`Agent profile written: ${dest}`);
+                console.log(`Next: switchbot --profile agent config set-token <token> <secret>`);
+            }
+        }
+        else {
+            if (isJsonMode()) {
+                printJson(template);
+            }
+            else {
+                console.log(JSON.stringify(template, null, 2));
+                console.log('');
+                console.log('Write with: switchbot config agent-profile --write');
+            }
+        }
+    });
 }

package/dist/commands/daemon.js

@@ -0,0 +1,367 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isJsonMode, printJson, exitWithError } from '../utils/output.js';
+import { readPidFile, writePidFile, isPidAlive, getDefaultPidFilePaths, writeReloadSentinel, sighupSupported } from '../rules/pid-file.js';
+import { stringArg } from '../utils/arg-parsers.js';
+import chalk from 'chalk';
+import { DAEMON_LOG_FILE, DAEMON_PID_FILE, DAEMON_STATE_FILE, HEALTHZ_PID_FILE, readDaemonState, writeDaemonState, } from '../lib/daemon-state.js';
+function readDaemonPid() {
+    return readPidFile(DAEMON_PID_FILE);
+}
+function readHealthPid() {
+    return readPidFile(HEALTHZ_PID_FILE);
+}
+function killIfAlive(pid, signal = 'SIGTERM') {
+    if (!pid)
+        return;
+    if (!isPidAlive(pid))
+        return;
+    process.kill(pid, signal);
+}
+function buildHealthSummary(state) {
+    const healthPid = readHealthPid();
+    const healthRunning = healthPid !== null && isPidAlive(healthPid);
+    const port = state?.healthzPort ?? null;
+    return {
+        configured: port !== null,
+        pid: healthRunning ? healthPid : null,
+        pidFile: HEALTHZ_PID_FILE,
+        port,
+        running: healthRunning,
+        url: port !== null ? `http://127.0.0.1:${port}/healthz` : null,
+    };
+}
+function getDaemonStatus() {
+    const state = readDaemonState();
+    const pid = readDaemonPid();
+    const running = pid !== null && isPidAlive(pid);
+    return {
+        status: running ? 'running' : 'stopped',
+        pid: running ? pid : null,
+        pidFile: DAEMON_PID_FILE,
+        logFile: DAEMON_LOG_FILE,
+        stateFile: DAEMON_STATE_FILE,
+        health: buildHealthSummary(state),
+        lastReloadAt: state?.lastReloadAt ?? null,
+        lastReloadStatus: state?.lastReloadStatus ?? null,
+        lastReloadMessage: state?.lastReloadMessage ?? null,
+        startedAt: state?.startedAt ?? null,
+        stoppedAt: state?.stoppedAt ?? null,
+    };
+}
+function persistState(partial) {
+    const previous = readDaemonState();
+    const next = {
+        ...(previous ?? {}),
+        status: partial.status ?? previous?.status ?? 'stopped',
+        pid: partial.pid ?? previous?.pid ?? null,
+        ...partial,
+        logFile: DAEMON_LOG_FILE,
+        pidFile: DAEMON_PID_FILE,
+        stateFile: DAEMON_STATE_FILE,
+    };
+    writeDaemonState(next);
+    return next;
+}
+function renderHumanStatus(status) {
+    if (status.status === 'running' && status.pid !== null) {
+        console.log(`${chalk.green('●')} Daemon is running (pid ${status.pid}).`);
+    }
+    else {
+        console.log(`${chalk.grey('○')} Daemon is not running.`);
+    }
+    if (status.startedAt)
+        console.log(`  Started: ${status.startedAt}`);
+    if (status.stoppedAt)
+        console.log(`  Stopped: ${status.stoppedAt}`);
+    console.log(`  Log:     ${status.logFile}`);
+    console.log(`  PID:     ${status.pidFile}`);
+    console.log(`  State:   ${status.stateFile}`);
+    if (status.lastReloadAt) {
+        console.log(`  Reload:  ${status.lastReloadAt} (${status.lastReloadStatus ?? 'unknown'})`);
+        if (status.lastReloadMessage)
+            console.log(`           ${status.lastReloadMessage}`);
+    }
+    if (status.health.configured) {
+        if (status.health.running) {
+            console.log(`${chalk.green('✓')} Health server running (pid ${status.health.pid})`);
+        }
+        else {
+            console.log(`${chalk.yellow('!')} Health server configured but not running`);
+        }
+        if (status.health.url)
+            console.log(`  Health:  ${status.health.url}`);
+    }
+}
+export function registerDaemonCommand(program) {
+    const daemon = program
+        .command('daemon')
+        .description('Manage the background SwitchBot rules daemon and its health endpoint.')
+        .addHelpText('after', `
+The daemon runs \`switchbot rules run\` as a detached background process,
+tracks runtime metadata in ~/.switchbot/daemon.state.json, and can optionally
+co-launch a health endpoint via \`switchbot health serve\`.
+
+Subcommands:
+  start [--policy <path>]   Start the daemon (no-op if already running).
+  stop                      Stop the daemon and any co-launched health server.
+  status                    Report the daemon state, log path, and health summary.
+  reload                    Trigger a hot reload for the running rules engine.
+
+The daemon reads the same policy file as \`switchbot rules run\`.
+`);
+    daemon
+        .command('start')
+        .description('Start the rules-engine daemon in the background.')
+        .option('--policy <path>', 'Policy file path (default: auto-detected)', stringArg('--policy'))
+        .option('--force', 'Restart even if the daemon appears to be running.')
+        .option('--healthz-port <n>', 'Also start a health HTTP server on this port (default: disabled).')
+        .action((opts) => {
+        const current = getDaemonStatus();
+        if (current.status === 'running' && !opts.force) {
+            if (isJsonMode()) {
+                printJson({ result: 'already-running', ...current });
+            }
+            else {
+                console.log(`Daemon is already running (pid ${current.pid}). Use --force to restart.`);
+            }
+            return;
+        }
+        if (opts.force) {
+            try {
+                killIfAlive(current.pid);
+                killIfAlive(current.health.pid);
+            }
+            catch {
+                // best effort
+            }
+        }
+        const thisFile = fileURLToPath(import.meta.url);
+        const cliEntry = path.resolve(path.dirname(thisFile), 'index.js');
+        const args = ['rules', 'run'];
+        if (opts.policy)
+            args.push(opts.policy);
+        fs.mkdirSync(path.dirname(DAEMON_PID_FILE), { recursive: true, mode: 0o700 });
+        persistState({
+            status: 'starting',
+            pid: null,
+            startedAt: new Date().toISOString(),
+            stoppedAt: undefined,
+            failedAt: undefined,
+            failureReason: undefined,
+            healthzPort: opts.healthzPort ? Number.parseInt(opts.healthzPort, 10) : null,
+            healthzPid: null,
+            healthzPidFile: HEALTHZ_PID_FILE,
+        });
+        const logFd = fs.openSync(DAEMON_LOG_FILE, 'a');
+        const child = spawn(process.execPath, [cliEntry, ...args], {
+            detached: true,
+            stdio: ['ignore', logFd, logFd],
+            env: { ...process.env },
+        });
+        child.unref();
+        fs.closeSync(logFd);
+        const newPid = child.pid;
+        if (!newPid) {
+            persistState({
+                status: 'failed',
+                pid: null,
+                failedAt: new Date().toISOString(),
+                failureReason: 'Failed to spawn daemon process.',
+            });
+            exitWithError({ code: 1, kind: 'runtime', message: 'Failed to spawn daemon process.' });
+        }
+        writePidFile(DAEMON_PID_FILE, newPid);
+        let healthzPid = null;
+        let healthzPort = opts.healthzPort ? Number.parseInt(opts.healthzPort, 10) : null;
+        if (healthzPort !== null) {
+            const healthArgs = ['health', 'serve', '--port', String(healthzPort)];
+            const healthLogFd = fs.openSync(DAEMON_LOG_FILE, 'a');
+            const healthChild = spawn(process.execPath, [cliEntry, ...healthArgs], {
+                detached: true,
+                stdio: ['ignore', healthLogFd, healthLogFd],
+                env: { ...process.env },
+            });
+            healthChild.unref();
+            fs.closeSync(healthLogFd);
+            if (healthChild.pid) {
+                healthzPid = healthChild.pid;
+                writePidFile(HEALTHZ_PID_FILE, healthzPid);
+            }
+        }
+        persistState({
+            status: 'running',
+            pid: newPid,
+            startedAt: new Date().toISOString(),
+            stoppedAt: undefined,
+            failedAt: undefined,
+            failureReason: undefined,
+            healthzPort,
+            healthzPid,
+            healthzPidFile: HEALTHZ_PID_FILE,
+        });
+        const status = getDaemonStatus();
+        if (isJsonMode()) {
+            printJson({ result: 'started', ...status });
+        }
+        else {
+            console.log(`${chalk.green('✓')} Daemon started (pid ${newPid})`);
+            console.log(`  Log:     ${DAEMON_LOG_FILE}`);
+            console.log(`  PID:     ${DAEMON_PID_FILE}`);
+            console.log(`  State:   ${DAEMON_STATE_FILE}`);
+            console.log(`  Reload:  switchbot daemon reload`);
+            if (status.health.running && status.health.url) {
+                console.log(`${chalk.green('✓')} Health server started (pid ${status.health.pid})`);
+                console.log(`  Health:  ${status.health.url}`);
+            }
+        }
+    });
+    daemon
+        .command('stop')
+        .description('Stop the background daemon by sending SIGTERM.')
+        .action(() => {
+        const status = getDaemonStatus();
+        if (status.status !== 'running' || status.pid === null) {
+            persistState({ status: 'stopped', pid: null, stoppedAt: new Date().toISOString() });
+            if (isJsonMode()) {
+                printJson({ result: 'not-running', ...getDaemonStatus() });
+            }
+            else {
+                console.log(`No running daemon found (pid file: ${DAEMON_PID_FILE}).`);
+            }
+            return;
+        }
+        try {
+            killIfAlive(status.pid);
+            killIfAlive(status.health.pid);
+        }
+        catch (err) {
+            persistState({
+                status: 'failed',
+                pid: status.pid,
+                failedAt: new Date().toISOString(),
+                failureReason: err instanceof Error ? err.message : String(err),
+            });
+            exitWithError({
+                code: 1,
+                kind: 'runtime',
+                message: `Failed to stop daemon (pid ${status.pid}): ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+        try {
+            fs.unlinkSync(DAEMON_PID_FILE);
+        }
+        catch { /* best effort */ }
+        try {
+            fs.unlinkSync(HEALTHZ_PID_FILE);
+        }
+        catch { /* best effort */ }
+        persistState({
+            status: 'stopped',
+            pid: null,
+            healthzPid: null,
+            stoppedAt: new Date().toISOString(),
+        });
+        if (isJsonMode()) {
+            printJson({ result: 'stopped', ...getDaemonStatus() });
+        }
+        else {
+            console.log(`${chalk.green('✓')} Daemon stopped (pid ${status.pid}).`);
+        }
+    });
+    daemon
+        .command('status')
+        .description('Report whether the daemon is currently running.')
+        .action(() => {
+        const status = getDaemonStatus();
+        if (isJsonMode()) {
+            printJson(status);
+            return;
+        }
+        renderHumanStatus(status);
+    });
+    daemon
+        .command('reload')
+        .description('Trigger a hot reload on the running rules-engine daemon.')
+        .action(() => {
+        const daemonStatus = getDaemonStatus();
+        if (daemonStatus.status !== 'running' || daemonStatus.pid === null) {
+            persistState({
+                status: 'failed',
+                failedAt: new Date().toISOString(),
+                failureReason: 'No running daemon to reload.',
+                lastReloadAt: new Date().toISOString(),
+                lastReloadStatus: 'failed',
+                lastReloadMessage: 'No running daemon to reload.',
+            });
+            exitWithError({
+                code: 2,
+                kind: 'usage',
+                message: `No running daemon found (pid file: ${DAEMON_PID_FILE}).`,
+            });
+        }
+        const pidPaths = getDefaultPidFilePaths();
+        const rulesPid = readPidFile(pidPaths.pidFile);
+        if (rulesPid === null || !isPidAlive(rulesPid)) {
+            persistState({
+                status: 'failed',
+                failedAt: new Date().toISOString(),
+                failureReason: 'Rules engine PID is missing or stale.',
+                lastReloadAt: new Date().toISOString(),
+                lastReloadStatus: 'failed',
+                lastReloadMessage: 'Rules engine PID is missing or stale.',
+            });
+            exitWithError({
+                code: 2,
+                kind: 'usage',
+                message: `No running rules engine found for daemon reload (pid file: ${pidPaths.pidFile}).`,
+            });
+        }
+        let method;
+        try {
+            if (sighupSupported()) {
+                process.kill(rulesPid, 'SIGHUP');
+                method = 'SIGHUP';
+            }
+            else {
+                writeReloadSentinel(pidPaths.reloadFile);
+                method = 'sentinel';
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            persistState({
+                status: 'failed',
+                failedAt: new Date().toISOString(),
+                failureReason: message,
+                lastReloadAt: new Date().toISOString(),
+                lastReloadStatus: 'failed',
+                lastReloadMessage: message,
+            });
+            exitWithError({
+                code: 1,
+                kind: 'runtime',
+                message: `Failed to reload daemon: ${message}`,
+            });
+        }
+        persistState({
+            status: 'running',
+            lastReloadAt: new Date().toISOString(),
+            lastReloadStatus: 'ok',
+            lastReloadMessage: method === 'SIGHUP'
+                ? `Sent SIGHUP to rules engine pid ${rulesPid}.`
+                : `Wrote reload sentinel ${pidPaths.reloadFile}.`,
+        });
+        const status = getDaemonStatus();
+        if (isJsonMode()) {
+            printJson({ result: 'reloaded', method, ...status });
+        }
+        else {
+            console.log(`${chalk.green('✓')} Reload requested via ${method}.`);
+            if (status.lastReloadMessage)
+                console.log(`  ${status.lastReloadMessage}`);
+        }
+    });
+}

package/dist/commands/devices.js

@@ -16,6 +16,7 @@ import { registerDevicesMetaCommand } from './device-meta.js';
 import { isDryRun } from '../utils/flags.js';
 import { DryRunSignal } from '../api/client.js';
 import { resolveField, resolveFieldList, listSupportedFieldInputs } from '../schema/field-aliases.js';
+import { allowsDirectDestructiveExecution, destructiveExecutionHint } from '../lib/destructive-mode.js';
 const EXPAND_HINTS = {
     'Air Conditioner': { command: 'setAll', flags: '--temp 26 --mode cool --fan low --power on' },
     'Curtain': { command: 'setPosition', flags: '--position 50 --mode silent' },
@@ -355,7 +356,8 @@ Examples:
         .option('--name-category <cat>', 'Narrow --name by category: physical|ir', enumArg('--name-category', ['physical', 'ir']))
         .option('--name-room <room>', 'Narrow --name by room name (substring match)', stringArg('--name-room'))
         .option('--type <commandType>', 'Command type: "command" for built-in commands (default), "customize" for user-defined IR buttons', enumArg('--type', COMMAND_TYPES), 'command')
-        .option('--yes', 'Confirm a destructive command (Smart Lock unlock, Garage open, …). --dry-run is always allowed without --yes.')
+        .option('--yes', 'Confirm a destructive command in an explicit dev profile. --dry-run is always allowed without --yes.')
+        .option('--explain', 'Print a human-readable summary of what this command would do (risk level, device type, idempotency) then exit without executing.')
         .option('--allow-unknown-device', 'Allow targeting a deviceId that is not in the local cache. By default unknown IDs exit 2 so --dry-run is a reliable pre-flight gate; use this flag for scripted pass-through.')
         .option('--skip-param-validation', 'Skip client-side parameter validation (escape hatch — prefer fixing the argument over using this).')
         .option('--idempotency-key <key>', 'Client-supplied key to dedupe retries. process-local 60s window; cache is per Node process (MCP session, batch run, plan run). Independent CLI invocations do not share cache.', stringArg('--idempotency-key'))
@@ -393,8 +395,8 @@ Common errors:
 
 Safety:
   Destructive commands (Smart Lock unlock, Garage Door Opener turnOn/turnOff,
-  Keypad createKey/deleteKey, …) are blocked by default. Pass --yes to confirm,
-  or --dry-run to preview without sending.
+  Keypad createKey/deleteKey, …) are blocked by default. Use the reviewed plan
+  flow instead, or --dry-run to preview without sending.
 
 Examples:
   $ switchbot devices command ABC123 turnOn
@@ -402,7 +404,7 @@ Examples:
   $ switchbot devices command ABC123 setAll "26,1,3,on"
   $ switchbot devices command ABC123 startClean '{"action":"sweep","param":{"fanLevel":2,"times":1}}'
   $ switchbot devices command ABC123 "MyButton" --type customize
-  $ switchbot devices command <lockId> unlock --yes
+  $ switchbot devices command <lockId> unlock --dry-run
 `)
         .action(async (deviceIdArg, cmdArg, parameter, options) => {
         // Declared outside try so the DryRunSignal catch branch can reference them.
@@ -507,22 +509,72 @@ Examples:
                     parameter = paramCheck.normalized;
             }
             const cachedForGuard = getCachedDevice(deviceId);
-            if (!options.yes &&
-                !isDryRun() &&
-                isDestructiveCommand(cachedForGuard?.type, cmd, options.type)) {
+            // --explain: print intent + risk metadata without executing
+            if (options.explain) {
+                const isDestructive = isDestructiveCommand(cachedForGuard?.type, cmd, options.type);
+                const reason = getDestructiveReason(cachedForGuard?.type, cmd, options.type);
+                const riskLevel = isDestructive ? 'high' : options.type === 'command' ? 'medium' : 'low';
+                const recommendedMode = isDestructive ? 'review-before-execute' : 'direct';
+                if (isJsonMode()) {
+                    printJson({
+                        intent: `Send command "${cmd}" to device ${deviceId}`,
+                        deviceType: cachedForGuard?.type ?? 'unknown',
+                        deviceName: cachedForGuard?.name ?? null,
+                        command: cmd,
+                        parameter: parameter ?? null,
+                        commandType: options.type,
+                        riskLevel,
+                        requiresConfirmation: isDestructive,
+                        safetyReason: reason ?? null,
+                        recommendedMode,
+                        note: 'This is a dry explanation only — command was NOT executed.',
+                    });
+                }
+                else {
+                    console.log(`Command: ${cmd} on device ${deviceId}`);
+                    console.log(`Device type: ${cachedForGuard?.type ?? 'unknown'}${cachedForGuard?.name ? ` (${cachedForGuard.name})` : ''}`);
+                    console.log(`Parameter: ${parameter ?? '(none)'}`);
+                    console.log(`Risk level: ${riskLevel}`);
+                    if (reason)
+                        console.log(`Safety reason: ${reason}`);
+                    if (isDestructive)
+                        console.log(`Requires plan approval by default. ${destructiveExecutionHint()}`);
+                    console.log('(not executed — remove --explain to run)');
+                }
+                process.exit(0);
+            }
+            const destructive = isDestructiveCommand(cachedForGuard?.type, cmd, options.type);
+            if (!isDryRun() && destructive && !options.yes && !allowsDirectDestructiveExecution()) {
+                const typeLabel = cachedForGuard?.type ?? 'unknown';
+                const reason = getDestructiveReason(cachedForGuard?.type, cmd, options.type);
+                exitWithError({
+                    kind: 'guard',
+                    message: `Direct destructive execution disabled — destructive command "${cmd}" on ${typeLabel}.`,
+                    hint: reason ? `${destructiveExecutionHint()} Reason: ${reason}` : destructiveExecutionHint(),
+                    context: {
+                        command: cmd,
+                        deviceType: typeLabel,
+                        deviceId,
+                        directExecutionAllowed: false,
+                        requiredWorkflow: 'plan-approval',
+                        ...(reason ? { safetyReason: reason, destructiveReason: reason } : {}),
+                    },
+                });
+            }
+            if (!options.yes && !isDryRun() && destructive) {
                 const typeLabel = cachedForGuard?.type ?? 'unknown';
                 const reason = getDestructiveReason(cachedForGuard?.type, cmd, options.type);
                 exitWithError({
                     kind: 'guard',
                     message: `Refusing to run destructive command "${cmd}" on ${typeLabel} without --yes.`,
                     hint: reason
-                        ? `Re-run with --yes to confirm. Reason: ${reason}`
-                        : 'Re-run with --yes to confirm, or --dry-run to preview without sending.',
+                        ? `Re-run with --yes only from an explicit dev profile, or use the reviewed plan flow. Reason: ${reason}`
+                        : `Re-run with --yes only from an explicit dev profile, use the reviewed plan flow, or --dry-run to preview without sending.`,
                     context: { command: cmd, deviceType: typeLabel, deviceId, ...(reason ? { safetyReason: reason, destructiveReason: reason } : {}) },
                 });
             }
             // Warn when --yes is given but the command is not destructive (no-op flag)
-            if (options.yes && !isDestructiveCommand(cachedForGuard?.type, cmd, options.type) && !isDryRun()) {
+            if (options.yes && !destructive && !isDryRun()) {
                 console.error(`Note: --yes has no effect; "${cmd}" is not a destructive command.`);
             }
             // parameter may be a JSON object string (e.g. S10 startClean) or a plain string