run_shell_command

TypeScript

Python
Ruby Unavailable
Lua Unavailable
TypeScript
Rust
Go
Java
.NET
C++
Swift

Run a shell command in a pane with your user’s permissions. Run a shell command in a pane, wait for it to finish, and report its exit status and output. Prefer this over send_keys plus capture_pane: it frames the command so a pane’s echo of what you typed can never be mistaken for what the command printed, and it knows when the command actually ended rather than guessing from the screen. The command runs in a subshell, so cd and export do not persist to a later call. A pane is effectively single-writer: this server reserves it until the command settles, but another process with the same tmux socket can still write into it.

All TypeScript tools · JSON · Source

Arguments

command required · string: The shell command to run.
force optional · boolean: Allow writing to the pane this server itself was called from, which is otherwise refused. It does not override the refusal to write to a pane a person is watching — a pane an attached client has on screen is still refused with force.
maxLines optional · integer: Keep at most this many lines, from the end. Defaults to the server limit.
paneId required · string: Stable pane id, e.g. %1.
timeoutMs optional · integer: How long to wait. Clamped by the server ceiling; the result says what was used.

Schemas

The schema defines required fields, nested values, defaults, and validation constraints.

Input schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "command": {
      "description": "The shell command to run.",
      "type": "string"
    },
    "force": {
      "description": "Allow writing to the pane this server itself was called from, which is otherwise refused. It does not override the refusal to write to a pane a person is watching — a pane an attached client has on screen is still refused with force.",
      "type": "boolean"
    },
    "maxLines": {
      "description": "Keep at most this many lines, from the end. Defaults to the server limit.",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "type": "integer"
    },
    "paneId": {
      "description": "Stable pane id, e.g. %1.",
      "pattern": "^%\\d+$",
      "type": "string"
    },
    "timeoutMs": {
      "description": "How long to wait. Clamped by the server ceiling; the result says what was used.",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "type": "integer"
    }
  },
  "required": [
    "command",
    "paneId"
  ],
  "type": "object"
}

Output schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false,
  "properties": {
    "droppedLines": {
      "description": "Lines of output withheld by maxLines. The text half says so in a notice; a caller reading only the structured half would otherwise take the tail for the whole.",
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "type": "integer"
    },
    "effectiveTimeoutMs": {
      "description": "The timeout actually enforced.",
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "type": "integer"
    },
    "exitStatus": {
      "anyOf": [
        {
          "maximum": 9007199254740991,
          "minimum": -9007199254740991,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "The command's exit status; null if it did not finish."
    },
    "foreignOutputSuspected": {
      "description": "Another writer printed into this pane while the command ran. Output that could be attributed to them was removed; what is left may still include theirs. False means no foreign marker was seen, not that the output is certainly this command's.",
      "type": "boolean"
    },
    "missedBytes": {
      "description": "Output that fell out of the pane's buffer before this read reached it. Nonzero means the command printed more than was kept, so the output here starts partway through it.",
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "type": "integer"
    },
    "omittedBytes": {
      "description": "Output bytes omitted by the result ceiling.",
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "type": "integer"
    },
    "outcome": {
      "description": "Why this returned. Read it rather than inferring from the text.",
      "enum": [
        "completed",
        "timed_out",
        "pane_died",
        "cancelled"
      ],
      "type": "string"
    },
    "output": {
      "description": "The bounded tail of the command's output.",
      "type": "string"
    },
    "outputComplete": {
      "description": "False when capture or result limits omitted any command output.",
      "type": "boolean"
    },
    "paneId": {
      "description": "Stable pane id, e.g. %1.",
      "pattern": "^%\\d+$",
      "type": "string"
    },
    "returnedBytes": {
      "description": "UTF-8 output bytes returned.",
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "type": "integer"
    },
    "stillRunning": {
      "description": "Whether the command may still be running after this call returned.",
      "type": "boolean"
    }
  },
  "required": [
    "effectiveTimeoutMs",
    "droppedLines",
    "missedBytes",
    "omittedBytes",
    "foreignOutputSuspected",
    "exitStatus",
    "outcome",
    "output",
    "outputComplete",
    "paneId",
    "returnedBytes",
    "stillRunning"
  ],
  "type": "object"
}

Tool annotations

{
  "destructiveHint": true,
  "idempotentHint": false,
  "openWorldHint": true,
  "readOnlyHint": false
}