ap-run-command

Run a Command

When to use

Use ap-run-command for SHORT, synchronous, non-interactive shell work — a lint check, a single test file, a git status, a quick build step. It is not for long builds/test suites (use a session or a background terminal instead, see ap-terminal) and not for interactive TUIs.

MCP tool: command_execute

command must be a bare basename allowlisted in <workspace>/.agentproto/allowed-commands.json. args is an array passed to the process verbatim — there is NO shell expansion, so no pipes, globs, &&, or quoting tricks. timeoutMs caps at 600000 (10 minutes). stdin can feed input; cwd sets the working directory.

{
  "tool": "command_execute",
  "args": {
    "command": "pnpm",
    "args": ["--filter=@simone/core", "check-types"],
    "cwd": "/Volumes/SSDExternalMacStudio/Code/products/agentik/agentik-studio",
    "timeoutMs": 120000
  }
}

Every invocation creates a kind: 'command' session you can read back later like any other session.

MCP tool: command_list

List recent command sessions, newest first.

{ "tool": "command_list", "args": { "limit": 20 } }

MCP tool: command_log_tail

Tail the stdout/stderr of a specific command session, e.g. while it's still running.

{ "tool": "command_log_tail", "args": { "sessionId": "cmd_7f0a", "lines": 200 } }

MCP tool: tool_calls_list

Unified log across both command_execute calls and agent tool calls — audit what actually ran, in order, across a session or the whole workspace.

{ "tool": "tool_calls_list", "args": { "sessionId": "sess_a1b2" } }

HTTP

None — command_execute and friends are MCP/CLI-only; there is no daemon HTTP route for one-off command execution.

Gotchas

• Only for SHORT synchronous commands — a 10-minute command_execute call blocks your turn; long builds/tests belong in a session (ap-spawn-agent) or a background terminal (ap-terminal).
• No shell expansion: no pipes, no globs, no &&, no shell-interpreted quoting. Pre-compute the expansion yourself or wrap the logic in a script file and call that script instead.
• command must match an allowlisted basename exactly — a full path or an unlisted binary is rejected before it runs.
• Every command run is itself a readable session — use command_log_tail or conversation_read instead of re-running to see output you missed.