rebar3_grisp_io

rebar3_grisp_io
=====
![GitHub Release](https://img.shields.io/github/v/release/grisp/rebar3_grisp_io)

Rebar plug-in for grisp.io. To obtain information about the plugin and its tasks, use the followinf command:

```shell
rebar3 help grisp-io [<task>]
```

📖 **Table of content**
- [rebar3\_grisp\_io](#rebar3_grisp_io)
  - [Installation](#installation)
  - [Tasks](#tasks)
    - [Authentication](#authentication)
    - [Deauthentication](#deauthentication)
    - [Deploy](#deploy)
    - [Upload](#upload)
    - [List](#list)
    - [Delete](#delete)
    - [Validate](#validate)
    - [Cancel](#cancel)
    - [Reboot](#reboot)
    - [Version](#version)

## Installation

To install the plugin globally, add it to your "plugins" list in `~/.config/rebar3/rebar.config`

For example:
```erlang
{plugins, [
    rebar3_hex,
    rebar3_grisp,
    rebar3_grisp_io
]}.
```

Afterwards to update it to the latest version, you need to update the Hex index and then the plugin:

```shell
rebar3 udpdate
rebar3 plugins upgrade rebar3_grisp_io
```

To verify that everything works correctly you can check the version of the plugin by calling:

```shell
rebar3 grisp-io version
```

## Tasks

### Authentication

This command allows you to authenticate on `grisp.io` and receive an API token.
By default, `rebar3 grisp-io auth` opens your OS browser to log in and approve
CLI access. The CLI creates a five-minute PKCE session, starts an HTTP listener
on an OS-selected port at `127.0.0.1`, and waits for the browser to return the
authorization code.
It verifies the callback nonce, stops the listener, and redeems the code with
its original PKCE verifier to obtain an API token.
Use `--credentials` to authenticate with a username and password.

You can encrypt the token locally with a password, or save it without
encryption. If you omit `--encrypt-token`, the command asks which option you
prefer after authentication succeeds and the API token has been obtained.
Press Enter to save the token without encryption (the default).

```shell
rebar3 grisp-io auth --credentials
===> Analyzing applications...
===> Compiling rebar3_grisp_io

Username > <Username>
Password > <Password>
Encrypt token locally? (y/N) > y
Please provide a local password to encrypt the token
Local password > <LocalPassword>
Confirm your local password > <LocalPassword> % Must be the same
Token successfully requested
```

Use `--encrypt-token true` or `--encrypt-token false` to make the choice
without the prompt. With encryption disabled, the clear API token is saved in
the local plugin config file and commands do not ask for a local password.

To use another callback port or API host, configure the plugin in `rebar.config`:

```erlang
{rebar3_grisp_io, [{base_url, <<"https://app.grisp.io">>},
                   {cacertfile, "path/to/ca.pem"}]}.
```

---
### Deauthentication

This command revokes the currently stored API token and removes the local
credentials:

```shell
rebar3 grisp-io deauth
```

If the token was encrypted, enter the local password used when authenticating.
If the token has already expired or been revoked, the stale local credentials
are still removed.

---
### Deploy

> [!IMPORTANT]
> You need an authentication token to run this command see: [authenticate](#authenticate)
> You need an uploaded package on `grisp.io` as well see: [upload](#upload)

This command allows you to update a grisp board using a package uploaded previously on `grisp.io`

This command has 2 options (mandatory options are marked with :exclamation:
- `--device` or `-d`: This option specifies the serial number of the target device :exclamation:
- `--package` or `-p`: This option specifies the full package name that needs to be deployed

> [!NOTE]
> :pushpin: If no package name is specified, it will use the informations contained in your `rebar.config` to deduce the package name
---
### Upload

> [!IMPORTANT]
> You need to authenticate first and request a token using [authenticate](#authenticate)

This command allows you to upload a package on `grisp.io`. Internally, this command will call `rebar3 grisp pack` and create
a new release package. Release packages are identified by 3 elements:
- The platform name (by default `grisp2`)
- The application name
- The release version in SemVer fashion (by default `0.1.0`)

This command has 2 options:
- `--force` or `-f`: This option will force an overwritting of the local and remote files of a given project and release
- `--refresh` or `-r`: Force software package building even if it already exists
---
### List

> [!IMPORTANT]
> You need to authenticate first and request a token using [Authentication](#authentication).

This command lists the update packages stored for your grisp.io account,
including their application, version, platform, and last-modified time.

```shell
rebar3 grisp-io list
```

---
### Delete

> [!IMPORTANT]
> You need to authenticate first and request a token using [Authentication](#authentication).

This command permanently deletes an update package stored in your grisp.io
account. Use the package identifier shown in the `NAME` column of
`rebar3 grisp-io list`:

```shell
rebar3 grisp-io delete grisp2.myapp.0.1.0.tar
```

When no package name is provided, the command remains backward compatible and
derives the package name from the current project's release and platform
configuration:

```shell
rebar3 grisp-io delete
```

Only one package name can be specified per invocation.

---
### Validate

> [!IMPORTANT]
> You need to authenticate first and request a token using [authenticate](#authenticate)

This command allows you to validate an update that has been deployed on a device

This command has 1 mandatory option:
- `--device` or `-d`: Used to specify the serial number of the device on which you want to validate the update

```shell
rebar3 grisp-io validate -d SERIAL_NUMBER
```

---
### Cancel

> [!IMPORTANT]
> You need to authenticate first and request a token using [Authentication](#authentication).

This command cancels the update running on a device linked to your grisp.io
account:

```shell
rebar3 grisp-io cancel -d DEVICE_IDENTIFIER
```

The `--device` (`-d`) option is mandatory. The platform is read from the
project's GRiSP configuration.

---
### Reboot

> [!IMPORTANT]
> You need to authenticate first and request a token using [Authentication](#authentication).

This command requests a reboot of a device linked to your grisp.io account:

```shell
rebar3 grisp-io reboot -d DEVICE_IDENTIFIER
```

The `--device` (`-d`) option is mandatory. The platform is read from the
project's GRiSP configuration.

---
### Version

```shell
rebar3 grisp-io version
===> Analyzing applications...
===> Compiling rebar3_grisp_io
rebar3_grisp_io: 1.0.0
```