Zors 🥇

Next-gen framework for building modern, type-safe command-line applications.

• 📦 Tiny (zero dependencies)
• 💡 Runtime agonistic (supports both Deno and Node JS)
• 🛠️ Rich Features
• 🔩 Simple and extensible plugin api
• 🔑 Excellent Typescript support with fully Typed APIs

Notice

We're actively working on bug fixes, improvements and documentation to get this stable and released ASAP.

Table of Contents

• Installation
• Quick Start Guide
• Usage
  • Display Help Message and Version
• API Reference
• Packages

Installation

# with npm
npm install zors

# with yarn
yarn add zors

# with pnpm
pnpm add zors

Quick Start Guide

To create a new program you can import the zors function, which takes in your a name and version which will be later used for automatic help generation.

Its recommended to keep your program name same as the bin name in your package.json

// in main.[js | ts] ...

import { zors } from 'zors';

const name = 'my-git';
const version = '1.0.0';

const program = zors(name, version);

// let's build a simple git cli
program
  .command('init', 'Initialize an empty git repository')
  .option(
    '-q, --quiet',
    'Only print error and warning messages; all other output will be suppressed.'
  )
  .action((args, options, tools) => {
    if (!options.quiet) {
      console.log('Initialized an empty git repository');
    }

    process.exit(0);
  });

// run it
await program.run(process.argv.slice(2));

So what do some of these terms mean?

You can use the .command() method to create a new Command which takes in a some raw input and description parameters along with an optional config object.

  .command('init', 'Initialize an empty git repository')

Every command can define some options, you can add one using .option() method on any command object. Which also takes in a raw input and description.

If neither of these are used, an option is treated as a boolean by default.

.option('-q, --quiet', 'Only print error and warning messages; all other output will be suppressed.')

Every command needs to have an action defined, action is just a function which is executed with some arguments when the command is called.

You can define an action using the .action() method on any command, whose parameters are args, options and tools respectively.

.action((args, options, tools) => {
  // define the actions needed to be done on command execution
});

That's all you need to create a basic CLI app,

Let's try running it. In Node to get the standard input argv we can use process.argv and use .slice(2) ignore the first 2 items in the array as they're of no use to us.

await program.run(process.argv.slice(2));

🔝 scroll to top

Usage

Display Help Message and Version

import { zors } from 'zors';
import { commitCommand, statusCommand } from './commands.js';

const program = zors('git', '1.0.0');

program
  .help()           // Displays help message when '-h' or '--help' is specified
  .version("1.0.0") // Displays version number when '-v' or '--version' is specified
  .command(...)
  ...

program.run(process.argv.slice(2));

🔝 scroll to top

API Reference

We rely on Typescript types to auto-generate API documentation find it here

Packages

Package	Version (click for changelogs)
zors

🔝 scroll to top