flecks/website/docs/cli.mdx

---
title: Command-line interface
description: Use built-in commands and write your own.
---

import Create from '@site/helpers/create';

# Command-line interface

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

## Built-in commands

### `add`

Add a fleck to your application.

```
Usage: flecks add [options] <fleck>

Arguments:
  fleck       fleck
```

### `build`

Build a target in your application.

```
Usage: flecks build [options] [target]

Arguments:
  target               target (choices: "...")

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

### `lint`

Run linter.

```
Usage: flecks lint [options]
```

### `docusaurus`
(Implemented by `@flecks/dox`)

Create a documentation website for this project.

```
Usage: flecks docusaurus [options] <subcommand> [siteDir]

Arguments:
  subcommand  Docusaurus command to run (choices: "build", "create", "start")
  siteDir     Docusaurus directory (default: "website")
```

The `build` and `start` subcommands are sugar on top of the corresponding Docusaurus commands.

The `create` subcommand will create a documentation website starter template for you at `siteDir`
if `siteDir` doesn't already exist (defaults to `website`). A `docusaurus.config.js`
starter configuration will also be copied to your `build` directory if it doesn't already exist.

## Your commands

You can implement your own command by implementing
[`@flecks/core.commands`](/docs/flecks/@flecks/dox/hooks#fleckscorecommands) in your fleck. Let's
run through the process.

### Implement <code>@flecks/core&#8203;.commands</code>

First, create an application:

<Create type="app" pkg="cli_test" />

Move into the new project and create a fleck:

```bash
npx create-fleck fortune
```

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

### Create a command that takes an option

Now, edit `packages/fortune/src/index.js` to look like this:

```javascript
export const hooks = {
  '@flecks/core.commands': () => ({
    fortune: {
      options: [
        ['-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:

```bash
npx flecks --help
```

You will see among the commands listed:

```
  fortune [options]         find your true love
```

Run the command with the `--help` option:

```bash
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!

```bash
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:

```bash
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:

```javascript
export const hooks = {
  // highlight-start
  '@flecks/core.commands': (program, flecks) => {
    const {Argument} = flecks.fleck('@flecks/core/server');
    return {
    // highlight-end
      fortune: {
        // highlight-start
        args: [
          new Argument('[name]', 'your name')
        ],
        // highlight-end
        options: [
          ['-n, --be-nice', 'be nice'],
        ],
        description: 'find your true love',
        // highlight-next-line
        action: async (name = 'person', {beNice}) => {
          // highlight-next-line
          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.');
          }
        },
      },
    // highlight-start
    };
  },
  // highlight-end
};
```

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

Try it again:

```bash
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:

```bash
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](https://github.com/tj/commander.js#quick-start) under the hood to build its CLI.
It might be worth checking out their documentation for any more advanced usage.