# CLI Utility Scripts

This documents the various utility scripts that are provided with the project
whose purposes are to support the operation of the application in one way or
another.

To get a list of the available scripts/flask commands that can be run, do:

```sh
FLASK_APP="main.py" flask --help
```

With that, you should get a list of commands, which as of 2023-05-26 are:

```sh
. . . output truncated to save space ...

Commands:
  apply-migrations     Apply the dabasase migrations.
  assign-system-admin  Assign user with ID `user_id` administrator role.
  init-dev-clients     Initialise a development client for OAuth2 sessions.
  init-dev-users       Initialise development users for OAuth2 sessions.
  routes               Show the routes for the app.
  run                  Run a development server.
  shell                Run a shell in the app context.
```

*NB*: You can simply do `export FLASK_APP="main.py"` at the beginning of your
shell session and then just run the commands without prepending with the
`FLASK_APP="main.py"` declaration.

## Registering/Setting a User as System Administrator

You can register an new user and set them as the system administrator with:
```sh
FLASK_APP="main.py" flask register-admin
```

A typical session might go something like:
```sh
$ FLASK_APP="main.py" flask register-admin
Enter the user's name: CLI SysAdmin
Enter the administrator's email: someadmin@gmail.com
Enter password: 
Confirm password: 
$
```

You can also run the script directly (without flask) with:
```sh
$ python3 -m scripts.register_sys_admin /home/frederick/genenetwork/gn3_files/db/auth.db
```
changing "/home/frederick/genenetwork/gn3_files/db/auth.db" to the path to your database file.

### Setting an Existing User to System Administrator

If a user already exists in your system, and you want to make that user system admin, you could do it with:

```sh
FLASK_APP="main.py" flask assign-system-admin 5b15ef01-a9d7-4ee4-9a38-fe9dd1d871b8
```

You can retrieve the user ID from the (SQLite) database, with something like:

```sh
$ sqlite3 /home/frederick/genenetwork/gn3_files/db/auth.db
SQLite version 3.40.0 2022-11-16 12:10:08
Enter ".help" for usage hints.
sqlite> SELECT * FROM users;
0ad1917c-57da-46dc-b79e-c81c91e5b928|test@development.user|Test Development User
9c5d4ddf-c361-4133-add3-9ab9845bb9f2|fredtest02@gmail.com|A New Group Member
b4a8ed7a-a878-4884-94e0-26d3fe0c56a3|fredleader@gmail.com|Frederick the Group Leader
```

## Make Existing Data Publicly Visible

This will only act on any existing data that is not already linked with a user
group in the new auth system.

This can be run using flask with

```sh
FLASK_APP="main.py" flask make-data-public
```

which will use the application's configuration settings for the
auth(entic|oris)ation database and the MariaDB database.

You could also run the script directly with:

```sh
python3 -m scripts.migrate_existing_data AUTHDBPATH MYSQLDBURI
```

where `AUTHDBPATH` and `MYSQLDBURI` are replaced with the appropriate values,
e.g.

```sh
python3 -m scripts.migrate_existing_data \
    /home/frederick/genenetwork/gn3_files/db/auth.db \
    mysql://webqtlout:webqtlout@127.0.0.1:3307/db_webqtl
```

## List Available Routes

```sh
FLASK_APP="main.py" flask routes
```

## Drop Into a Python Shell

```sh
FLASK_APP="main.py" flask shell
```

## Development Scripts

The commands in this section are meant for easing development and are not to be
run in a production environment.

### Setting up a Sample User for Development

```sh
FLASK_APP="main.py" flask init-dev-users
```

That will initialise your development database with a development user with the
following details:

- User ID: 0ad1917c-57da-46dc-b79e-c81c91e5b928
- Email: test@development.user
- Password: testpasswd

### Setting up Sample OAuth2 Client for Development

```sh
FLASK_APP="main.py" flask init-dev-clients
```