alfresco-ng2-components/lib/cli/README.md

# Alfresco ADF Cli

The ADF CLI provides a set of utilities to manage your ADF projects.

## Installation

To get started, follow these instructions:

```bash
npm install @alfresco/adf-cli -g
```

To know more about any command use the -h or --help option: 

```bash
adf-cli <command> --help
```

## Developing

### Quick Setup

Link the project as a global tool (builds and links in one command):

```bash
npm run link
```

This will build the CLI and make the `adf-cli` command available globally on your system.

When you're done developing:

```bash
npm run unlink
```

### Development Mode

Build the tool in the **develop** mode (automatically watches for changes and rebuilds the commands):

```bash
npm run develop
```

Run the tool with the `DEVELOP` environment variable:

```bash
DEVELOP=true adf-cli <command>
```

In develop mode, the CLI takes the prebuilt scripts from the dist folder.

### Manual Workflow

If you need more control, you can manually build and link:

```bash
# Build the CLI
npm run build

# Or build with full distribution (includes copying resources)
npm run dist

# Link from the dist directory
cd ../../dist/libs/cli && npm link
```

## Commands

| **Commands**     | **Description**                                                |
|------------------|----------------------------------------------------------------|
| changelog        | Generate changelog report for two branches of git repository   |
| check-cs-env     | Check cs env is up                                             |
| check-plugin-env | Check plugin status                                            |
| init-aae-env     | Init env                                                       |
| init-aps-env     | Init aps                                                       |
| licenses         | Create a 3th party license file                                |
| audit            | Check the security risk dependency in your package.json        |

## Examples

### Changelog

You can get command details by using `--help` argument

```bash
adf-cli changelog --help
```

The format of the command is as following:

```bash
Usage: adf-cli changelog [options]

Generate changelog report for two branches of git repository

Options:
  -v, --version          output the version number
  -r, --range <range>    Commit range, e.g. master..develop (default: "master..develop")
  -d, --dir <dir>        Working directory (default: working directory)
  -m, --max <number>     Limit the number of commits to output
  -o, --output <dir>     Output directory, will use console output if not defined
  --skip <number>        Skip number commits before starting to show the commit output
  -f, --format <format>  Output format (md, html) (default: "md")
  -e --exclude <string>  Exclude authors from the output, comma-delimited list
  -h, --help             output usage information
```

#### Usage examples

```sh
# show changelog in the console for the current directory
adf-cli changelog -r master..develop -d .

# show changelog in the console for a specific folder 
adf-cli changelog -d ~/github/alfresco-ng2-components

# generate changelog for specific folder and pipe the console output to a file
adf-cli changelog -d ~/github/alfresco-ng2-components > log.md

# generate changelog report in the default format as "changelog-X.X.X.md" and save to the current folder
adf-cli changelog -d ~/github/alfresco-ng2-components -o .  

# generate changelog report and save it to a specific folder
adf-cli changelog -d ~/github/alfresco-ng2-components -o ../reports

# generate changelog report in the HTML format and save to the current folder
adf-cli changelog -d ~/github/alfresco-ng2-components -f html -o .

# generate report in the default format and save to the current folder, reset all filters (including embedded ones for bots)
adf-cli changelog -d ~/github/alfresco-ng2-components -e ""

# generate report in the default format excluding commits made by certain authors
adf-cli changelog -d ~/github/alfresco-ng2-components -e "bot,user1,user2"
```

### License Check

Move in the folder where you have your `package.json` and run the command:

```bash
npm install

adf-cli licenses
```

### Audit Check

Move in the folder where you have your `package.json` and run the command:

```bash
npm install

adf-cli audit
```

### Initialize activiti cloud env

The following command is in charge of Initializing the activiti cloud env with the default apps:

```bash
adf-cli init-aae-env --host "gateway_env"  --oauth "identity_env" --identityHost "identity_env" --modelerUsername "modelerusername" --modelerPassword "modelerpassword" --devopsUsername "devopsusername" --devopsPassword "devopspassword"
```

You can also specify the environment ids of the envs where to deploy the app adding the `--envs` option:
```bash
adf-cli init-aae-env --host "gateway_env"  --oauth "identity_env" --identityHost "identity_env" --modelerUsername "modelerusername" --modelerPassword "modelerpassword" --devopsUsername "devopsusername" --devopsPassword "devopspassword" --envs envId1 envId2
```

If you want to add a new app the schema needs to be:

```text
TEST_APP: {
    name: 'testapp',
    file_location: 'https://github.com/Alfresco/alfresco-ng2-components/blob/branch/e2e/resources/testapp.zip?raw=true',
    security:[
        {'role': 'APS_ADMIN', groups': ['myadmingroup'], 'users': ['myadminuser']},
        {'role': 'APS_USER', 'groups': ['myusergroup'], 'users': ['myuser']}]
    },
```

### Checks plugin status

The following command is in charge of checking plugin status by given plugin name:

```bash
adf-cli check-plugin-env --host "gateway_env" --pluginName "Name of the plugin" --clientId "clientId" --appName "appName" -u "username" -p "password" 
--ui "uiName"
```