@0x-jerry/silver

Silver

Let writing CLI like writing a document.

Install

pnpm i @0x-jerry/silver

Quick Start

import { silver } from "@0x-jerry/silver";

const cli = silver`
v1.0.0 @autocomplete

my-cli [file], A CLI that writes like a document. ${mainAction}

-t --test @type:defaultValue, Test autocomplete.
-o --output @string, Output file path.

up/upgrade <dir> [...extra] #stopEarly, Upgrade something. ${upgradeAction}

  -f --force @bool, Force upgrade.
`;

// Register custom completion types
cli.type("type", () => ["value1", "value2", "value3"]);

function mainAction([file], options) {
  console.log("file:", file, "options:", options);
}

function upgradeAction([dir, ...extra], options) {
  console.log("dir:", dir, "extra:", extra, "options:", options);
}

Syntax Guide

Silver uses a template literal to define your CLI. Here's the full syntax:

Program-level

v1.0.0 @autocomplete @manual

Command Definition

commandName/alias [param] <reqParam> [...restParam] #stopEarly, Description text. ${actionFn}

Command flags:

Options

-s --string @type, Description.

Parameter Types

[@type:name]     // typed optional parameter
<@type:name>     // typed required parameter
[...@type|_files:name]  // typed rest param with file completion

Types are registered via cli.type(name, getValues). Built-in types include bool, boolean, number, string. Special completion types _files and _dirs enable shell-native file/directory completion.

Autocomplete

Set @autocomplete at the program level to enable shell completion.

Shell Support

For persistent setup, add the output to your shell's config file (.zshrc or PowerShell profile).

Custom Completion Types

cli.type("env", () => ["development", "production", "staging"]);

// Async types
cli.type("remote-branch", async () => {
  const res = await fetch("https://api.example.com/branches");
  return res.json();
});

// With descriptions (displayed in some shells)
cli.type("format", () => [
  { label: "json", desc: "JSON output" },
  { label: "yaml", desc: "YAML output" },
]);

Built-in Completion Types

These can be combined with custom types: @custom|_files.

API

silver (default export)

function silver(template: TemplateStringsArray, ...tokens: any[]): Silver;

Parses the template and optionally auto-executes with process.argv.

Silver class

Exported Types

import {
  silver,
  BuiltinType, // enum: File = '_files', Dir = '_dirs'
  type CompletionGroup, // { name: string, values: string[] }
  type CompletionOutput, // { groups: CompletionGroup[] }
  type Command,
  type CmdOption,
  type CmdParameter,
  type Program,
  type CmdAction,
  type ActionParsedArgs,
  ProgramFlag,
  CommandFlag,
} from "@0x-jerry/silver";

Thanks

• vitest
• minimist
• tsdown
• ohm-js
• mustache
• picocolors