OpenParable
Skip to content
← Back to skills

CLI To JS

Apps & Automation
cli-to-js

CLI To JS is an Agent Skill for apps & automation published in the millionco/cli-to-js repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when wrapping CLI binaries in JavaScript, automating shell workflows in TypeScript, composing multiple CLIs into scripts, or building agent tool-use. Covers convertCliToJs, $command, $validate, $spawn, script(), .text()/.lines()/.json() output parsing.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/millionco/cli-to-js/blob/HEAD/.agents/skills/cli-to-js/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/cli-to-js, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

cli-to-js

You are using cli-to-js to turn CLI binaries into callable JavaScript APIs.

REQUIRED for every cli-to-js usage:

  1. Call convertCliToJs("binary") once, reuse the returned API
  2. Use .text(), .lines(), or .json() for typed output — never manually split result.stdout
  3. Use $validate before executing when inputs come from untrusted sources
  4. Use $spawn + for await for streaming — never callbacks unless specifically asked

Flag mapping

// JS option key            → CLI output
// { verbose: true }        → --verbose
// { verbose: false }       → (omitted)
// { output: "file.txt" }   → --output file.txt
// { dryRun: true }         → --dry-run
// { v: true }              → -v
// { include: ["a", "b"] }  → --include a --include b
// { _: ["file.txt"] }      → file.txt

API quick reference

import { convertCliToJs, script } from "cli-to-js";
const tool = await convertCliToJs("binary-name");

// Run + typed output
await tool.subcommand({ flag: "val", _: ["pos"] }).text();
await tool.subcommand({ json: true }).json<MyType>();
await tool.subcommand().lines();

// Streaming
for await (const line of tool.$spawn.subcommand({ watch: true })) {
}

// Validation (did-you-mean, choices, required flags, exclusive flags)
const errors = tool.$validate({ misspeled: true });

// Shell string without executing
tool.$command.subcommand({ flag: "val" });
// → "binary-name subcommand --flag val"

// Compose into runnable script
const deploy = script(git.$command.push(), docker.$command.build({ tag: "app", _: ["."] }));
deploy.run(); // execute with &&
console.log(`${deploy}`); // get the string

When building tools

Bad:

const result = await api.status();
const lines = result.stdout.trim().split("\n");

Good:

const statusLines = await api.status().lines();

Bad:

const api1 = await convertCliToJs("git");
const api2 = await convertCliToJs("git"); // wasteful duplicate

Good:

const git = await convertCliToJs("git");
// reuse git everywhere

Bad:

await api.commit({ mesage: "fix" }); // typo silently becomes unknown flag

Good:

const errors = api.$validate({ mesage: "fix" });
// [{ kind: "unknown-flag", suggestion: "message" }]
if (errors.length > 0) throw new Error(errors[0].message);
await api.commit({ message: "fix" });

Multi-CLI workflow pattern

const git = await convertCliToJs("git");
const claude = await convertCliToJs("claude");

const files = await git.diff({ nameOnly: true, _: ["HEAD~1"] }).lines();

for (const file of files) {
  const review = await claude({
    print: true,
    model: "sonnet",
    _: [`Review ${file} for bugs`],
  }).text();

  if (review.includes("no issues")) continue;
  console.log(`${file}: ${review}`);
}

Full API surface

MethodReturnsUse for
api.sub(opts)CommandPromiseRun subcommand
.text()Promise<string>Trimmed stdout
.lines()Promise<string[]>Split by newlines
.json<T>()Promise<T>Parse JSON output
api.$spawn.sub(opts)CommandProcessfor await streaming
api.$command.sub(opts)stringShell string, no execution
api.$validate(opts)ValidationError[]Pre-flight flag checking
api.$validate("sub", opts)ValidationError[]Subcommand flag checking
api.$schemaCliSchemaParsed schema from --help
api.$parse("sub")ParsedCommandLazily enrich subcommand
script(...cmds){ run, toString }Compose && chain