@langchain/langgraph-cli 1.5.1-rc.0 → 1.5.2-dev.0

package/dist/cli/build.mjs

@@ -1,6 +1,5 @@
 import { getDockerCapabilities } from "../docker/compose.mjs";
 import { assembleLocalDeps, configToDocker, getBaseImage, } from "../docker/docker.mjs";
-import { getExecaOptions } from "../docker/shell.mjs";
 import { getConfig } from "../utils/config.mjs";
 import { builder } from "./utils/builder.mjs";
 import { getProjectPath } from "./utils/project.mjs";
@@ -33,11 +32,11 @@ builder
     await getDockerCapabilities();
     const projectDir = path.dirname(configPath);
     const config = getConfig(await fs.readFile(configPath, "utf-8"));
-    const opts = await getExecaOptions({
+    const opts = {
         cwd: projectDir,
         stderr: "inherit",
         stdout: "inherit",
-    });
+    };
     const localDeps = await assembleLocalDeps(configPath, config);
     const input = await configToDocker(configPath, config, localDeps, {
         watch: false,

package/dist/cli/deploy.mjs

@@ -18,7 +18,7 @@ import { withAnalytics } from "./utils/analytics.mjs";
 import { getProjectPath } from "./utils/project.mjs";
 import { getConfig } from "../utils/config.mjs";
 import { assembleLocalDeps, configToDocker, getBaseImage, } from "../docker/docker.mjs";
-import { getExecaOptions } from "../docker/shell.mjs";
+import { DOCKER_NOT_INSTALLED, DOCKER_NOT_RUNNING, isBinaryNotFound, } from "../docker/errors.mjs";
 import { HostBackendClient, HostBackendError, } from "./utils/host-backend.mjs";
 import { Emitter, Spinner } from "./utils/deploy-output.mjs";
 import { createArchive, BYTES_PER_MIB } from "./utils/archive.mjs";
@@ -276,23 +276,18 @@ async function callWithOptionalTenant(client, operation) {
 // ---------------------------------------------------------------------------
 // Build mode resolution
 // ---------------------------------------------------------------------------
-const DOCKER_NOT_INSTALLED = "Docker is required but not installed.\n" +
-    "Install Docker Desktop: https://docs.docker.com/get-docker/";
-const DOCKER_NOT_RUNNING = "Docker is installed but not running.\nStart Docker and try again.";
 async function canBuildLocally() {
-    let opts;
-    try {
-        opts = await getExecaOptions({ reject: false });
-    }
-    catch {
-        return [false, DOCKER_NOT_INSTALLED];
-    }
+    const opts = { reject: false };
     try {
         const info = await $(opts) `docker info`;
+        if (isBinaryNotFound(info))
+            return [false, DOCKER_NOT_INSTALLED];
         if (info.exitCode !== 0)
             return [false, DOCKER_NOT_RUNNING];
     }
-    catch {
+    catch (error) {
+        if (isBinaryNotFound(error))
+            return [false, DOCKER_NOT_INSTALLED];
         return [false, DOCKER_NOT_RUNNING];
     }
     if (os.arch() !== "x64") {
@@ -331,15 +326,21 @@ async function resolveBuildMode(remoteBuildFlag) {
     }
     return [!supported, localBuildError];
 }
-async function resolveDeployment(client, step, deploymentId, name, notFoundMessage) {
+async function resolveDeployment(client, step, deploymentId, name, notFoundMessage, agent) {
     if (deploymentId) {
         emitter.step(step, `Using deployment ${deploymentId}`);
         await callWithOptionalTenant(client, (c) => c.getDeployment(deploymentId));
         return { deploymentId, needsCreation: false, step: step + 1 };
     }
-    emitter.step(step, `Looking up deployment '${name}'`);
-    const response = await callWithOptionalTenant(client, (c) => c.listDeployments(name));
-    const foundId = findDeploymentIdByName(response, name);
+    emitter.step(step, agent
+        ? `Looking up agent '${agent.agent_id}' in ${agent.environment}`
+        : `Looking up deployment '${name}'`);
+    const response = await callWithOptionalTenant(client, (c) => c.listDeployments(name, agent?.agent_id, agent?.environment));
+    let foundId = findDeploymentIdByName(response, name);
+    if (agent && Array.isArray(response.resources)) {
+        const found = response.resources.find((dep) => rec(dep).id && !rec(dep).is_preview);
+        foundId = found ? String(rec(found).id) : null;
+    }
     if (foundId) {
         emitter.info(`Found existing deployment (ID: ${foundId})`);
         return { deploymentId: foundId, needsCreation: false, step: step + 1 };
@@ -348,17 +349,28 @@ async function resolveDeployment(client, step, deploymentId, name, notFoundMessa
     return { deploymentId: undefined, needsCreation: true, step: step + 1 };
 }
 async function createDeployment(client, step, args) {
-    emitter.step(step, `Creating deployment '${args.name}'`);
-    const created = await client.createDeployment({
-        name: args.name,
-        deploymentType: args.deploymentType,
-        source: args.source,
-        secrets: args.secrets,
-    });
+    emitter.step(step, args.agent
+        ? `Creating deployment for agent '${args.agent.agent_id}' in ${args.agent.environment}`
+        : `Creating deployment '${args.name}'`);
+    let created;
+    try {
+        created = await client.createDeployment(args);
+    }
+    catch (error) {
+        if (args.agent &&
+            error instanceof HostBackendError &&
+            error.statusCode === 409) {
+            throw new HostBackendError("This agent already has a deployment in this environment.", 409);
+        }
+        throw error;
+    }
     const id = typeof created.id === "string" ? created.id : undefined;
     if (!id) {
         throw new HostBackendError("POST /v2/deployments succeeded but response missing a valid 'id'");
     }
+    if (args.agent && created.name) {
+        emitter.info(`Deployment name: ${created.name}`);
+    }
     emitter.info(`Deployment ID: ${id}`, { deployment_id: id });
     return { id, step: step + 1 };
 }
@@ -583,7 +595,7 @@ async function runLocalBuild(args) {
     const dockerfile = generatedDockerfile.replace(/^FROM .*$/m, `FROM ${baseImageRef}`);
     const needsBuildx = os.arch() !== "x64";
     const localTag = `langgraph-deploy-tmp:${Math.floor(Date.now() / 1000)}`;
-    const baseOpts = await getExecaOptions({ cwd: projectDir });
+    const baseOpts = { cwd: projectDir };
     const stdio = args.verbose
         ? { stdout: "inherit", stderr: "inherit" }
         : { stdout: "ignore", stderr: "ignore" };
@@ -807,12 +819,42 @@ async function runRemoteBuild(args) {
         await archive.cleanup();
     }
 }
+// ---------------------------------------------------------------------------
+// Main deploy orchestration
+// ---------------------------------------------------------------------------
+function resolveAgentOptions(opts) {
+    const agentId = opts.agentId ?? (process.env.LANGSMITH_AGENT_ID || undefined);
+    const agentEnvironment = opts.agentEnvironment ??
+        (process.env.LANGSMITH_AGENT_ENVIRONMENT || undefined);
+    if (agentId !== undefined || agentEnvironment !== undefined) {
+        emitter.note("Note: --agent-id and --agent-environment flags are in private beta");
+    }
+    if (agentId !== undefined && !agentId.trim()) {
+        throw new Error("--agent-id must not be empty.");
+    }
+    if (agentEnvironment !== undefined &&
+        !["development", "staging", "production"].includes(agentEnvironment)) {
+        throw new Error("--agent-environment must be development, staging, or production.");
+    }
+    return { agentId, agentEnvironment };
+}
 async function runDeploy(dockerBuildArgs, opts, remoteBuildFlag) {
     emitter = new Emitter(opts.json);
     noInput = !opts.input;
     emitter.note("Note: 'langgraphjs deploy' is in beta. Expect frequent updates and improvements.");
     if (!opts.json)
         process.stdout.write("\n");
+    const { agentId, agentEnvironment } = resolveAgentOptions(opts);
+    let agent;
+    if (agentId !== undefined || agentEnvironment !== undefined) {
+        if (!agentId || !agentEnvironment) {
+            throw new Error("--agent-id and --agent-environment are required together.");
+        }
+        if (opts.name !== undefined || opts.deploymentId !== undefined) {
+            throw new Error("--agent-id and --agent-environment cannot be combined with --name or --deployment-id.");
+        }
+        agent = { agent_id: agentId, environment: agentEnvironment };
+    }
     if (!["dev", "prod"].includes(opts.deploymentType)) {
         throw new Error(`Invalid --deployment-type '${opts.deploymentType}' (expected 'dev' or 'prod').`);
     }
@@ -825,16 +867,16 @@ async function runDeploy(dockerBuildArgs, opts, remoteBuildFlag) {
     const envVars = await parseEnvFromConfig(rawConfig, configPath);
     let name = opts.name;
     let deploymentId = opts.deploymentId;
-    if (!deploymentId && !name) {
+    if (!agent && !deploymentId && !name) {
         name = envVars[DEPLOYMENT_NAME_ENV] ?? process.env[DEPLOYMENT_NAME_ENV];
     }
-    if (!deploymentId && !name) {
+    if (!agent && !deploymentId && !name) {
         const defaultName = normalizeName(path.basename(process.cwd()));
         name = noInput
             ? defaultName
             : await promptText("Deployment name", defaultName);
     }
-    if (name && !deploymentId) {
+    if (!agent && name && !deploymentId) {
         name = normalizeName(name);
         if (!noInput) {
             const envPath = await resolveEnvPath(rawConfig, configPath);
@@ -856,12 +898,13 @@ async function runDeploy(dockerBuildArgs, opts, remoteBuildFlag) {
     let step = 1;
     const resolved = await resolveDeployment(client, step, deploymentId, name, useRemoteBuild
         ? "No deployment found. Will create."
-        : "No deployment found. Will create after build.");
+        : "No deployment found. Will create after build.", agent);
     deploymentId = resolved.deploymentId;
     step = resolved.step;
     if (resolved.needsCreation) {
         const created = await createDeployment(client, step, {
-            name: name,
+            name,
+            agent,
             deploymentType: opts.deploymentType,
             source: useRemoteBuild ? "internal_source" : "internal_docker",
             secrets,
@@ -953,8 +996,9 @@ async function runDeploy(dockerBuildArgs, opts, remoteBuildFlag) {
 async function runList(opts) {
     emitter = new Emitter(false);
     noInput = false;
+    const { agentId, agentEnvironment } = resolveAgentOptions(opts);
     const client = await createHostBackendClient(opts.hostUrl, opts.apiKey);
-    const response = await callWithOptionalTenant(client, (c) => c.listDeployments(opts.nameContains));
+    const response = await callWithOptionalTenant(client, (c) => c.listDeployments(opts.nameContains, agentId, agentEnvironment));
     const resources = Array.isArray(rec(response).resources)
         ? rec(response).resources
         : [];
@@ -1112,6 +1156,8 @@ const deploy = builder
     .option("--api-key <key>", "API key (or LANGGRAPH_HOST_API_KEY / LANGSMITH_API_KEY / LANGCHAIN_API_KEY).")
     .option("--name <name>", "Deployment name (or LANGSMITH_DEPLOYMENT_NAME). Defaults to the current directory name.")
     .option("--deployment-id <id>", "ID of an existing deployment to update.")
+    .option("--agent-id <id>", "Agent ID (or LANGSMITH_AGENT_ID).")
+    .option("--agent-environment <environment>", "Agent environment: development, staging, or production (or LANGSMITH_AGENT_ENVIRONMENT).")
     .option("--deployment-type <type>", "Deployment type when creating: 'dev' or 'prod'.", "dev")
     .option("--no-wait", "Skip waiting for deployment status.")
     .option("--verbose", "Show more output from the server logs.", false)
@@ -1146,6 +1192,8 @@ const deploy = builder
 deploy
     .command("list")
     .description("[Beta] List LangSmith Deployments.")
+    .option("--agent-id <id>", "Agent ID (or LANGSMITH_AGENT_ID).")
+    .option("--agent-environment <environment>", "Agent environment: development, staging, or production (or LANGSMITH_AGENT_ENVIRONMENT).")
     .option("--api-key <key>", "API key.")
     .option("--host-url <url>", "Host backend URL.", DEFAULT_HOST_URL)
     .option("--name-contains <value>", "Only show deployments whose names contain this value.", "")

package/dist/cli/dev.mjs

@@ -7,6 +7,7 @@ import open from "open";
 import { startCloudflareTunnel } from "./cloudflare.mjs";
 import { createIpcServer } from "./utils/ipc/server.mjs";
 import { getProjectPath } from "./utils/project.mjs";
+import { DEFAULT_STUDIO_URL, resolveStudioUrl } from "./utils/studio-url.mjs";
 import { getConfig } from "../utils/config.mjs";
 import { builder } from "./utils/builder.mjs";
 import { logError, logger } from "../utils/logging.mjs";
@@ -22,6 +23,7 @@ builder
     .option("-n, --n-jobs-per-worker <number>", "number of workers to run", "10")
     .option("-c, --config <path>", "path to configuration file", process.cwd())
     .option("--tunnel", "use Cloudflare Tunnel to expose the server to the internet")
+    .option("--studio-url <url>", `URL of the LangGraph Studio instance to connect to (defaults to ${DEFAULT_STUDIO_URL})`)
     .allowExcessArguments()
     .allowUnknownOption()
     .exitOverride((error) => gracefulExit(error.exitCode))
@@ -31,6 +33,7 @@ builder
     host: command.opts().host !== "localhost",
     n_jobs_per_worker: command.opts().nJobsPerWorker !== "10",
     tunnel: Boolean(command.opts().tunnel),
+    studio_url: Boolean(command.opts().studioUrl),
 })))
     .action(async (options, { args }) => {
     try {
@@ -46,7 +49,7 @@ builder
         let hasOpenedFlag = false;
         let child = undefined;
         let tunnel = undefined;
-        let hostUrl = "https://smith.langchain.com";
+        let hostUrl = DEFAULT_STUDIO_URL;
         let envNoBrowser = process.env.BROWSER === "none";
         server.on("data", async (data) => {
             const response = z.object({ queryParams: z.string() }).parse(data);
@@ -103,16 +106,13 @@ builder
                 const removedTarget = oldWatch.filter((target) => !newWatch.includes(target));
                 watcher.unwatch(removedTarget).add(addedTarget);
             }
-            try {
+            hostUrl = await resolveStudioUrl(options.studioUrl, async () => {
                 const { Client } = await import("langsmith");
                 const apiUrl = env?.["LANGSMITH_ENDPOINT"] ||
                     env?.["LANGCHAIN_ENDPOINT"] ||
                     undefined;
-                hostUrl = new Client({ apiUrl }).getHostUrl() || hostUrl;
-            }
-            catch {
-                // pass
-            }
+                return new Client({ apiUrl }).getHostUrl();
+            });
             return { config, env, hostUrl };
         };
         const launchServer = async () => {

package/dist/cli/dev.python.mjs

@@ -121,6 +121,7 @@ export async function spawnPythonServer(args, context, options) {
         context.configPath,
         ...(args.browser ? [] : ["--no-browser"]),
         ...(args.reload ? [] : ["--no-reload"]),
+        ...(args.studioUrl ? ["--studio-url", args.studioUrl] : []),
         ...args.rest,
     ], {
         stdio: ["inherit", "inherit", "inherit"],

package/dist/cli/up.mjs

@@ -6,7 +6,6 @@ import { getProjectPath } from "./utils/project.mjs";
 import { logger } from "../utils/logging.mjs";
 import { createCompose, getDockerCapabilities } from "../docker/compose.mjs";
 import { configToCompose, getBaseImage } from "../docker/docker.mjs";
-import { getExecaOptions } from "../docker/shell.mjs";
 import { $ } from "execa";
 import { createHash } from "node:crypto";
 import dedent from "dedent";
@@ -71,11 +70,11 @@ builder
         watch: capabilities.watchAvailable,
     });
     const name = getProjectName(configPath);
-    const execOpts = await getExecaOptions({
+    const execOpts = {
         cwd,
         stdout: "inherit",
         stderr: "inherit",
-    });
+    };
     const exec = $(execOpts);
     if (!config._INTERNAL_docker_tag && params.pull) {
         // pull the image

package/dist/cli/utils/host-backend.mjs

@@ -160,7 +160,7 @@ export class HostBackendClient {
      */
     createDeployment(args) {
         const payload = {
-            name: args.name,
+            ...(args.agent ? { agent: args.agent } : { name: args.name }),
             source: args.source,
             source_config: { deployment_type: args.deploymentType },
             source_revision_config: {},
@@ -179,9 +179,13 @@ export class HostBackendClient {
      * @param nameContains - Optional substring filter on deployment names.
      * @returns A paginated response object with a `resources` array.
      */
-    listDeployments(nameContains = "") {
+    listDeployments(nameContains = "", agentId, agentEnvironment) {
         return this.request("GET", "/v2/deployments", {
-            params: { name_contains: nameContains },
+            params: {
+                name_contains: nameContains,
+                agent_id: agentId,
+                agent_environment: agentEnvironment,
+            },
         });
     }
     /**

package/dist/cli/utils/studio-url.mjs

@@ -0,0 +1,16 @@
+export const DEFAULT_STUDIO_URL = "https://smith.langchain.com";
+/**
+ * Resolves the Studio host the same way as the Python CLI: an explicit
+ * `--studio-url` wins, then the host derived from the LangSmith endpoint,
+ * then the public LangSmith host. `deriveUrl` only runs without a flag.
+ */
+export async function resolveStudioUrl(studioUrl, deriveUrl) {
+    if (studioUrl)
+        return studioUrl;
+    try {
+        return (await deriveUrl()) || DEFAULT_STUDIO_URL;
+    }
+    catch {
+        return DEFAULT_STUDIO_URL;
+    }
+}

package/dist/docker/compose.mjs

@@ -1,7 +1,7 @@
 import { $ } from "execa";
 import * as yaml from "yaml";
 import { z } from "zod/v3";
-import { getExecaOptions } from "./shell.mjs";
+import { DOCKER_NOT_INSTALLED, isBinaryNotFound } from "./errors.mjs";
 export const DEFAULT_POSTGRES_URI = "postgres://postgres:postgres@langgraph-postgres:5432/postgres?sslmode=disable";
 const REDIS = {
     image: "redis:6",
@@ -53,10 +53,12 @@ function compareVersion(a, b) {
 export async function getDockerCapabilities() {
     let rawInfo = null;
     try {
-        const { stdout } = await $(await getExecaOptions()) `docker info -f json`;
+        const { stdout } = await $ `docker info -f json`;
         rawInfo = JSON.parse(stdout);
     }
     catch (error) {
+        if (isBinaryNotFound(error))
+            throw new Error(DOCKER_NOT_INSTALLED);
         throw new Error("Docker not installed or not running: " + error);
     }
     const info = z
@@ -84,7 +86,7 @@ export async function getDockerCapabilities() {
     }
     else {
         try {
-            const standalone = await $(await getExecaOptions()) `docker-compose --version --short`;
+            const standalone = await $ `docker-compose --version --short`;
             composeRes = {
                 composeType: "standalone",
                 versionCompose: parseVersion(standalone.stdout),

package/dist/docker/errors.mjs

@@ -0,0 +1,22 @@
+/**
+ * Shared diagnostics for the Docker CLI invocations made by `build`, `up` and
+ * `deploy`.
+ *
+ * The `docker` binary is resolved from the inherited environment, exactly as
+ * any other command a user runs in their shell. These helpers turn a failed
+ * spawn into the same two-way distinction the Python CLI makes: the binary is
+ * missing, or the daemon is not answering.
+ */
+export const DOCKER_NOT_INSTALLED = "Docker is required but not installed.\n" +
+    "Install Docker Desktop: https://docs.docker.com/get-docker/";
+export const DOCKER_NOT_RUNNING = "Docker is installed but not running.\nStart Docker and try again.";
+/**
+ * Whether a rejected (or `reject: false`) execa call failed because the binary
+ * could not be found on `PATH`, as opposed to running and exiting non-zero.
+ */
+export function isBinaryNotFound(error) {
+    return (typeof error === "object" &&
+        error != null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langchain/langgraph-cli",
-  "version": "1.5.1-rc.0",
+  "version": "1.5.2-dev.0",
   "type": "module",
   "engines": {
     "node": "^18.19.0 || >=20.16.0"
@@ -39,8 +39,8 @@
     "winston-console-format": "^1.0.8",
     "yaml": "^2.8.3",
     "zod": "^3.25.76 || ^4",
-    "create-langgraph": "1.1.5",
-    "@langchain/langgraph-api": "1.5.1-rc.0"
+    "@langchain/langgraph-api": "1.5.2-dev.0",
+    "create-langgraph": "1.1.5"
   },
   "devDependencies": {
     "@types/babel__code-frame": "^7.0.6",

package/dist/docker/shell.mjs

@@ -1,62 +0,0 @@
-import { $ } from "execa";
-import { homedir } from "node:os";
-let PATH = undefined;
-// TODO: macOS related only
-async function getUserShell() {
-    const dscl = await $({
-        shell: true,
-    }) `dscl . -read ~/ UserShell | sed 's/UserShell: //'`;
-    return dscl.stdout.trim();
-}
-async function verifyDockerPath(PATH) {
-    await $({ env: { PATH } }) `which docker`;
-    return PATH;
-}
-// TODO: macOS related only
-async function extractPathFromShell() {
-    const pathToShell = await getUserShell().catch(() => "/bin/zsh");
-    const args = pathToShell.includes("csh")
-        ? ["-c", "echo $PATH"]
-        : ["-lc", "echo $PATH"];
-    const shell = await $(pathToShell, args);
-    return shell.stdout.trim();
-}
-// TODO: macOS related only
-async function guessUserPath() {
-    return [
-        "/bin",
-        "/usr/bin",
-        "/sbin",
-        "/usr/sbin",
-        "/opt/homebrew/bin",
-        "/opt/homebrew/sbin",
-        `${homedir()}/.local/bin`,
-        "/Applications/Docker.app/Contents/Resources/bin",
-        `${homedir()}/.docker/bin`,
-        // support for Rancher Desktop
-        // https://github.com/langchain-ai/langgraph-studio/issues/24#issuecomment-2274046328
-        // https://github.com/langchain-ai/langgraph-studio/issues/122
-        `${homedir()}/.rd/bin`,
-        `/Applications/Rancher Desktop.app/Contents/Resources/resources/darwin/bin`,
-    ].join(":");
-}
-async function getLoginPath() {
-    if (PATH)
-        return { PATH };
-    const [fromShell, fromBackup] = await Promise.allSettled([extractPathFromShell(), guessUserPath()].map((promise) => promise.then(verifyDockerPath)));
-    if (fromShell.status === "fulfilled") {
-        PATH = fromShell.value;
-    }
-    else if (fromBackup.status === "fulfilled") {
-        PATH = fromBackup.value;
-    }
-    else {
-        console.error("Failed to get PATH from shell or backup", fromShell.reason, fromBackup.reason);
-        throw fromShell.reason || fromBackup.reason;
-    }
-    return { PATH };
-}
-export async function getExecaOptions(options) {
-    const env = await getLoginPath();
-    return { ...options, env };
-}