@manfred-kunze-dev/iot-cli 3.0.0-dev.1

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026-present Manfred Kunze Dev
+
+All rights reserved.
+
+This software and associated documentation files (the "Software") are proprietary
+and confidential. No part of the Software may be reproduced, distributed, or
+transmitted in any form or by any means, including photocopying, recording, or
+other electronic or mechanical methods, without the prior written permission of
+the copyright holder.
+
+The Software is provided "as is", without warranty of any kind, express or implied,
+including but not limited to the warranties of merchantability, fitness for a
+particular purpose, and noninfringement. In no event shall the authors or copyright
+holders be liable for any claim, damages, or other liability, whether in an action
+of contract, tort, or otherwise, arising from, out of, or in connection with the
+Software or the use or other dealings in the Software.
+
+Usage of this Software is permitted only in accordance with the terms and conditions
+set forth by Manfred Kunze Dev.

package/README.md

@@ -0,0 +1,140 @@
+# iot CLI
+
+Command-line interface for the [iot platform](https://iot.manfred-kunze.dev) by Manfred Kunze Development.
+
+Manage devices, sensors, sites, readings, events and more — straight from your terminal.
+
+## Installation
+
+```bash
+# Latest stable release
+npm install -g @manfred-kunze-dev/iot-cli
+
+# Pre-release (dev channel)
+npm install -g @manfred-kunze-dev/iot-cli@dev
+```
+
+The CLI is installed as `iot`, `mkd-iot`, and `mki` (short alias) — pick whichever you prefer:
+
+```bash
+iot --version
+mki --version
+```
+
+The CLI will notify you when a newer version is available.
+
+## Quick Start
+
+```bash
+# Authenticate
+iot auth login
+
+# Verify
+iot auth status
+```
+
+## Authentication
+
+The CLI supports multiple authentication methods (highest priority first):
+
+| Method | Example |
+|--------|---------|
+| CLI flags | `--api-key sk_... --base-url https://...` |
+| Environment variables | `IOT_API_KEY`, `IOT_BASE_URL` |
+| Local `.iot` file | JSON file in the current directory or any ancestor |
+| Config store | `~/.config/iot-cli/config.json` (set via `iot auth login`) |
+
+```bash
+iot auth login     # Interactive setup
+iot auth status    # Verify credentials
+iot auth logout    # Clear stored credentials
+```
+
+## Contexts
+
+The CLI supports kubectl-style contexts for switching between organizations and environments:
+
+```bash
+# Contexts are created automatically via `iot auth login`
+iot context list              # List all contexts
+iot context use prod          # Switch active context
+iot context create staging    # Create a new context
+iot context rename old new    # Rename a context
+iot context delete old        # Remove a context
+iot context current           # Print just the active name (script-friendly)
+```
+
+You can also switch contexts for a single invocation:
+
+```bash
+iot --context staging auth status
+```
+
+## Commands (foundation — v1)
+
+| Command | Description |
+|---------|-------------|
+| `auth` | Login, logout, and check auth status |
+| `config` | Get, set, and list global configuration values |
+| `context` | Manage CLI contexts for multiple environments |
+| `docs` | Browse API documentation from the terminal |
+
+Resource commands (`devices`, `sensors`, `sites`, `readings`, `events`, …) ship in later releases.
+
+### Global Options
+
+| Flag | Description |
+|------|-------------|
+| `--api-key <key>` | Override the API key |
+| `--base-url <url>` | Override the base URL |
+| `--context <name>` | Use a named context for this invocation without switching the active one |
+| `--json` | Output raw JSON instead of formatted tables |
+| `--no-color` | Disable colored output |
+| `--verbose` | Print resolved base URL, masked key, and request method+path on stderr before each call |
+
+## Output
+
+Stdout carries the command's data payload (table, JSON, created resource ID). Everything else — spinners, errors, the update banner — goes to stderr. This makes pipelines like `iot devices list --json | jq` clean.
+
+Exit codes:
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Generic error |
+| 2 | Not authenticated (401) |
+| 3 | Forbidden (403) |
+| 4 | Not found (404) |
+| 5 | Conflict (409) |
+| 6 | Validation error (422) |
+| 7 | Server error (5xx) |
+| 8 | Network error |
+
+## Development
+
+```bash
+# Install deps
+npm ci
+
+# Build
+npm run build
+
+# Watch + rebuild
+npm run dev
+
+# Type-check only
+npm run typecheck
+
+# Run tests
+npm test
+
+# Regenerate typed client from a running dev backend
+SPRING_PROFILES_ACTIVE=spec ./mvnw.cmd -pl backend spring-boot:run   # in backend/
+npm run generate                                                       # in cli/
+```
+
+See [`docs/superpowers/specs/2026-05-25-iot-cli-foundation-design.md`](../docs/superpowers/specs/2026-05-25-iot-cli-foundation-design.md) for the full design.
+
+## License
+
+Proprietary — see [LICENSE](./LICENSE) for details.

package/dist/commands/auth.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function makeAuthCommand(): Command;
+//# sourceMappingURL=auth.d.ts.map

package/dist/commands/auth.js

@@ -0,0 +1,204 @@
+import { Command } from "commander";
+import { createInterface } from "node:readline/promises";
+import { DEFAULT_BASE_URL, getActiveContextName, getActiveContext, getContextCount, setContext, setActiveContext, deleteContext, isJsonOutput, resolveConfig, } from "../lib/config.js";
+import { getClient } from "../lib/client.js";
+import { printJson, printKeyValue, printSuccess, maskKey } from "../lib/output.js";
+import { handleError } from "../lib/errors.js";
+export function makeAuthCommand() {
+    const cmd = new Command("auth").description("Manage authentication");
+    cmd
+        .command("login")
+        .description("Configure API credentials for the current context")
+        .option("--api-key <key>", "API key (skips the prompt)")
+        .option("--base-url <url>", "Base URL (skips the prompt)")
+        .action(async (opts, command) => {
+        try {
+            let { apiKey, baseUrl } = opts;
+            const contextName = getActiveContextName();
+            const currentCtx = getActiveContext();
+            if (!apiKey || !baseUrl) {
+                const rl = createInterface({ input: process.stdin, output: process.stderr });
+                try {
+                    if (!baseUrl) {
+                        const defaultUrl = currentCtx?.baseUrl ?? DEFAULT_BASE_URL;
+                        const answer = (await rl.question(`Base URL [${defaultUrl}]: `)).trim();
+                        baseUrl = answer || defaultUrl;
+                    }
+                    if (!apiKey) {
+                        apiKey = (await promptHidden(rl, "API Key: ")).trim();
+                    }
+                }
+                finally {
+                    rl.close();
+                }
+            }
+            if (!apiKey) {
+                throw new Error("API key is required.");
+            }
+            setContext(contextName, { apiKey, baseUrl: baseUrl });
+            setActiveContext(contextName);
+            // Validate by probing /v1/devices/summary so the user knows the
+            // creds work before they exit the prompt.
+            const { client } = getClient(command);
+            const { data, error } = await client.GET("/v1/devices/summary");
+            if (error) {
+                throw new Error("Saved credentials, but the validation probe failed. " +
+                    "Double-check the API key and base URL with `iot auth status`.");
+            }
+            if (isJsonOutput(command)) {
+                printJson({
+                    success: true,
+                    context: contextName,
+                    baseUrl,
+                    devices: data?.total ?? null,
+                });
+            }
+            else {
+                printSuccess(`Credentials saved (context: ${contextName}).`, "stderr");
+            }
+        }
+        catch (err) {
+            handleError(err, { json: isJsonOutput(command) });
+        }
+    });
+    cmd
+        .command("status")
+        .description("Show authentication status for the active context")
+        .action(async (_opts, command) => {
+        try {
+            const json = isJsonOutput(command);
+            let config;
+            try {
+                config = resolveConfig(command);
+            }
+            catch {
+                if (json) {
+                    printJson({ authenticated: false });
+                }
+                else {
+                    process.stderr.write("Not authenticated.\n");
+                    process.stderr.write('Run "iot auth login" to configure.\n');
+                }
+                process.exitCode = 2;
+                return;
+            }
+            const { apiKey, baseUrl } = config;
+            const multiContext = getContextCount() > 1;
+            const contextName = getActiveContextName();
+            try {
+                const { client } = getClient(command);
+                const { data, error } = await client.GET("/v1/devices/summary");
+                if (error) {
+                    throw error;
+                }
+                const devices = data?.total ?? 0;
+                if (json) {
+                    printJson({
+                        authenticated: true,
+                        ...(multiContext ? { context: contextName } : {}),
+                        baseUrl,
+                        apiKeyPreview: maskKey(apiKey),
+                        devices,
+                    });
+                }
+                else {
+                    printKeyValue({
+                        Status: "Authenticated",
+                        ...(multiContext ? { Context: contextName } : {}),
+                        "Base URL": baseUrl,
+                        "API Key": maskKey(apiKey),
+                        Devices: devices,
+                    });
+                }
+            }
+            catch (err) {
+                if (json) {
+                    printJson({
+                        authenticated: false,
+                        ...(multiContext ? { context: contextName } : {}),
+                        baseUrl,
+                        apiKeyPreview: maskKey(apiKey),
+                        error: "validation_failed",
+                    });
+                }
+                else {
+                    process.stderr.write("Credentials configured but validation failed.\n");
+                    printKeyValue({
+                        ...(multiContext ? { Context: contextName } : {}),
+                        "Base URL": baseUrl,
+                        "API Key": maskKey(apiKey),
+                    });
+                }
+                throw err;
+            }
+        }
+        catch (err) {
+            handleError(err, { json: isJsonOutput(command) });
+        }
+    });
+    cmd
+        .command("logout")
+        .description("Clear the API key from the active context (keeps the base URL)")
+        .action(async (_opts, command) => {
+        try {
+            const contextName = getActiveContextName();
+            const count = getContextCount();
+            if (count === 0) {
+                // Nothing configured — silent success.
+                printSuccess("No credentials to clear.", "stderr");
+                return;
+            }
+            const ctx = getActiveContext();
+            if (count <= 1) {
+                // Last context — keep the entry, just blank the key. This matches
+                // the spec: "logout clears the active context's apiKey, keeps baseUrl
+                // so re-login is one prompt."
+                setContext(contextName, { apiKey: "", baseUrl: ctx?.baseUrl ?? DEFAULT_BASE_URL });
+            }
+            else {
+                deleteContext(contextName);
+            }
+            if (isJsonOutput(command)) {
+                printJson({ success: true, context: contextName });
+            }
+            else {
+                printSuccess("Credentials cleared.", "stderr");
+            }
+        }
+        catch (err) {
+            handleError(err, { json: isJsonOutput(command) });
+        }
+    });
+    return cmd;
+}
+/**
+ * Tiny hidden-input helper for API keys. readline.question doesn't natively
+ * support hiding input on Windows/POSIX consistently, so we mute the muxed
+ * output stream while the user types.
+ */
+function promptHidden(rl, prompt) {
+    return new Promise((resolveAnswer, rejectAnswer) => {
+        const mutableStdout = rl.output;
+        const original = mutableStdout.write.bind(mutableStdout);
+        let muted = false;
+        mutableStdout.write = ((chunk, enc, cb) => {
+            if (muted && typeof chunk === "string") {
+                return original("", enc, cb);
+            }
+            return original(chunk, enc, cb);
+        });
+        process.stderr.write(prompt);
+        muted = true;
+        rl.question("")
+            .then((answer) => {
+            mutableStdout.write = original;
+            process.stderr.write("\n");
+            resolveAnswer(answer);
+        })
+            .catch((err) => {
+            mutableStdout.write = original;
+            rejectAnswer(err);
+        });
+    });
+}
+//# sourceMappingURL=auth.js.map

package/dist/commands/config.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function makeConfigCommand(): Command;
+//# sourceMappingURL=config.d.ts.map

package/dist/commands/config.js

@@ -0,0 +1,94 @@
+import { Command } from "commander";
+import { isPreferenceKey, getPreference, setPreference, unsetPreference, listPreferences, listPreferenceKeys, isJsonOutput, } from "../lib/config.js";
+import { printTable, printJson, printSuccess } from "../lib/output.js";
+import { handleError, CLIError, EXIT } from "../lib/errors.js";
+export function makeConfigCommand() {
+    const cmd = new Command("config").description("Manage global CLI preferences (not per-context)");
+    cmd
+        .command("get <key>")
+        .description("Get a preference value")
+        .action((key, _opts, command) => {
+        try {
+            ensureValidKey(key);
+            const value = getPreference(key);
+            if (isJsonOutput(command)) {
+                printJson({ key, value: value ?? null });
+            }
+            else if (value === undefined) {
+                process.stderr.write(`(unset)\n`);
+            }
+            else {
+                process.stdout.write(String(value) + "\n");
+            }
+        }
+        catch (err) {
+            handleError(err, { json: isJsonOutput(command) });
+        }
+    });
+    cmd
+        .command("set <key> <value>")
+        .description("Set a preference value")
+        .action((key, value, _opts, command) => {
+        try {
+            ensureValidKey(key);
+            setPreference(key, value);
+            if (isJsonOutput(command)) {
+                printJson({ success: true, key, value });
+            }
+            else {
+                printSuccess(`Set ${key}=${value}`, "stderr");
+            }
+        }
+        catch (err) {
+            handleError(err, { json: isJsonOutput(command) });
+        }
+    });
+    cmd
+        .command("unset <key>")
+        .description("Remove a preference")
+        .action((key, _opts, command) => {
+        try {
+            ensureValidKey(key);
+            unsetPreference(key);
+            if (isJsonOutput(command)) {
+                printJson({ success: true, key });
+            }
+            else {
+                printSuccess(`Unset ${key}`, "stderr");
+            }
+        }
+        catch (err) {
+            handleError(err, { json: isJsonOutput(command) });
+        }
+    });
+    cmd
+        .command("list")
+        .description("List all preferences and their valid keys")
+        .action((_opts, command) => {
+        try {
+            const prefs = listPreferences();
+            if (isJsonOutput(command)) {
+                printJson({ preferences: prefs, validKeys: listPreferenceKeys() });
+                return;
+            }
+            const rows = listPreferenceKeys().map((key) => ({
+                key,
+                value: prefs[key] ?? "(unset)",
+            }));
+            printTable(rows, [
+                { key: "key", header: "KEY" },
+                { key: "value", header: "VALUE" },
+            ]);
+        }
+        catch (err) {
+            handleError(err, { json: isJsonOutput(command) });
+        }
+    });
+    return cmd;
+}
+function ensureValidKey(key) {
+    if (!isPreferenceKey(key)) {
+        throw new CLIError(`Unknown preference key: ${key}. Valid keys: ${listPreferenceKeys().join(", ")}`, EXIT.VALIDATION);
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/commands/context.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function makeContextCommand(): Command;
+//# sourceMappingURL=context.d.ts.map

package/dist/commands/context.js

@@ -0,0 +1,137 @@
+import { Command } from "commander";
+import { getAllContexts, getActiveContextName, setActiveContext, setContext, deleteContext, renameContext, isJsonOutput, DEFAULT_BASE_URL, validateContextName, } from "../lib/config.js";
+import { printTable, printJson, printSuccess, maskKey } from "../lib/output.js";
+import { handleError } from "../lib/errors.js";
+export function makeContextCommand() {
+    const cmd = new Command("context").description("Manage CLI contexts (environments)");
+    cmd
+        .command("list")
+        .description("List all contexts")
+        .action((_opts, command) => {
+        try {
+            const contexts = getAllContexts();
+            const active = getActiveContextName();
+            const rows = Object.entries(contexts).map(([name, ctx]) => ({
+                name,
+                baseUrl: ctx.baseUrl,
+                apiKey: ctx.apiKey ? maskKey(ctx.apiKey) : "(unset)",
+                active: name === active ? "*" : "",
+            }));
+            if (isJsonOutput(command)) {
+                printJson({ active, contexts });
+                return;
+            }
+            if (rows.length === 0) {
+                process.stderr.write('No contexts configured. Run "iot auth login" to create one.\n');
+                return;
+            }
+            printTable(rows, [
+                { key: "active", header: "" },
+                { key: "name", header: "NAME" },
+                { key: "baseUrl", header: "BASE URL" },
+                { key: "apiKey", header: "API KEY" },
+            ]);
+        }
+        catch (err) {
+            handleError(err, { json: isJsonOutput(command) });
+        }
+    });
+    cmd
+        .command("use <name>")
+        .description("Switch the active context")
+        .action((name, _opts, command) => {
+        try {
+            setActiveContext(name);
+            if (isJsonOutput(command)) {
+                printJson({ success: true, currentContext: name });
+            }
+            else {
+                printSuccess(`Switched to context "${name}".`, "stderr");
+            }
+        }
+        catch (err) {
+            handleError(err, { json: isJsonOutput(command) });
+        }
+    });
+    cmd
+        .command("create <name>")
+        .description("Create a new empty context")
+        .option("--base-url <url>", "Base URL for the new context", DEFAULT_BASE_URL)
+        .action((name, opts, command) => {
+        try {
+            validateContextName(name);
+            if (getAllContexts()[name]) {
+                throw new Error(`Context "${name}" already exists.`);
+            }
+            setContext(name, { apiKey: "", baseUrl: opts.baseUrl });
+            if (isJsonOutput(command)) {
+                printJson({ success: true, name, baseUrl: opts.baseUrl });
+            }
+            else {
+                printSuccess(`Created context "${name}". Run "iot auth login" to set its API key, or "iot context use ${name}".`, "stderr");
+            }
+        }
+        catch (err) {
+            handleError(err, { json: isJsonOutput(command) });
+        }
+    });
+    cmd
+        .command("rename <old> <new>")
+        .description("Rename a context")
+        .action((oldName, newName, _opts, command) => {
+        try {
+            renameContext(oldName, newName);
+            if (isJsonOutput(command)) {
+                printJson({ success: true, from: oldName, to: newName });
+            }
+            else {
+                printSuccess(`Renamed "${oldName}" to "${newName}".`, "stderr");
+            }
+        }
+        catch (err) {
+            handleError(err, { json: isJsonOutput(command) });
+        }
+    });
+    cmd
+        .command("delete <name>")
+        .description("Delete a context (refuses if it's the only one)")
+        .action((name, _opts, command) => {
+        try {
+            const wasActive = getActiveContextName() === name;
+            deleteContext(name);
+            if (isJsonOutput(command)) {
+                printJson({ success: true, deleted: name, wasActive });
+            }
+            else {
+                if (wasActive) {
+                    process.stderr.write(`Deleted active context "${name}". Switched to "${getActiveContextName()}".\n`);
+                }
+                else {
+                    printSuccess(`Deleted context "${name}".`, "stderr");
+                }
+            }
+        }
+        catch (err) {
+            handleError(err, { json: isJsonOutput(command) });
+        }
+    });
+    cmd
+        .command("current")
+        .description("Print the active context name (script-friendly)")
+        .action((_opts, command) => {
+        try {
+            const name = getActiveContextName();
+            if (isJsonOutput(command)) {
+                printJson({ currentContext: name });
+            }
+            else {
+                process.stdout.write(name + "\n");
+            }
+        }
+        catch (err) {
+            handleError(err, { json: isJsonOutput(command) });
+        }
+    });
+    return cmd;
+}
+//# sourceMappingURL=context.js.map

package/dist/commands/docs.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function makeDocsCommand(): Command;
+//# sourceMappingURL=docs.d.ts.map