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

| Token | Description | | --------------- | ---------------------------------------------------------- | | v1.0.0 | Version declaration (must be at the top) | | @autocomplete | Enables complete subcommand for shell autocomplete | | @manual | Prevents auto-execution; call cli.execute(argv) manually |

Command Definition

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

| Part | Example | Description | | -------------- | --------------------- | ----------------------------------------- | | Name | install | Command name (alphanumeric + _) | | Alias | install/i | Shorthand alias via / | | Optional param | [name] | Optional positional parameter | | Required param | <name> | Required positional parameter | | Rest param | [...items] | Collects remaining arguments as array | | Flag | #stopEarly | Command flag (see below) | | Description | , Install packages. | Text after comma is the description | | Action | ${myFn} | Function to call when command is executed |

Command flags:

| Flag | Description | | ------------ | -------------------------------------------------------- | | #stopEarly | Stop parsing options after the first non-option argument |

Options

-s --string @type, Description.

| Part | Example | Description | | ----------- | ---------------- | ----------------------- | | Short name | -s | Single-letter alias | | Long name | --string | Full option name | | Type | @string | Option type (see below) | | Description | , Description. | Text after comma |

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

| Shell | Command | | ---------- | ---------------------------------------------------------------- | | zsh | source <(your-cli complete zsh) | | PowerShell | Invoke-Expression (your-cli complete powershell \| Out-String) |

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

| Type | Description | | -------- | ---------------------------------------- | | _files | File path completion (shell-native) | | _dirs | Directory path completion (shell-native) |

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

| Method | Description | | ----------------------- | ------------------------------------------ | | type(name, getValues) | Register a completion type (sync or async) | | execute(argv) | Execute the CLI with the given arguments | | parse(raw, ...tokens) | Parse a template literal programmatically |

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