Skip to content

Commit

Permalink
Merge pull request #73 from Green-Software-Foundation/update-cli-alia…
Browse files Browse the repository at this point in the history
…s-doc

chore(docs): updated docs by adding shortcuts info
  • Loading branch information
jmcook1186 authored May 9, 2024
2 parents 90de238 + 3923cd8 commit d32d58e
Show file tree
Hide file tree
Showing 2 changed files with 44 additions and 12 deletions.
20 changes: 13 additions & 7 deletions docs/major-concepts/if.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,24 +9,31 @@ sidebar-position: 3
`ie` is a command line tool that computes [Manifest files](manifest-file.md).
It is the portal allowing users to interact with the Impact Framework.

The available options are:
The available options and their shortcuts are:

- `--manifest` or `-m`: path to an input manifest file
- `--output` or `-o` (optional): path to the output file where the results as saved
- `--stdout` or `-s` (optional): prints the output to stdout (console)
- `--override-params` or `-p` (optional): if you are an advanced user and you want to override our standard set of parameters and their definitions, you can provide the path to an alternative file as an argument to this command.
- `--help` or `-h`: prints out help instruction

- `--manifest`: path to an input manifest file
- `--output` (optional): path to the output file where the results as saved, if none is provided it prints to stdout.
- `--override-params` (optional): if you are an advanced user and you want to override our standard set of parameters and their definitions, you can provide the path to an alternative file as an argument to this command.

The only required command is `--manifest`. Without a valid path to a manifest file, `ie` has nothing to execute.

To use `ie`, you must first [write a manifest file](../users/how-to-write-manifests.md). Then, you can simply pass the path to the manifest file to `ie` on the command line.

```sh
ie --manifest /my-manifest.yml
ie --manifest /my-manifest.yml
## or using aliases
ie -m /my-manifest.yml
```

You can also pass a path where you would like to save the output file to. For example:

```sh
ie --manifest ./my-manifest.yml --output ./my-results.yml
## or using aliases
ie -m ./my-manifest.yml -o ./my-results.yml
```

> Note that you also need to add some config to your manifest file to enable exporting to a file. The config is as follows:
Expand All @@ -37,7 +44,6 @@ initialize:
```



If you omit the `--output` command, your results will be displayed in the console.
If you omit the `--output` command, your results won't be displayed in the console. You should use `--stdout` command for that.

For more information on the `ie` commands see the [CLI reference documentation](../reference/cli.md).
36 changes: 31 additions & 5 deletions docs/reference/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,22 +10,32 @@ If you have globally installed our `if` npm package, you can invoke the CLI usin

`ie <args>`

## `--manifest`
## `--manifest` , `-m`

The `--manifest` flag is the only required flag and tells `ie` where to find the manifest file that you want to execute. This command expects to receive the path where your manifest file is saved, as shown in the following example:

```sh
ie --manifest examples/manifests/my-manifest.yml
```

## `--output`
## `--output` , `-0`

The `--output` flag is optional and is used for defining a path to save your output data. If you provide the `--output` command with a path, your output data will be saved as a `.yml` file to disk. If you omit this command, your output data will be displayed in the terminal.
The `--output` flag is optional and is used for defining a path to save your output data. If you provide the `--output` command with a path, you also need to specify the file type in the `initialize.outputs` block in your manifest file. With both pieces of information, IF will save your output data to file.

Here is an example of `--output` being used to define a path:

```sh
ie --manifest examples/manifests/my-manifest.yml --output examples/outputs/my-outdata.yml
ie --manifest examples/manifests/my-manifest.yml --output examples/outputs/my-outdata
## or using aliases
ie -m examples/manifests/my-manifest.yml -o examples/outputs/my-outdata
```

If `my-manifest.yml` contains the following config, then a `yaml` file named `my-outdata.yml` will be created, containing the results from your IF run.

```yaml
initialize:
output:
- yaml
```
### CSV export identifiers
Expand All @@ -35,10 +45,12 @@ If you want to save data to CSV, you have to select a specific metric to export.

```sh
ie --manifest demo.yml --output demo#carbon
## or
ie -m demo.yml -o demo#carbon
```


## `--override-params`
## `--override-params` , `-p`

The `override-params` command is used when you want to discard our recommended set of parameters and associated units and aggregation methods and instead provide your own. We do not recommend this, and if you use this feature you take full responsibility for any errors you introduce downstream, including unit or aggregation errors. This is why we hide the ability to override the parameters behind a CLI command - it is an advanced feature that you should only use if you really know what you are doing.

Expand All @@ -48,4 +60,18 @@ For example:

```sh
ie --manifest <your manifest> --override-params <path-to-your-params-file>
## or using aliases
ie -m <your manifest> -p <path-to-your-params-file>
```


## `--help` , `-h`

The `--help` command provides information about all available commands in order to help you easily find the command you need.

Example:
```sh
ie --help
## or using alias
ie -h
```

0 comments on commit d32d58e

Please sign in to comment.