Skip to content
On this page

Quick Start Guide

/cliapp$ wooks cli --quick-start|


Work on Wooks is still in progress. It is already suitable for immediate use in CLI events, but some APIs may still undergo changes.

This guide will help you get started with using Wooks CLI to build powerful command-line interfaces (CLIs) for your applications. Wooks CLI leverages the concept of composables and event context to provide a seamless and flexible workflow for processing CLI commands. Let's dive in!


To install Wooks CLI, you need to have Node.js and npm (Node Package Manager) installed on your system. Once you have them set up, you can install Wooks CLI using the following command:

npm install wooks @wooksjs/event-cli


Here's a step-by-step guide to using Wooks CLI:

Step 1: Import createCliApp factory and create an App instance

Start by importing the necessary modules and creating an instance of the Wooks CLI adapter:

import { createCliApp } from '@wooksjs/event-cli'
import { useRouteParams } from 'wooks'

const app = createCliApp()
import {
} from '@wooksjs/event-cli'
import { useRouteParams } from 'wooks'

const app = createCliApp({
    // Implementing onUnknownCommand hook
    onUnknownCommand: (path, raiseError) => {
        // Whenever cli command was not recognized by router
        // this callback will be called        
        if (!useAutoHelp()) {
            // fallback to useCommandLookupHelp if command help was not found
            // fallback to a standard error handling when command not recognized

Step 2: Define CLI commands

Next, you can define your CLI commands using the cli() method provided by the Wooks CLI adapter. The cli() method allows you to register CLI commands along with their respective handlers.

app.cli('command/:arg', () => {
  // Handle the command and its parameters
  return 'Command executed with argument:', useRouteParams().get('arg')
app.cli('command/:arg', () => {
  useAutoHelp() && process.exit(0)  // Print help if --help option provided
  // Handle the command and its parameters
  return 'Command executed with argument:', useRouteParams().get('arg')

Step 3: Start command processing

To start processing CLI commands, you can call the run() method of the Wooks CLI adapter. By default, it uses process.argv.slice(2) as the command, but you can also pass your own argv array as an argument.


Step 4: Execute CLI commands

You can now execute your registered CLI commands by running your script with the appropriate command and arguments. Here's an example:

node your-script.js command test

This will execute the registered CLI command with the argument "test" and log the result to the console.

Advanced Usage

Wooks CLI provides additional features and options for building more complex CLIs. Some of the notable features include:

That's it! You have completed the Quick Start Guide for Wooks CLI. You now have the basic knowledge and steps to start building your own CLI applications using Wooks CLI. Feel free to explore the documentation and experiment with different configurations and options to suit your specific requirements.

Happy command-line scripting with Wooks CLI!

Released under the MIT License.