README.md

Optc

An easy way to write a single-file TypeScript command line application.

Installation

npm i -g optc

Usage

See example echo.ts.

#!/usr/bin/env optc

export const name = 'echo';

export const version = '0.0.0';

export const description = 'Print some messages';

// Echo some message
export default function echo(text: string) {
  console.log(text);
  return text;
}

// Greet someone
export function greet(name?: string, option?: { prefix: string }) {
  const text = `${option?.prefix ?? 'Hello'}, ${name ?? 'Stranger'}`;
  console.log(text);
  return text;
}

When running the above CLI script, Optc will automatically generate a default command with a required paramter text, and a subcommand greet with an optional paramter name.

optc examples/echo.ts word
# word

optc examples/echo.ts greet world
# Hello, world

optc examples/echo.ts --version
# echo/0.0.0 win32-x64 node-v16.14.2

optc examples/echo.ts --help
# echo/0.0.0
# 
# Usage: echo [OPTIONS] [COMMAND]
# 
# Commands:
#   echo <text>        Echo some message
#   echo greet [name]  Greet someone
# 
# Options:
#   -h, --help     Print help
#   -v, --version  Print version

# or use it directly, make sure you grant the executable permissions
./examples/echo.ts greet Optc --prefix Hi
# Hi, Optc

You can see more examples in the ./examples.

Libraries

Optc has some builtin functions based on some famous libs.

• cd(dir: string): Change directory
• pwd(): Print working directory
• $`cmd`: Exec command like zx
• path: Node.js Path API
• fs: fs-extra
• glob: globby
• http: axios

Custom Libraries

You can init a node module at ~/.optc/, and create ~/.optc/dep.ts to import all your custom libraries, functions and so on to your script execution environment.

// ~/.optc/dep.ts

// Make sure that you have install "kolorist" in `~/.optc/`
import kolorist from 'kolorist'

export default function(global: any) {
  global.color = kolorist
}

Limitation

• Optc extracts type infomation from the abstract syntax tree of the code (based on babel), so you can not do some type magic (union type, generic type and so on) on the types of paramters.

• Global code snippets can not have the type of global functions. Currently, it links to the local type declaration file.

Inspiration

• argc: A handy way to handle sh/bash cli parameters.
• zx: A tool for writing better scripts
• cac: Simple yet powerful framework for building command-line apps.

License

MIT License © 2023 XLor