agent-argv

Structured command execution for AI agents without shell quoting by default.

The core idea is simple: agents should emit data, not terminal strings. Most commands should run as program + args with shell: false. Shell execution stays available for pipes, redirection, glob expansion, and shell-specific syntax, but it is explicit.

Install

npm install agent-argv

API

import { runAgentCommand } from "agent-argv";

const result = await runAgentCommand({
  program: "git",
  args: ["commit", "-m", 'message with "quotes" and spaces'],
  cwd: "C:\\repo"
});

console.log(result.stdout);

Command Shape

type AgentCommand = {
  program?: string;
  args?: string[];
  cwd?: string;
  env?: Record<string, string | null | undefined>;
  stdin?: string | null;
  shell?: false | {
    dialect: "powershell" | "pwsh" | "cmd" | "bash" | "sh";
    script: string;
  };
  tempScript?: {
    language: "powershell" | "cmd" | "bash" | "sh" | "python" | "node";
    content: string;
    args?: string[];
    keep?: boolean;
    dir?: string;
  };
  timeoutMs?: number;
};

Use exactly one of program, shell, or tempScript.

Preview

import { normalizeCommand, previewCommand } from "agent-argv";

const normalized = await normalizeCommand({
  program: "git",
  args: ["commit", "-m", "fix quoting bug"]
});

console.log(previewCommand(normalized));

Output:

program: git
args:
  [0] "commit"
  [1] "-m"
  [2] "fix quoting bug"
cwd: /repo
shell: false

Temp Scripts

Avoid large inline command strings like python -c, node -e, or powershell -Command when the content is complex:

await runAgentCommand({
  tempScript: {
    language: "node",
    content: "console.log(JSON.stringify(process.argv.slice(2)))",
    args: ['value with "quotes"', "a&b", "$HOME"]
  }
});

Explicit Shell Mode

Use shell mode only when shell syntax is the point:

await runAgentCommand({
  shell: {
    dialect: "powershell",
    script: "Get-ChildItem | Select-String TODO"
  }
});

Internally, this still uses spawn(..., { shell: false }); the shell executable and its arguments are made explicit.

CLI

agent-argv preview command.json
agent-argv run command.json

Example command.json:

{
  "program": "node",
  "args": ["-e", "console.log(process.argv[1])", "hello quoted world"]
}