## CLI usage overview

```

duffy --help

```

The rewritten version of Duffy includes a lot of functionality under one umbrella, making it convenient for the maintainers to operate upon the following things from a single command.

1. [Configuring the variables](https://github.com/CentOS/duffy/wiki/Usage#the-config-command)

2. [Migrating the database](https://github.com/CentOS/duffy/wiki/Usage#the-migration-command)

3. [Serving the primary web application](https://github.com/CentOS/duffy/wiki/Usage#the-serve-command)

4. [Serving the legacy web application](https://github.com/CentOS/duffy/wiki/Usage#the-serve-legacy-command)

5. [Setting up the database](https://github.com/CentOS/duffy/wiki/Usage#the-setup-db-command)

6. [Interact with a running instance](https://github.com/CentOS/duffy/wiki/Usage#the-shell-command)

7. Starting a backend processor 

```

Usage: duffy [OPTIONS] COMMAND [ARGS]...

Options:

  -c, --config FILE  Read option defaults from the specified YAML file.

                     [default: /etc/duffy.yaml]

  --version          Show the version and exit.

  --help             Show this message and exit.

Commands:

  config        Check and dump configuration.

  migration     Handle database migrations.

  serve         Run the Duffy web application server.

  serve-legacy  Serve the Duffy Metaclient for Legacy Support app.

  setup-db      Create tables from the database model.

  shell         Run an interactive shell.

  worker        Start a Celery worker to process backend tasks.

```

We will go in detail about each of the aforementioned functionalities in the sections below.

### The `config` command

To understand how the config command makes use of a YAML-based configuration, please refer to [the configuration documentation](https://github.com/CentOS/duffy/wiki/Configuration).

```

duffy config --help

```

Duffy is written to be flexible enough to allow for smaller configurations (like setting log levels for an operation, selecting port number for publishing etc.) to be quickly appended to the command as options as well as for bigger configurations (like setting up the worker environment, pointing to Ansible Playbook locations etc.) to be descriptively specified in a YAML-based configuration file. The subcommands included in the CLI allows for verifying the correctness of and, dumping merged configurations of the latter kind.

```

Usage: duffy config [OPTIONS] COMMAND [ARGS]...

  Check and dump configuration.

Options:

  --help  Show this message and exit.

Commands:

  check  Validate configuration structure.

  dump   Dump merged configuration.

```

### The `migration` command

```

duffy migration --help

```

With the use of SQLAlchemy, the interactions with the database are abstracted enough such that, Duffy becomes agnostic of the kind of database that it makes use of. It does allow for migrating schemas and managing changes with the use of the said command. The command requires URL of the database for both synchronous and asynchronous operations with it. As Duffy is agnostic of what database it makes use of, any kind of relational database can be used but we strongly recommend the use of Postgres.

```

Usage: duffy migration [OPTIONS] COMMAND [ARGS]...

  Handle database migrations.

Options:

  --help  Show this message and exit.

Commands:

  create      Create a new migration.

  db-version

  downgrade

  upgrade

```

### The `serve` command

```

duffy serve --help

```

The primary web server is the main interface with which clients can connect to Duffy and perform tasks like create a session, request baremetal or virtual nodes etc. The server can be started up using the aforementioned command by providing parameters like host address, port number, log level etc. These variables can either be passed as options appended to a command or be listed under the `app` section of the YAML-based configuration file. 

```

Usage: duffy serve [OPTIONS]

  Run the Duffy web application server.

  Duffy is the middle layer running ci.centos.org that manages the

  provisioning, maintenance, teardown and rebuild of the Nodes (physical

  hardware and virtual machines) that are used to run the tests in the CI

  Cluster.

Options:

  --reload / --no-reload          Automatically reload if the code is changed.

  -H, --host TEXT                 Set the host address to listen on.

  -p, --port INTEGER RANGE        Set the port value.  [1<=x<=65535]

  -l, --loglevel [critical|error|warning|info|debug|trace]

                                  Set the log level.

  --help                          Show this message and exit.

```

### The `serve-legacy` command

```

duffy serve-legacy --help

```

The legacy web server is the secondary interface for existing clients of legacy Duffy that provides for a 1:1 compatibility with the older endpoints. Clients can connect here to do the same tasks that they could in the primary interface with minimal changes to the workflow. As like the primary interface, this command can be customized with the use of appended options or as variables under the `metaclient` section of the YAML-based configuration file.

```

Usage: duffy serve-legacy [OPTIONS]

  Serve the Duffy Metaclient for Legacy Support app.

  Duffy is the middle layer running ci.centos.org that manages the

  provisioning, maintenance and teardown / rebuild of the Nodes (physical

  hardware for now, VMs coming soon) that are used to run the tests in the CI

  Cluster.

  This metaclient exposes older endpoints for legacy support and connects them

  to the path operations introduced by the newer version of the Duffy

  endpoint, until the support for the older endpoints is deprecated.

Options:

  --reload / --no-reload          Automatically reload if the code is changed.

  -H, --host TEXT                 Set the host address to listen on.

  -p, --port INTEGER RANGE        Set the port value.  [1<=x<=65535]

  -D, --dest TEXT                 Set the destination address of Duffy

                                  deployment.

  -l, --loglevel [critical|error|warning|info|debug|trace]

                                  Set the log level.

  --help                          Show this message and exit.

```

### The `setup-db` command

```

duffy setup-db --help

```

According to the database of the maintainer's choice, Duffy can set up tables from the included database model. To facilitate for a development and testing environment, contributors can also populate the created database with test data - although the same database must not be used in a production environment. The command requires URL of the database for both synchronous and asynchronous operations with it. As Duffy is agnostic of what database it makes use of, any kind of relational database can be used but we strongly recommend the use of Postgres.

```

Usage: duffy setup-db [OPTIONS]

  Create tables from the database model.

Options:

  --test-data / --no-test-data  Initialized database with test data.

  --help                        Show this message and exit.

```

### The `shell` command

```

duffy shell --help

```

Performing management tasks on a currently running instance of Duffy is made possible with the inclusion of an interactive shell - that can be run on the same environment as the one where the application is deployed. The shell can be managed either by a Python interpreter or an IPython interpreter - with IPython providing additional enrichment to a normal REPL-based interface. Maintainers can use the shell to perform CRUD operations on the attached database with respect to sessions, tenants, nodes, projects etc.

```

Usage: duffy shell [OPTIONS]

  Run an interactive shell.

Options:

  -t, --shell-type [python|ipython]

                                  Type of interactive shell to use.

  --help                          Show this message and exit.

```