Skip to main content

run

Execute project scripts or raw commands with process management.

Synopsis​

// Run a project script
run {script_name: "<name>"}

// Run a raw command
run {raw: true, command: "<executable>", args: ["arg1", "arg2"]}

Parameters​

ParameterTypeRequiredDescription
script_namestringYes*Script name from detect (e.g., "test", "build")
rawbooleanNoSet to true to run raw command instead of script
commandstringYes**Executable to run (when raw: true)
argsstring[]NoArguments for raw command
idstringNoCustom process ID (auto-generated if omitted)
pathstringNoWorking directory (defaults to current)
modestringNoExecution mode: background, foreground, foreground-raw

* Required if raw is not true ** Required if raw is true

Execution Modes​

Background (Default)​

Returns immediately with process ID. Process runs asynchronously.

run {script_name: "dev"}
→ {
    "process_id": "dev",
    "state": "running",
    "message": "Process started in background"
  }

Use proc tool to monitor.

Foreground​

Waits for completion. Returns exit code and runtime.

run {script_name: "build", mode: "foreground"}
→ {
    "process_id": "build",
    "state": "stopped",
    "exit_code": 0,
    "runtime": "12.3s"
  }

Output accessible via proc {action: "output"}.

Foreground-Raw​

Waits for completion. Includes stdout/stderr in response.

run {script_name: "test", mode: "foreground-raw"}
→ {
    "process_id": "test",
    "state": "stopped",
    "exit_code": 0,
    "runtime": "5.2s",
    "stdout": "✓ 42 tests passed\n",
    "stderr": ""
  }

Best for short commands where output is needed immediately.

Examples​

Run Project Scripts​

// Run tests
run {script_name: "test"}

// Run build and wait
run {script_name: "build", mode: "foreground"}

// Run lint with immediate output
run {script_name: "lint", mode: "foreground-raw"}

Run Raw Commands​

// Go module tidy
run {raw: true, command: "go", args: ["mod", "tidy"], mode: "foreground-raw"}

// cURL request
run {raw: true, command: "curl", args: ["-s", "https://api.example.com/health"]}

// Docker command
run {raw: true, command: "docker", args: ["ps"]}

Custom Process IDs​

// Named dev servers for multi-project
run {script_name: "dev", id: "frontend-dev", path: "./apps/web"}
run {script_name: "dev", id: "backend-dev", path: "./apps/api"}

// Check status by ID
proc {action: "status", process_id: "frontend-dev"}

Working Directory​

// Run in subdirectory
run {script_name: "test", path: "./packages/core"}

// Run in monorepo package
run {script_name: "build", path: "./apps/web", id: "web-build"}

Response​

Background Mode​

interface RunBackgroundResponse {
  process_id: string;
  state: "starting" | "running";
  message: string;
}

Foreground Mode​

interface RunForegroundResponse {
  process_id: string;
  state: "stopped" | "failed";
  exit_code: number;
  runtime: string;
}

Foreground-Raw Mode​

interface RunForegroundRawResponse {
  process_id: string;
  state: "stopped" | "failed";
  exit_code: number;
  runtime: string;
  stdout: string;
  stderr: string;
}

Error Responses​

Script Not Found​

{
  "error": "script not found",
  "script_name": "nonexistent"
}

ID Already Exists​

{
  "error": "process already exists",
  "process_id": "dev"
}

Command Failed to Start​

{
  "error": "command not found: unknowncmd",
  "command": "unknowncmd"
}

Process Lifecycle​

After starting with run:

  1. Monitor: proc {action: "status", process_id: "..."}
  2. View Output: proc {action: "output", process_id: "..."}
  3. Stop: proc {action: "stop", process_id: "..."}

See Also​