# 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.

- Skill name: `cli-to-js`
- Category: [Apps & Automation](https://www.openparable.com/skill/apps-automation/1)
- Source: https://github.com/millionco/cli-to-js/blob/HEAD/.agents/skills/cli-to-js/SKILL.md
- Repository: millionco/cli-to-js (407 GitHub stars when collected)

## SKILL.md

# 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

```ts
// 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

```ts
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:**

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

**Good:**

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

**Bad:**

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

**Good:**

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

**Bad:**

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

**Good:**

```ts
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

```ts
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           |

---

Source: https://www.openparable.com/skill/apps-automation/cli-to-js (OpenParable). Cite the canonical URL above.
