Metadata-Version: 2.4
Name: finopspp
Version: 0.2.1
Summary: CLI tool used for the FinOps++ Assessment.
Author: Travis Salas Cox
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click==8.2.1
Requires-Dist: click-didyoumean==0.3.1
Requires-Dist: click-help-colors==0.9.4
Requires-Dist: GitPython==3.1.62
Requires-Dist: jinja2==3.1.6
Requires-Dist: pandas==2.3.2
Requires-Dist: pydantic==2.12.0
Requires-Dist: pyyaml==6.0.2
Requires-Dist: rich==14.2.0
Requires-Dist: semver==3.0.4
Requires-Dist: textual==8.2.3
Requires-Dist: xlsxwriter==3.2.5
Provides-Extra: validation
Requires-Dist: pylint==4.0.3; extra == "validation"
Provides-Extra: testing
Requires-Dist: pytest==9.0.1; extra == "testing"
Dynamic: license-file

# CLI Tool

To aid with formatting, transforming, and using the yaml specification files, we built the `finopspp` CLI tool. Currently, to use it you have to build it from source from this repository. To do this, please read through [Developing the finopspp CLI tool](/guidelines/development.md#developing-the-finopspp-cli-tool) in the [development](/guidelines/development.md) guide.

Below we will go through a few of the key commands this CLI tools provides. If you have the tool installed, we encourage you to play around with the tools and look at commands not discussed below, such as the `finopspp version` command.

## Generating commands

The most useful commands to use with `finopspp` will be related to generate some aspect of the framework. Either markdown documentation or Excel files.

### Framework Markdown & Assessment Worksheet

The most useful (or powerful) of the most useful commands offered by `finopspp` is the command used to generate the framework markdown and assessment worksheet files for a profile. The framework markdown files are designed to give a one-stop shop for getting an overview, in tabular format, of how a framework (generated from a profile) is logically grouped together. While the assessment worksheet is used for scoring the priority weighted maturity of an organization against action completeness for a profile.

To generate the markdown for the framework overview and assessment excel file, make sure that the profile you desire to use is included under [specifications/profiles](https://github.com/FinOpsPP/Framework-Assessment/tree/main/specifications/profiles/) or, if need be, create a new profile.

Then run the following

```{sh}
finopspp generate assessment --profile="<desired-profile-name>"
```

you can run `finopspp generate assessment --help` to see the list of profile options. The files generated by this command can be found in [assessments](https://github.com/FinOpsPP/Framework-Assessment/tree/main/assessments/). Simply search in this directory for a `<desired-profile-name>` subdirectory. This subdirectory will include your framework markdown and assessment.

### Components Markdown

These files are designed to be generally more human readable and easier to navigate than the yaml specifications. The four components supported directly correlate with the four specification types used currently by `finopspp`. Which are `profiles`, `domains`, `capabilities`, and `actions`; and can be found in subdirectories of the same names under.

- [components/profiles](https://github.com/FinOpsPP/Framework-Assessment/tree/main/components/profiles/)
- [components/domains](https://github.com/FinOpsPP/Framework-Assessment/tree/main/components/domains/)
- [components/capabilities](https://github.com/FinOpsPP/Framework-Assessment/tree/main/components/capabilities/)
- [components/actions](https://github.com/FinOpsPP/Framework-Assessment/tree/main/components/actions/)

> [!NOTE]
> `profiles` markdown files are generated and offered on an as-best-as-possible basis. This is because of the customization allowed for this type. Generally it is recommended to use the Framework markdown to get a true overview of the profiles. But we include them for the sake of compilation.

To generate the files in these folder fresh from the yaml files, you can call the following command

```{sh}
finopspp generate components --specification-type=<desired-spec-type> <spec-id-or-all-or-diff>
```

> [!NOTE]
> The serialization number for a markdown file uses the schema `xxx.md`, where `xxx` will match the serialization number of the yaml specification for the profile or component.

Using this command, you can generate a component markdown file for a specific specification ID, for a specific specification type. If you pass in `all`, you can generate the component markdown files for all specifications under a given type specific type. While passing `diff` will generate component markdown files for the specifications of a given type that have changed when compared to the `main` branch of the repository. This last option requires the `git` tool to be installed. For more on that please read the [Development](/guidelines/development.md) Guideline.

## Specification commands

A set of utility commands that can do a number of different actions relevant to the yaml specifications. This range from showing the [OpenAPI schema](https://www.openapis.org/what-is-openapi) for the different specifications types, to full updates of the specifications via changes to a specification model derived using [Pydantic](https://docs.pydantic.dev/latest/concepts/models/).

### Validation

One of the most useful command is the validation command

```{sh}
finopspp specifications validate --specification-type=<desired-spec-type> <spec-id-or-all-or-diff>
```

With this, you can validate a specific specification by ID and type. While, by passing in `all`, you can validate all specification for a specific type. Or, if you have `git` installed, you can pass `diff` which will validate only the specifications of a given type that have changed when compared to the `main` branch of the repository.

Validation is relatively strict, and makes uses of Pydantic [validator](https://docs.pydantic.dev/latest/concepts/validators/). Validation failures are logged to stderr for the user, and results in a failure return code on the command if any specifications fail to validate during a run.

### Update

Another really useful command is `update`, which can be called with the following

```{sh}
finopspp specifications update --specification-type=<desired-spec-type> <spec-id-or-all>
```

Giving a specification type, and corresponding changes to the specification type's [model definitions](/src/models/definitions.py), you can update that specification type's files by ID or all at once to match the new definition. Some updates work out-of-the-box, like adding/removing fields. While other more complex updates, such as renaming a field or changing the order of fields in the schema, are allowed by creating custom alias for fields or by using Pydantic [model_serializer](https://docs.pydantic.dev/latest/api/functional_serializers/#pydantic.functional_serializers.model_serializer).

### New

The `new` command will allow you to create new specification files from smart defaults, which can be found, in code, under [models/defaults.py](/src/models/defaults.py). The new specification file, created for a desired specification type, can be used as template to fill-in until the specification is in a state that is ready to be publish.

The command to create these new specification is simply

```{sh}
finopspp specifications new --specification-type=<desired-spec-type> <desired-id>
```

> [!IMPORTANT]
> If you are creating a new profile, make sure to select a Title for the specification that has not already been used. Otherwise this will cause a collision issues with the generate assessment command.

The only requirement is that the desired ID be unique. If it has been used previously, an error will be returned and the specification file will not be created.
