Command Line Interface

The Command Line Interface (CLI) is a powerful tool that allows users to interact with their computer systems and software applications through text-based commands.

Installation

To install the Mineral CLI, run the following command:

dart pub global activate mineral_cli [version]

Now you can use it like this:

mineral help

Welcome to Mineral CLI !
Work seamlessly with Mineral from the command line.

USAGE:
  mineral <command> <subcommand> [flags]

CORE COMMANDS
  create           Create a new project
  help             Display the help message

MAKE COMMANDS
  make:event       Create a new event class
  make:command     Create a new command class

The CLI is used in two different ways depending on the location and context in which it is used.

• Global: This is the default context, and is used when the CLI is requested from anywhere in the system outside of a Mineral project.

• Project: Within a Mineral project, the CLI is called within the context of your application. create your own commands using your project's environment variables.

Core commands

The basic commands are those available by default in the CLI.

Help

The help command displays the list of commands available in the CLI.

Welcome to Mineral CLI !
Work seamlessly with Mineral from the command line.

USAGE:
  mineral <command> <subcommand> [flags]

CORE COMMANDS
  create           Create a new project
  help             Display the help message

MAKE COMMANDS
  make:event       Create a new event class
  make:command     Create a new command class
  make:provider    Create a new provider entrypoint
  make:state       Create a new global state

It is important to note that when you create commands injected into the CLI, they will automatically appear in this help menu. automatically appear in this help menu.

Create project

The create command is used to create a new Mineral project.

mineral create [project_name]

Token

When the command is run, you will be asked to enter your application's token in order to pre-populate your environment file.

HMR

HMR (Hot Module Replacement) is a feature that automatically reloads your business code without having to restart having to restart your project.

Preset

You can then choose the skeleton of your project's software architecture in the form of an installation preset.

At present, 2 presets are available:

• Slim : A minimalist project with a minimal basic structure.
• Basic : A preset based on an architecture that groups components by type.
• Hexagonal : A preset based on an architecture that groups components by domain.

Make event

The make:event command is used to create a new event.

mineral make:event [filename]

The command will ask you to choose an event from among those available in the current version of the core used in your project.

Make command

The make:command command is used to create a new command.

mineral make:command [filename]

The command will offer you a choice of two types of command:

• Declaration
• Definition

For each of the cases presented, you will be asked to complete your order by means of a question and answer game.

You can find more information about orders in the dedicated section.

Make provider

The make:provider command is used to create a new provider.

mineral make:provider [name]

See the dedicated section for more information on providers.

Make state

The make:state command is used to create a new state.

mineral make:state [name]

See the dedicated section for more information on shared states.

Make your own commands

You can also create your own commands to simplify or automate certain processes.

The procedure explained below is valid when you want to create commands for your project but also as part of packages registered on the dart pub registry.

To collect choices from the user of your order, we recommend that you use the commander_ui library, which will enable you to create interactive interfaces within CLi and the mansion package to make colored output.

Structure

We recommend that you structure your commands according to the structure recommended in the official documentation.

We will use a bin folder for this purpose, but you are free to choose the location.

├── bin
│  └── main.dart
│
├── cli
│  ├── my_command.dart
│  └── my_command2.dart
│
├── pubspec.yaml
└── .env

Declaration

Declaring a command is an important step, as it indicates its existence within the CLI.

Following the example of Flutter, add a new mineral key to the pubspec.yaml file in your project. which will contain a list of commands.

name: my_application
description: A simple mineral application

mineral:
  commands:
    - name: my_command
      description: My first command
      entrypoint: cli/my_command.dart

environment:
dependencies:
dev_dependencies:

The use of a yaml file is mandatory because the CLI invokes the targeted command through the spawn of a new Process.

Entrypoint

The input file for your command is the file that will be invoked by the CLI. It is defined when mapping your commands in the pubspec.yaml file.

mineral:
  commands:
    - name: my_command
      description: My first command
      entrypoint: cli/my_command.dart 👈

The sine qua non condition for this invocation to work properly is the presence of a hand' function in the file containing your command.

We can think of each command as a program in its own right which can itself instantiate various services used within your Mineral application in the same way as when you start it.

For example, you can use Mineral's environment service to retrieve environment variables environment variables within your main application.

import 'package:mineral/api.dart';
import 'package:mineral/services.dart';

void main() {
  final env = Environment()
    ..loadEnvironment();

  final token = env.get(AppEnv.token);
  print('Your token is $token');
}

DART_ENV=development
TOKEN=your_token
HTTP_VERSION=10
WSS_VERSION=10
INTENT=3276799
LOG_LEVEL=TRACE

Help displaying

If your command is called migration:run or migration:rollback, it will be filed in the dedicated migration section.

...
MIGRATION COMMANDS
  migration:run          Run SQL database migrations
  migration:rollback     Rollback SQL database migrations
...