CLI To JS
Apps & Automationcli-to-jsCLI 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.
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- 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:
- Call
convertCliToJs("binary")once, reuse the returned API - Use
.text(),.lines(), or.json()for typed output — never manually splitresult.stdout - Use
$validatebefore executing when inputs come from untrusted sources - Use
$spawn+for awaitfor 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
| Method | Returns | Use for |
|---|---|---|
api.sub(opts) | CommandPromise | Run subcommand |
.text() | Promise<string> | Trimmed stdout |
.lines() | Promise<string[]> | Split by newlines |
.json<T>() | Promise<T> | Parse JSON output |
api.$spawn.sub(opts) | CommandProcess | for await streaming |
api.$command.sub(opts) | string | Shell string, no execution |
api.$validate(opts) | ValidationError[] | Pre-flight flag checking |
api.$validate("sub", opts) | ValidationError[] | Subcommand flag checking |
api.$schema | CliSchema | Parsed schema from --help |
api.$parse("sub") | ParsedCommand | Lazily enrich subcommand |
script(...cmds) | { run, toString } | Compose && chain |