feat(cursor-cli): add Cursor Agent CLI module (interactive default, MCP settings, model/force)

- Runs `cursor-agent` directly (no AgentAPI); interactive chat by default
- Supports non-interactive prints (-p) with output-format, model (-m), force (-f)
- Merges MCP settings into ~/.cursor/settings.json
- Installs via npm (uses nvm if needed); terraform tests added

Author: matifali

registry/coder-labs/modules/cursor-cli/README.md

@@ -0,0 +1,57 @@
+---
+display_name: Cursor CLI
+icon: ../../../../.icons/cursor.svg
+description: Run Cursor CLI agent in your workspace (no AgentAPI)
+verified: true
+tags: [agent, cursor, ai, cli]
+---
+
+# Cursor CLI
+
+Run the Cursor Coding Agent in your workspace using the Cursor CLI directly. This module does not use AgentAPI and executes the Cursor agent process itself.
+
+- Defaults to interactive mode, with an option for non-interactive mode
+- Supports `--force` runs
+- Allows configuring MCP servers (settings merge)
+- Lets you choose a model and pass extra CLI arguments
+
+```tf
+module "cursor_cli" {
+  source   = "registry.coder.com/coder-labs/cursor-cli/coder"
+  version  = "0.1.0"
+  agent_id = coder_agent.example.id
+
+  # Optional
+  folder              = "/home/coder/project"
+  install_cursor_cli  = true
+  cursor_cli_version  = "latest"
+  interactive         = true
+  non_interactive_cmd = "run --once"
+  force               = false
+  model               = "gpt-4o"
+  additional_settings = jsonencode({
+    mcpServers = {
+      coder = {
+        command = "coder"
+        args    = ["exp", "mcp", "server"]
+        type    = "stdio"
+        name    = "Coder"
+        env     = {}
+        enabled = true
+      }
+    }
+  })
+  extra_args = ["--verbose"]
+}
+```
+
+## Notes
+
+- See Cursor CLI docs: `https://docs.cursor.com/en/cli/overview`
+- The module writes merged settings to `~/.cursor/settings.json`
+- Interactive by default; set `interactive = false` to run non-interactively via `non_interactive_cmd`
+
+## Troubleshooting
+
+- Ensure the CLI is installed (enable `install_cursor_cli = true` or preinstall it in your image)
+- Logs are written to `~/.cursor-cli-module/`

registry/coder-labs/modules/cursor-cli/cursor-cli.tftest.hcl

@@ -0,0 +1,91 @@
+// Terraform tests for the cursor-cli module
+// Validates that we render expected script content given inputs
+
+run "defaults_interactive" {
+  command = plan
+
+  variables {
+    agent_id = "test-agent"
+  }
+
+  assert {
+    condition     = can(regex("INTERACTIVE='true'", resource.coder_script.cursor_cli.script))
+    error_message = "Expected INTERACTIVE default to be true"
+  }
+
+  assert {
+    condition     = can(regex("BINARY_NAME='cursor-agent'", resource.coder_script.cursor_cli.script))
+    error_message = "Expected default binary_name to be cursor-agent"
+  }
+}
+
+run "non_interactive_mode" {
+  command = plan
+
+  variables {
+    agent_id            = "test-agent"
+    interactive         = false
+    non_interactive_cmd = "run --once"
+  }
+
+  assert {
+    condition     = can(regex("INTERACTIVE='false'", resource.coder_script.cursor_cli.script))
+    error_message = "Expected INTERACTIVE to be false when interactive=false"
+  }
+
+  assert {
+    condition     = can(regex("NON_INTERACTIVE_CMD='run --once'", resource.coder_script.cursor_cli.script))
+    error_message = "Expected NON_INTERACTIVE_CMD to be propagated"
+  }
+}
+
+run "model_and_force" {
+  command = plan
+
+  variables {
+    agent_id = "test-agent"
+    model    = "test-model"
+    force    = true
+  }
+
+  assert {
+    condition     = can(regex("MODEL='test-model'", resource.coder_script.cursor_cli.script))
+    error_message = "Expected MODEL to be propagated"
+  }
+
+  assert {
+    condition     = can(regex("FORCE='true'", resource.coder_script.cursor_cli.script))
+    error_message = "Expected FORCE true to be propagated"
+  }
+}
+
+run "additional_settings_propagated" {
+  command = plan
+
+  variables {
+    agent_id            = "test-agent"
+    additional_settings = jsonencode({
+      mcpServers = {
+        coder = {
+          command = "coder"
+          args    = ["exp", "mcp", "server"]
+          type    = "stdio"
+        }
+      }
+    })
+  }
+
+  // Ensure the encoded settings are passed into the install invocation
+  assert {
+    condition     = can(regex(base64encode(jsonencode({
+      mcpServers = {
+        coder = {
+          command = "coder"
+          args    = ["exp", "mcp", "server"]
+          type    = "stdio"
+        }
+      }
+    })), resource.coder_script.cursor_cli.script))
+    error_message = "Expected ADDITIONAL_SETTINGS (base64) to be in the install step"
+  }
+}

registry/coder-labs/modules/cursor-cli/main.test.ts

@@ -0,0 +1,96 @@
+import { test, afterEach, describe, setDefaultTimeout, beforeAll, expect } from "bun:test";
+import { execContainer, readFileContainer, runTerraformInit, runTerraformApply, writeFileContainer, runContainer, removeContainer, findResourceInstance } from "~test";
+import dedent from "dedent";
+
+let cleanupFunctions: (() => Promise<void>)[] = [];
+const registerCleanup = (cleanup: () => Promise<void>) => {
+  cleanupFunctions.push(cleanup);
+};
+
+afterEach(async () => {
+  const cleanupFnsCopy = cleanupFunctions.slice().reverse();
+  cleanupFunctions = [];
+  for (const cleanup of cleanupFnsCopy) {
+    try {
+      await cleanup();
+    } catch (error) {
+      console.error("Error during cleanup:", error);
+    }
+  }
+});
+
+const writeExecutable = async (containerId: string, filePath: string, content: string) => {
+  await writeFileContainer(containerId, filePath, content, { user: "root" });
+  await execContainer(containerId, ["bash", "-c", `chmod 755 ${filePath}`], ["--user", "root"]);
+};
+
+const loadTestFile = async (...relativePath: string[]) => {
+  return await Bun.file(new URL(`./testdata/${relativePath.join("/")}`, import.meta.url)).text();
+};
+
+const setup = async (vars?: Record<string, string>): Promise<{ id: string }> => {
+  const state = await runTerraformApply(import.meta.dir, {
+    agent_id: "foo",
+    install_cursor_cli: "false",
+    ...vars,
+  });
+  const coderScript = findResourceInstance(state, "coder_script");
+  const id = await runContainer("codercom/enterprise-node:latest");
+  registerCleanup(async () => removeContainer(id));
+  await writeExecutable(id, "/home/coder/script.sh", coderScript.script);
+  await writeExecutable(id, "/usr/bin/cursor", await loadTestFile("cursor-mock.sh"));
+  return { id };
+};
+
+setDefaultTimeout(60 * 1000);
+
+describe("cursor-cli", async () => {
+  beforeAll(async () => {
+    await runTerraformInit(import.meta.dir);
+  });
+
+  test("happy-path-interactive", async () => {
+    const { id } = await setup();
+    const resp = await execContainer(id, ["bash", "-c", "cd /home/coder && ./script.sh"]);
+    if (resp.exitCode !== 0) {
+      console.log(resp.stdout);
+      console.log(resp.stderr);
+    }
+    expect(resp.exitCode).toBe(0);
+    const startLog = await readFileContainer(id, "/home/coder/.cursor-cli-module/start.log");
+    expect(startLog).toContain("agent");
+    expect(startLog).toContain("--interactive");
+  });
+
+  test("non-interactive-with-cmd", async () => {
+    const { id } = await setup({ interactive: "false", non_interactive_cmd: "run --once" });
+    const resp = await execContainer(id, ["bash", "-c", "cd /home/coder && ./script.sh"]);
+    expect(resp.exitCode).toBe(0);
+    const startLog = await readFileContainer(id, "/home/coder/.cursor-cli-module/start.log");
+    expect(startLog).toContain("run");
+    expect(startLog).toContain("--once");
+    expect(startLog).not.toContain("--interactive");
+  });
+
+  test("model-and-force-and-extra-args", async () => {
+    const { id } = await setup({ model: "test-model", force: "true" });
+    const resp = await execContainer(id, ["bash", "-c", "cd /home/coder && ./script.sh"], ["--env", "TF_VAR_extra_args=--foo\nbar"]);
+    expect(resp.exitCode).toBe(0);
+    const startLog = await readFileContainer(id, "/home/coder/.cursor-cli-module/start.log");
+    expect(startLog).toContain("--model");
+    expect(startLog).toContain("test-model");
+    expect(startLog).toContain("--force");
+  });
+
+  test("additional-settings-merge", async () => {
+    const settings = dedent`
+      {"mcpServers": {"coder": {"command": "coder", "args": ["exp","mcp","server"], "type": "stdio"}}}
+    `;
+    const { id } = await setup({ additional_settings: settings });
+    const resp = await execContainer(id, ["bash", "-c", "cd /home/coder && ./script.sh"]);
+    expect(resp.exitCode).toBe(0);
+    const cfg = await readFileContainer(id, "/home/coder/.cursor/settings.json");
+    expect(cfg).toContain("mcpServers");
+    expect(cfg).toContain("coder");
+  });
+});