@tdk-landscape/tdk-cli-core 1.3.121 → 1.3.123

package/CHANGELOG.md

@@ -4,6 +4,7 @@ Notable changes to the `tdk` CLI. Versions match [npm](https://www.npmjs.com/pac
 
 ## Unreleased
 
+- `tdk stack` can assign named resources in scripts with `--resources` (space- or comma-separated) and skip confirmation with `--yes`. Unknown names list valid resources, and non-TTY assignments without explicit resource names fail with a command hint. Invalid JSON encountered while writing now names the affected `service.json`.
 - `tdk eject` no longer claims files it does not create or prints a command that cannot work. It still writes only `EJECTED.md` (no file is copied, moved or generated; the Tiltfile and engine stay in git-ignored `.tdk/.tdk-out/`, and the per-service Compose files, golden-layer Dockerfile and Traefik file only exist after Tilt has run). `EJECTED.md` no longer lists them under "Keep" and says the Tiltfile still reads `.tdk/project.json` and the `service.json` files. `Next: tilt up` (which finds no Tiltfile at the project root) is replaced by `tilt up -f .tdk/.tdk-out/Tiltfile -- --focus=<stack>`, the form `tdk up` runs. A project that already has an `EJECTED.md` keeps its old text (the file is never overwritten) and is now told so. `--dry-run` headings read `Generated files, left where they are (git-ignored):` and `Files written:`. A command that exports plain Compose files and Dockerfiles does not exist. Fixes #610.
 - `tdk config regenerate` now restores a root `.tiltignore` that TDK wrote (it carries the `SYSTEM-GENERATED BY TDK CLI` header) and that was edited by hand, and prints `Restored: .tiltignore → project root (hand edits discarded)`. Before, it only copied the file when none existed, so `tdk config verify` kept failing with `Out of sync: .tiltignore (run 'tdk config regenerate')` after the advice was followed. A root `.tiltignore` without the header is still never overwritten, and plain `tdk project --yes` still does not overwrite an existing one. Docs: `docs/adopt-tdk.md` now quotes the current `tdk doctor` unknown-field wording.
 - `tdk doctor` now checks the project's own resource configs for duplicates. Two resources with the same `appName` fail (`Duplicate resource names`, naming both `service.json` paths): the name becomes the Compose service and Traefik router, so they collide, and before nothing reported it. Two backend, mcp or routed bring-your-own resources on the same `port` give a warning, not a failure (`Duplicate resource ports`): service ports are not published on the host and each service has its own container, so the pair can run, but it is usually a copied `service.json`. Frontends, workers, libraries and a missing `port` are ignored. Fixes #76.

package/README.md

@@ -13,7 +13,7 @@
 
 English | [简体中文](README-zh_cn.md) | [繁體中文](README-zh_tw.md) | [日本語](README-ja.md) | [한국어](README-ko.md)
 
-TDK CLI starts your services on your laptop. It is not a deploy and not a Compose file: define each service in `service.json`, then run `tdk up`. No Kubernetes is needed on the machine.
+TDK CLI — start services on your laptop. It is not a deploy and not a Compose file: define each service in `service.json`, then run `tdk up`. No Kubernetes is needed on the machine.
 
 Stability: 1.x local dev. Write `service.json`; TDK generates the local runtime files. See [what TDK writes](docs/generated-files.md) and how to check for drift. Core CLI is MIT and needs no key. Premium is optional.
 
@@ -32,9 +32,11 @@ mkdir shop && cd shop
 tdk project --yes
 tdk resource orders-api --type backend --stack shop --yes
 tdk up shop
-curl http://api.shop.localhost/api/orders-api/health
+curl http://api.shop.localhost:8080/api/orders/health
 ```
 
+`tdk up` prints the host ports it chose. Port 8080 is the default; if it was taken, use the HTTP port `tdk up` reports (or set `TDK_HTTP_PORT`). A resource named `orders-api` is served at `/api/orders` (a trailing `-api` is dropped); `tdk up` prints the exact URLs.
+
 ![TDK scaffolding a backend and a frontend, then listing the stack](docs/assets/demo.svg)
 
 *Scaffolding a backend and frontend, then listing the stack.*
@@ -63,6 +65,13 @@ If Helm, Compose, or your existing Tilt setup already gives you a working local
 
 See [how TDK CLI works alongside Helm](https://tdk-landscape.github.io/tdk-website/docs/with-helm/), the [service schema](engine/schemas/service-schema.json), and the [project configuration schema](engine/schemas/project-schema.json).
 
+## Terminal UI
+
+Use `tdk ui` to inspect stacks and resources. Arrow keys or `j`/`k` move the
+selection; `g`/`G` or Home/End jump to the first/last item, and PageUp/PageDown
+move one visible page. `/` searches; navigation letters remain search text
+while searching. The selected row stays visible when the terminal is resized.
+
 ## Installation
 
 Install the CLI from npm (requires Node.js 22.12+) or use the prebuilt binary (no Node.js or Bun required):
@@ -83,6 +92,7 @@ curl -fsSL https://tdk-landscape.github.io/install.sh | sh
 
 ## Docs
 
+- [CLI command cheat sheet](cli/README.md#cheat-sheet)
 - [Documentation index](docs/README.md)
 - [Pilot TDK on a real repository](docs/adopt-tdk.md)
 - [FAQ for agencies and multi-client teams](docs/faq-teams.md)
@@ -121,7 +131,7 @@ published on 21 September 2026. Those dates describe the current repository and
 
 ## Requirements and support
 
-For the local runtime, install Docker (Desktop, OrbStack, or Colima; Engine 25+, Compose 2.20+) and [Tilt](https://docs.tilt.dev/install.html). Bun 1.2+ is used by the default generated services. TDK selects host ports from bounded fallback ranges for HTTP, HTTPS, and Postgres; set `TDK_HTTP_PORT`, `TDK_HTTPS_PORT`, or `TDK_POSTGRES_PORT` to override them. TDK supports macOS, Linux, and Windows through WSL2 Ubuntu; native Windows supports CLI inspection only. Run `tdk doctor` to check local readiness (supports `--no-ping` to skip service health checks and `--ping-timeout <ms>`). See [WSL2 setup](docs/wsl2.md).
+For the local runtime, install Docker (Desktop, OrbStack, or Colima; Engine 25+, Compose 2.20.2+) and [Tilt](https://docs.tilt.dev/install.html). Bun 1.2+ is used by the default generated services. TDK selects host ports from bounded fallback ranges for HTTP, HTTPS, and Postgres; set `TDK_HTTP_PORT`, `TDK_HTTPS_PORT`, or `TDK_POSTGRES_PORT` to override them. Dev ports listen on `127.0.0.1` only, so other machines on your network cannot reach them. Set `TDK_BIND_ADDRESS` (for example `0.0.0.0`, to test from a phone) to change that; `tdk doctor` warns when it is a wildcard address. TDK supports macOS, Linux, and Windows through WSL2 Ubuntu; native Windows supports CLI inspection only. Run `tdk doctor` to check local readiness (supports `--no-ping` to skip service health checks and `--ping-timeout <ms>`). See [WSL2 setup](docs/wsl2.md).
 
 On native Windows, `tdk --version`, `tdk doctor`, and `tdk up --dry-run` are inspect-only commands. `tdk up` exits 2 with “Landscape startup needs Ubuntu on WSL2. Native Windows is inspect-only.”
 
@@ -144,8 +154,3 @@ Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and the
 TDK is MIT-licensed; see [LICENSE](LICENSE). The [license boundary](GOVERNANCE.md#license-boundary-and-donation-scope) says which code is MIT and which is downloaded with a key.
 
 Project governance: [GOVERNANCE.md](GOVERNANCE.md), [MAINTAINERS.md](MAINTAINERS.md), [ADOPTERS.md](ADOPTERS.md).
-
-Use `tdk ui` to inspect stacks and resources. Arrow keys or `j`/`k` move the
-selection; `g`/`G` or Home/End jump to the first/last item, and PageUp/PageDown
-move one visible page. `/` searches; navigation letters remain search text
-while searching. The selected row stays visible when the terminal is resized.

package/cli/dist/cli.js

@@ -30,7 +30,7 @@ import { unknownHelpTarget } from "./utils/help-command.js";
 const program = new Command();
 program
     .name("tdk")
-    .description("Tilt Development Kit - Project/Stack/Resource management")
+    .description("TDK CLI — start services on your laptop.")
     .version(pkg.version, "-v, --version", "Display version number")
     .option("--verbose", "Enable verbose output", false)
     .configureOutput({

package/cli/dist/commands/doctor.js

@@ -9,7 +9,7 @@ import { MASTER_CONFIG_FILES, REQUIRED_PACKAGE_SCRIPTS } from "../utils/constant
 import { isPathDiscovered, readDiscoveryPaths } from "../utils/discovery-paths.js";
 import { collectDoctorChecks, createDoctorReport, getDoctorExitCode, } from "../utils/doctor-report.js";
 import { checkHealthRoutes, checkIngressPorts, checkPrivateNpmRegistry, checkTiltResourceHealth, projectConfigEnablesVerdaccio, summarizeServiceProbes, } from "../utils/doctor-runtime.js";
-import { checkDockerNetworkCapacity, checkDuplicateResourceNames, checkDuplicateResourcePorts, checkFrontendBackendUrls, checkMigrationsInApi, checkNatsBroker, checkPrismaConsistency, checkResourcePackageJson, checkServiceUrlPorts, checkSharedPlatformPostgres, checkTiltInstances, } from "../utils/doctor-wiring.js";
+import { checkDockerNetworkCapacity, checkDuplicateResourceNames, checkDuplicateResourcePorts, checkFrontendBackendUrls, checkMigrationsInApi, checkNatsBroker, checkPrismaConsistency, checkResourcePackageJson, checkServiceUrlPorts, checkSharedPlatformPostgres, checkSharedStackRoutes, checkTiltInstances, } from "../utils/doctor-wiring.js";
 import { validateEnvFile } from "../utils/env-validator.js";
 import { execAsync, isExecTimeout } from "../utils/exec-async.js";
 import { formatCount } from "../utils/formatting.js";
@@ -17,6 +17,8 @@ import { getHostPortPlan } from "../utils/host-port-config.js";
 import { createHostPortPlan } from "../utils/host-port-plan.js";
 import { findProjectRoot, getPackageVersion } from "../utils/paths.js";
 import { isApiServiceType } from "../utils/resource-kind.js";
+import { EnvUnreadableError, envSecretValues, redactSecrets, redactValue, } from "../utils/secret-redaction.js";
+import { checkCircularDependencies, checkDependsOnShape, checkSchemaVersions, checkServicePorts, } from "../utils/service-config-checks.js";
 import { buildHealthTargets, pingHealthTargets } from "../utils/service-urls.js";
 import { discoverResourcesFromRoot } from "../utils/services.js";
 import { evaluateTdkVersionFloor } from "../utils/tdk-version.js";
@@ -70,6 +72,40 @@ export function checkWslProjectLocation(projectPath, strict, isWsl = process.pla
         fix: "Move the repository under your WSL home directory (for example, ~/projects) and retry tdk doctor.",
     };
 }
+/** True for IPv4 0.0.0.0 and any IPv6 unspecified form (::, 0:0::0, [::], ...). */
+function isWildcardBindAddress(value) {
+    const host = value.replace(/^\[(.*)\]$/, "$1");
+    if (host === "0.0.0.0")
+        return true;
+    // IPv4-embedded unspecified address, e.g. ::0.0.0.0
+    if (/^[0:]*:0\.0\.0\.0$/.test(host))
+        return true;
+    return host.includes(":") && /^[0:]+$/.test(host);
+}
+/**
+ * Dev ports (Traefik, Postgres) bind to 127.0.0.1 by default. TDK_BIND_ADDRESS
+ * opts in to another address; a wildcard exposes them to every machine on the
+ * network (GHSA-3hj3-f39v-j2x5).
+ */
+export function checkPublishedBindAddress(env = process.env, strict = false) {
+    const bindAddress = (env.TDK_BIND_ADDRESS ?? "").trim();
+    if (!isWildcardBindAddress(bindAddress)) {
+        return {
+            name: "Dev Port Bind Address",
+            didPass: true,
+            message: bindAddress
+                ? `Dev ports bind to ${bindAddress}`
+                : "Dev ports bind to 127.0.0.1 (this machine only)",
+        };
+    }
+    return {
+        name: "Dev Port Bind Address",
+        didPass: !strict,
+        isWarning: !strict,
+        message: `TDK_BIND_ADDRESS is ${bindAddress}: Traefik and Postgres are reachable from other machines on the network.`,
+        fix: "Unset TDK_BIND_ADDRESS to keep dev ports on 127.0.0.1. Keep it only when you test from another device on purpose.",
+    };
+}
 /** Failures are shown before passing statuses, with a 5432 conflict first. */
 export function orderDoctorResults(results) {
     const failures = results.filter((result) => !result.didPass && !result.isSkipped && !result.isWarning);
@@ -286,8 +322,8 @@ export async function checkTilt(exec = execAsync) {
         return {
             name: "Tilt CLI",
             didPass: false,
-            message: `Tilt ${raw || "version unknown"} is below the required v0.25.0 floor`,
-            fix: "Install Tilt v0.25.0 or newer: https://docs.tilt.dev/install.html",
+            message: `Tilt ${raw || "version unknown"} is below the required v${MIN_TILT_VERSION.join(".")} floor`,
+            fix: `Install Tilt v${MIN_TILT_VERSION.join(".")} or newer: https://docs.tilt.dev/install.html`,
         };
     }
     return { name: "Tilt CLI", didPass: true, message: `Tilt ${raw} is available` };
@@ -345,8 +381,8 @@ export async function checkBun(exec = execAsync) {
             return {
                 name: "Bun",
                 didPass: false,
-                message: `Bun ${rawVersion || "version unknown"} is below the required 1.2.0 floor`,
-                fix: "Install Bun 1.2.0 or newer: https://bun.sh/install",
+                message: `Bun ${rawVersion || "version unknown"} is below the required ${MIN_BUN_VERSION.join(".")} floor`,
+                fix: `Install Bun ${MIN_BUN_VERSION.join(".")} or newer: https://bun.sh/install`,
             };
         }
         return {
@@ -1122,6 +1158,7 @@ export const doctorCommand = new Command("doctor")
         checkDockerVersions,
         checkBun,
         () => checkWslProjectLocation(findProjectRoot() ?? process.cwd(), options.strict),
+        () => checkPublishedBindAddress(process.env, options.strict),
         // Each project needs several networks; a full address pool fails `tdk up` late.
         () => checkDockerNetworkCapacity(),
     ];
@@ -1139,9 +1176,14 @@ export const doctorCommand = new Command("doctor")
         // Wiring mistakes that otherwise surface minutes into `tdk up`.
         () => checkResourcePackageJson(),
         () => checkDuplicateResourceNames(),
+        () => checkDependsOnShape(),
+        () => checkCircularDependencies(),
+        () => checkServicePorts(),
+        () => checkSchemaVersions(undefined, options.strict),
         () => checkDuplicateResourcePorts(),
         () => checkServiceUrlPorts(),
         () => checkFrontendBackendUrls(),
+        () => checkSharedStackRoutes(),
         () => checkNatsBroker(),
         () => checkPrismaConsistency(),
         // Shared platform Postgres: will-start report + unknown dependsOn names stay errors.
@@ -1182,9 +1224,24 @@ export const doctorCommand = new Command("doctor")
     const exitCode = getDoctorExitCode(report);
     const allPassed = report.data.ready;
     if (options.json) {
-        console.log(JSON.stringify(report));
-        for (const error of errors)
+        let secrets;
+        try {
+            secrets = envSecretValues(findProjectRoot() ?? process.cwd());
+        }
+        catch (error) {
+            if (!(error instanceof EnvUnreadableError))
+                throw error;
+            // Without the values the report cannot be published safely, so it is replaced by a structured error.
+            console.log(JSON.stringify(createDoctorReport([], inProject, [
+                ...errors,
+                { code: "ENV_UNREADABLE", message: error.message },
+            ])));
             console.error(error.message);
+            process.exit(1);
+        }
+        console.log(JSON.stringify(redactValue(report, secrets)));
+        for (const error of errors)
+            console.error(redactSecrets(error.message, secrets));
         if (exitCode !== 0)
             process.exit(exitCode);
         return;

package/cli/dist/commands/help.js

@@ -1,7 +1,7 @@
 import chalk from "chalk";
 import pkg from "../../package.json" with { type: "json" };
 const TDK_BANNER = `
-  ${chalk.bold.cyan("tdk")} ${chalk.gray(`v${pkg.version}`)}  ${chalk.white("TDK runs many services locally with Docker + Tilt; Helm deploys the cluster")}
+  ${chalk.bold.cyan("tdk")} ${chalk.gray(`v${pkg.version}`)}  ${chalk.white("TDK CLI — start services on your laptop.")}
 `;
 const COMMAND_GROUPS = [
     {
@@ -14,6 +14,16 @@ const COMMAND_GROUPS = [
                 alias: "",
             },
             { name: "projects, info", desc: "Show project information and config status", alias: "" },
+            {
+                name: "import",
+                desc: "Import the services a directory describes",
+                alias: "[dir] --dry-run --yes",
+            },
+            {
+                name: "eject",
+                desc: "Write EJECTED.md describing the generated Tilt files",
+                alias: "--dry-run --yes",
+            },
         ],
     },
     {
@@ -39,6 +49,7 @@ const COMMAND_GROUPS = [
             { name: "up, deploy", desc: "Start services (optionally by stack)", alias: "[stack-name]" },
             { name: "down", desc: "Stop all tilt resources", alias: "" },
             { name: "status", desc: "Show status of services and stacks", alias: "" },
+            { name: "logs", desc: "Print recent logs from the running stack", alias: "--json" },
         ],
     },
     {
@@ -63,6 +74,7 @@ const COMMAND_GROUPS = [
                 alias: "regenerate, verify, edit",
             },
             { name: "doctor", desc: "Check environment readiness", alias: "" },
+            { name: "mcp", desc: "Run an MCP server over stdio for coding agents", alias: "" },
             {
                 name: "runtime",
                 desc: "Inspect packaged engine and template assets",
@@ -75,6 +87,10 @@ const COMMAND_GROUPS = [
         ],
     },
 ];
+/** Every command name and alias that the help table lists. */
+export function listedCommandNames() {
+    return COMMAND_GROUPS.flatMap((group) => group.commands.flatMap((command) => command.name.split(",").map((name) => name.trim())));
+}
 function formatCommand(name, desc, alias, color) {
     const nameFormatted = color(name.padEnd(20));
     const descFormatted = chalk.white(desc);

package/cli/dist/commands/logs.js

@@ -2,8 +2,11 @@ import { Command } from "commander";
 import { STANDARD_PORTS } from "../utils/constants.js";
 import { errorFactories, runCommand, showErrorAndExit, TdkError } from "../utils/errors.js";
 import { createMachineEnvelope } from "../utils/machine-output.js";
+import { findProjectRoot } from "../utils/paths.js";
+import { EnvUnreadableError, envSecretValues, redactSecrets, redactValue, } from "../utils/secret-redaction.js";
 import { isTiltAvailable, runTilt } from "../utils/tilt.js";
 import { DEFAULT_LOG_TAIL, isTiltConnectionFailure, isValidPort, isValidSince, isValidTail, MAX_LOG_TAIL, parseTiltLogLines, } from "../utils/tilt-logs.js";
+import { tiltUnreachableMessage } from "../utils/tilt-unreachable-message.js";
 /** Resource names Tilt knows about, or null when they cannot be listed (the logs call then reports the real error). */
 async function tiltResourceNames(port) {
     try {
@@ -28,16 +31,24 @@ export const logsCommand = new Command("logs")
     .option("--port <n>", "Tilt UI port (default: TILT_PORT or 10350)")
     .option("--json", "Output one JSON object and exit", false)
     .action(async (options) => {
-    const fail = (code, message, exitCode = 1, suggestions = []) => {
+    let secrets = [];
+    const fail = (code, rawMessage, exitCode = 1, suggestions = []) => {
+        const message = redactSecrets(rawMessage, secrets);
+        const redactedSuggestions = redactValue(suggestions, secrets);
         if (options.json) {
             console.log(JSON.stringify(createMachineEnvelope(null, [
-                { code, message, ...(suggestions.length > 0 ? { suggestions } : {}) },
+                {
+                    code,
+                    message,
+                    ...(redactedSuggestions.length > 0 ? { suggestions: redactedSuggestions } : {}),
+                },
             ])));
             console.error(message);
             process.exit(exitCode);
         }
-        if (suggestions.length > 0)
-            return new TdkError(message, suggestions, exitCode).exit();
+        if (redactedSuggestions.length > 0) {
+            return new TdkError(message, redactedSuggestions, exitCode).exit();
+        }
         return showErrorAndExit(message, exitCode);
     };
     if (!isValidTail(options.tail))
@@ -50,6 +61,16 @@ export const logsCommand = new Command("logs")
         fail("USAGE", "--port must be a valid port number", 2);
     const tail = Number(options.tail);
     const services = options.service ?? [];
+    try {
+        secrets = envSecretValues(findProjectRoot() ?? process.cwd());
+    }
+    catch (error) {
+        if (!(error instanceof EnvUnreadableError))
+            throw error;
+        fail("ENV_UNREADABLE", error.message, 1, [
+            "Fix the read permission on .env, or move it out of the project",
+        ]);
+    }
     const action = async () => {
         if (!(await isTiltAvailable())) {
             fail("TILT_MISSING", "Tilt is not installed. Run: tdk doctor");
@@ -75,16 +96,16 @@ export const logsCommand = new Command("logs")
         if (result.exitCode !== 0) {
             const detail = result.stderr.trim();
             if (!detail || isTiltConnectionFailure(detail)) {
-                fail("TILT_NOT_RUNNING", `Could not reach Tilt on port ${portText}: ${detail || "is the stack running? Start it with: tdk up"}`);
+                fail("TILT_NOT_RUNNING", tiltUnreachableMessage(portText));
             }
             fail("TILT_LOGS_FAILED", `tilt logs failed: ${detail}`);
         }
         if (!options.json) {
-            process.stdout.write(result.stdout);
+            process.stdout.write(redactSecrets(result.stdout, secrets));
             return;
         }
         const lines = parseTiltLogLines(result.stdout, tail);
-        console.log(JSON.stringify(createMachineEnvelope({ services, tail, since: options.since ?? null, lines })));
+        console.log(JSON.stringify(redactValue(createMachineEnvelope({ services, tail, since: options.since ?? null, lines }), secrets)));
     };
     await runCommand(action);
 });

package/cli/dist/commands/stack.js

@@ -3,21 +3,39 @@ import chalk from "chalk";
 import { Command } from "commander";
 import { assertValid, confirmOrCancel } from "../utils/command-helpers.js";
 import { clearDiscoveryCache, createDiscoveryContext } from "../utils/discovery-context.js";
-import { requireProjectRoot, runCommand } from "../utils/errors.js";
+import { errorFactories, requireProjectRoot, runCommand, TdkError } from "../utils/errors.js";
 import { writeJsonFile } from "../utils/file-helpers.js";
 import { formatCount, showAllSatisfyCondition, showCommandHeader, showDetail, showSuccess, } from "../utils/formatting.js";
 import { promptMultiSelect, promptText } from "../utils/prompt.js";
 import { createKebabCaseValidator, validateStackName } from "../utils/validation.js";
+export function parseStackResourceConfig(content, configPath) {
+    try {
+        return JSON.parse(content);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new TdkError(`Could not parse service.json at ${configPath}: ${reason}`);
+    }
+}
+function normalizeResourceNames(names) {
+    const normalizedNames = names.flatMap((name) => name
+        .split(",")
+        .map((part) => part.trim())
+        .filter(Boolean));
+    return [...new Set(normalizedNames)];
+}
 export const stackCommand = new Command("stack")
     .description("Organize resources into stacks (groups)")
     .argument("[stack-name]", "Stack name to assign to resources")
     .option("--list", "List resources without a stack", false)
+    .option("--resources <names...>", "Resource names to add (comma- or space-separated)")
+    .option("--yes", "Skip confirmation prompt", false)
     .action(async (stackName, options) => {
     await runCommand(async () => {
         requireProjectRoot();
         showCommandHeader("Stack Management");
         const discovery = createDiscoveryContext();
-        if (discovery.resources.length === 0) {
+        if (discovery.resources.length === 0 && options.resources === undefined) {
             console.log(chalk.yellow("No resources discovered. Make sure you're in a project with service.json files."));
             return;
         }
@@ -42,6 +60,24 @@ export const stackCommand = new Command("stack")
             }
             return;
         }
+        if (!process.stdin.isTTY) {
+            if (options.resources === undefined) {
+                throw new TdkError("Interactive resource selection requires a TTY.", [
+                    "Pass --resources <name...> to select resources without a prompt.",
+                    "Use --list to inspect unassigned resources without changing them.",
+                ]);
+            }
+            if (!stackName) {
+                throw new TdkError("A stack name is required when stdin is not a TTY.", [
+                    "Use: tdk stack <stack-name> --resources <name...> [--yes]",
+                ]);
+            }
+            if (!options.yes) {
+                throw new TdkError("Confirmation requires a TTY.", [
+                    "Pass --yes to skip confirmation when assigning resources without a TTY.",
+                ]);
+            }
+        }
         if (stackName)
             assertValid(validateStackName(stackName));
         let targetStack = stackName;
@@ -56,28 +92,64 @@ export const stackCommand = new Command("stack")
             targetStack = name;
         }
         const resourcesToUpdate = discovery.unassignedResources;
-        if (resourcesToUpdate.length === 0) {
-            console.log(chalk.yellow("\nNo resources available to add to this stack."));
-            return;
+        const selectedResources = [];
+        if (options.resources !== undefined) {
+            const requestedNames = normalizeResourceNames(options.resources);
+            if (requestedNames.length === 0) {
+                throw new TdkError("Pass at least one resource name to --resources.", [
+                    "Example: `tdk stack api --resources users-api orders-api --yes`",
+                ]);
+            }
+            const configPathsByName = new Map();
+            for (const resource of discovery.resources) {
+                const configPaths = configPathsByName.get(resource.name) ?? [];
+                configPaths.push(resource.configPath);
+                configPathsByName.set(resource.name, configPaths);
+            }
+            const duplicates = [...configPathsByName].filter(([, configPaths]) => configPaths.length > 1);
+            if (duplicates.length > 0) {
+                throw new TdkError("Cannot assign resources while duplicate names are present.", duplicates.map(([name, configPaths]) => `Duplicate "${name}" found in ${configPaths.join(" and ")}`));
+            }
+            const validNames = [...configPathsByName.keys()].sort();
+            const resourceByName = new Map(discovery.resources.map((resource) => [resource.name, resource]));
+            for (const name of requestedNames) {
+                const resource = resourceByName.get(name);
+                if (!resource) {
+                    const error = errorFactories.resourceNotFound(name, validNames);
+                    error.suggestions.unshift(`Valid resources: ${validNames.join(", ")}`);
+                    throw error;
+                }
+                if (resource.stack) {
+                    throw new TdkError(`Resource "${name}" is already assigned to stack "${resource.stack}".`, ["Run `tdk resources` to review current assignments."]);
+                }
+                selectedResources.push(resource.configPath);
+            }
         }
-        const selectedResources = await promptMultiSelect({
-            message: `Select resources to add to stack "${targetStack}":`,
-            choices: resourcesToUpdate.map((r) => ({
-                title: r.name,
-                value: r.configPath,
-            })),
-            validate: (input) => {
-                if (input.length === 0)
-                    return "Select at least one resource";
-                return true;
-            },
-        });
-        if (selectedResources.length === 0) {
-            console.log(chalk.yellow("No resources selected. Exiting."));
-            return;
+        else {
+            if (resourcesToUpdate.length === 0) {
+                console.log(chalk.yellow("\nNo resources available to add to this stack."));
+                return;
+            }
+            const promptedResources = await promptMultiSelect({
+                message: `Select resources to add to stack "${targetStack}":`,
+                choices: resourcesToUpdate.map((resource) => ({
+                    title: resource.name,
+                    value: resource.configPath,
+                })),
+                validate: (input) => {
+                    if (input.length === 0)
+                        return "Select at least one resource";
+                    return true;
+                },
+            });
+            if (promptedResources.length === 0) {
+                console.log(chalk.yellow("No resources selected. Exiting."));
+                return;
+            }
+            selectedResources.push(...promptedResources);
         }
         showDetail(`\nWill add "stack": "${targetStack}" to ${formatCount(selectedResources.length, "resource")}.`, 0);
-        const confirmed = await confirmOrCancel("Proceed?");
+        const confirmed = options.yes || (await confirmOrCancel("Proceed?"));
         if (!confirmed)
             return;
         // Clear cache since we're about to modify resources
@@ -85,7 +157,7 @@ export const stackCommand = new Command("stack")
         let updated = 0;
         for (const configPath of selectedResources) {
             const content = readFileSync(configPath, "utf-8");
-            const config = JSON.parse(content);
+            const config = parseStackResourceConfig(content, configPath);
             config.stack = targetStack;
             writeJsonFile(configPath, config);
             updated++;