Skip to main content

Command-line interface

flecks has a command-line interface for building, linting, testing, and so much more.

Built-in commands​

add​

Usage: flecks add [options] <packages...>

Add flecks to your application.

Arguments:
  packages                        packages to add

Options:
  -d, --dev-dependency            add to dev dependencies
  -h, --help                      display help for command

build​

Usage: flecks build [options] [target]

Build a target in your application.

Arguments:
  target               build target (choices: "fleck")

Options:
  -d, --no-production  dev build
  -h, --hot            build with hot module reloading
  -w, --watch          watch for changes
  --help               display help for command

clean​

Usage: flecks clean [options]

Remove node_modules, lock file, and build artifacts.

Options:
  -h, --help                      display help for command

dox​

(Implemented by @flecks/dox)

Usage: flecks dox [options] <subcommand> [output path]

Generate documentation

Arguments:
  subcommand                          Generation type (choices: "docusaurus", "json")
  output path                         Where the files are output

Options:
  -r, --rewrite-filenames [pairs...]  rewrite filenames
  -h, --help                          display help for command

lint​

Usage: flecks lint [options]

Run ESLint.

Options:
  -h, --help  display help for command

repl​

(Implemented by @flecks/repl)

Usage: flecks repl [options]

Connect to REPL.

Options:
  -r, --rlwrap  use rlwrap around socat
  -h, --help    display help for command

test​

Usage: flecks test [options] [only]

Run tests.

The options are passed along to the `build` command.

Arguments:
  only                           only run a specific test

Options:
  -d, --no-production            dev build
  -p, --platform [platforms...]  platforms to test (default: ["default","server"])
  -t, --timeout <ms>             timeout (default: 2000)
  -v, --verbose                  verbose output
  -w, --watch                    watch for changes
  -h, --help                     display help for command

Your commands​

You can implement your own command by implementing @flecks/build.commands in your fleck. Let's run through the process.

Implement @flecks/build​.commands​

First, create an application:

npm init @flecks/app cli_test

Move into the new project and create a fleck:

npm init @flecks/fleck -w packages/fortune

We're going to be creating a fortune teller command that will tell you when you will find love. 😍

Create a command that takes an option​

Commands are gathered during the bootstrap phase and therefore your hook must be implemented in a bootstrap script.

Edit your bootstrap script at packages/fortune/build/flecks.bootstrap.js to look like this:

packages/fortune/build/flecks.bootstrap.js
export const hooks = {
  '@flecks/build.commands': (program) => ({
    fortune: {
      options: [
        program.createOption('-n, --be-nice', 'be nice'),
      ],
      description: 'find your true love',
      action: async ({beNice}) => {
        console.log(`It will be ${Math.floor(Math.random() * 10) + 2} days until you meet your true love!`);
        if (!beNice) {
          console.log('You might also stub your toe.');
        }
      },
    },
  }),
};

Inspect and invoke your command​

Now, invoke flecks like so:

npx flecks --help

You will see among the commands listed:

  fortune [options]         find your true love

Run the command with the --help option:

npx flecks fortune --help

You will see this output:

Usage: flecks fortune [options]

find your true love

Options:
  -n, --be-nice  be nice

Let's try it!

npx flecks fortune --be-nice

You will see something like:

It will be 11 days until you meet your true love!

How about without our option:

npx flecks fortune

You will see something like:

It will be 7 days until you meet your true love!
You might also stub your toe.

Define arguments​

You can also define arguments in addition to options. Let's add an argument that takes the user's name to personalize the output:

packages/fortune/build/flecks.bootstrap.js
export const hooks = {
  '@flecks/build.commands': (program, flecks) => {
    return {
      fortune: {
        args: [
          program.createArgument('[name]', 'your name')
        ],
        options: [
          program.createOption('-n, --be-nice', 'be nice'),
        ],
        description: 'find your true love',
        action: async (name = 'person', {beNice}) => {
          console.log(`Hey, ${name}. It will be ${Math.floor(Math.random() * 10) + 2} days until you meet your true love!`);
          if (!beNice) {
            console.log('You might also stub your toe.');
          }
        },
      },
    };
  },
};

Notice that we added the argument to... the arguments.

Try it again:

npx flecks fortune --be-nice

You will see e.g.:

Hey, person. It will be 7 days until you meet your true love!

That's because we set the default name to 'person' in the code above. Let's try passing in a name:

npx flecks fortune cha0s

Now the output looks like:

Hey, cha0s. It will be 4 days until you meet your true love!
You might also stub your toe.

Going further​

flecks uses Commander.js under the hood to build its CLI. It might be worth checking out their documentation for any more advanced usage.