# run

## Usage

`prism run` is used to execute a *Python-based* Prism project. This is distinct from a PySpark-based Prism project, in which case you would need to use the [`spark-submit`](https://docs.runprism.com/v0.1.9rc2/cli/spark-submit) command.

```
Usage: prism run [-h] [--modules [X.py Y.py ...]] [--all-upstream] [--all-downstream] [--full-tb] [-l] [--vars [A=a B=b ...]] [--context '{}']

Execute your Prism project

Options:
  -h, --help            show this help message and exit

Command Options:
  --modules [X.py Y.py ...]
                        Path to script(s) that you want to run; if not specified, all modules in project are run
  --all-upstream        Run all modules upstream of --modules
  --all-downstream      Run all modules downstream of --modules

General Options:
  --full-tb             Display the full traceback for errors in the project; default is False
  -l, --log-level       Log level, must be one of `info`, `warn`, `error`, or `debug`. Default is `info`
  --vars [A=a B=b ...]  Prism variables as key-value pairs `key=value`. These overwrite any variable definitions in `prism_project.py`. All values are read as strings.
  --context '{}'        Prism variables as JSON. Cannot co-exist with --vars. These overwrite any variable definitions in `prism_project.py`.
```

Here's what `prism run` does under the hood:

1. It first executes the [`prism compile`](https://docs.runprism.com/v0.1.9rc2/cli/compile) command.  
   * Recall that this command parses the tasks contained in the `modules/` folder for `tasks.ref(...)` calls, creates the dependency graph, and stores the project metadata (e.g., the configuration, the `tasks.ref(...)` calls, the targets, and the [topological sort](https://en.wikipedia.org/wiki/Topological_sorting)) in a `manifest`.
2. It parses the `prism_project.py` file. It also parses the configuration files listed within `prism_project.py` (e.g., [`PROFILE_YML_PATH`](https://docs.runprism.com/v0.1.9rc2/fundamentals/config-files/profile-yml), [`TRIGGERS_YML_PATH`](https://docs.runprism.com/v0.1.9rc2/fundamentals/config-files/triggers-yml)).
3. It creates a pipeline consisting of the global variables from `prism_project.py` and the adapters from `profile.yml`.
4. It executes the tasks in a [topological order](https://en.wikipedia.org/wiki/Topological_sorting).

## Example

Here's what the output looks like in Terminal:

```
$ prism run
--------------------------------------------------------------------------------
<HH:MM:SS> | INFO  | Running with prism v0.1.9rc2...
<HH:MM:SS> | INFO  | Found project directory at /Users/my_first_project
 
<HH:MM:SS> | INFO  | RUNNING EVENT 'parsing prism_project.py'................................................ [RUN]
<HH:MM:SS> | INFO  | FINISHED EVENT 'parsing prism_project.py'............................................... [DONE in 0.03s]
<HH:MM:SS> | INFO  | RUNNING EVENT 'module DAG'.............................................................. [RUN]
<HH:MM:SS> | INFO  | FINISHED EVENT 'module DAG'............................................................. [DONE in 0.01s]
<HH:MM:SS> | INFO  | RUNNING EVENT 'creating pipeline, DAG executor'......................................... [RUN]
<HH:MM:SS> | INFO  | FINISHED EVENT 'creating pipeline, DAG executor'........................................ [DONE in 0.01s]
 
<HH:MM:SS> | INFO  | ===================== tasks 'vermilion-hornet-Gyycw4kRWG' =====================
<HH:MM:SS> | INFO  | 1 of 1 RUNNING EVENT 'module01.py'...................................................... [RUN]
<HH:MM:SS> | INFO  | 1 of 1 FINISHED EVENT 'module01.py'..................................................... [DONE in 0.01s]
 
<HH:MM:SS> | INFO  | Done!
--------------------------------------------------------------------------------
```

## Required arguments

There are no required arguments for `run`.

## Optional arguments

Here are the optional arguments you can run with `run`:

* `--full-tb` : Display full traceback if errors arise at any stage of the pipeline
* `--log-level`: Log level, one of `info`, `warn`, `error`, or `critical`.
* `--vars`: Prism variables as key-value pairs `key=value`. These overwrite any variable definitions in `prism_project.py`. All values are read as strings.
* `--context`: Prism variables as JSON. Cannot co-exist with `--vars`. These overwrite any variable definitions in `prism_project.py`.
* `--modules`: Paths to modules that you want to run; if not specified, all modules in pipeline are run. Paths should be specified relative to the `modules` folder.
* `--all-upstream`: Run all modules upstream of those specified in `--modules`
* `--all-downstream`: Run all modules downstream of those specified in `--modules`