Skip to main content

Configuring the CLI

info

Type greenframe help if you are lost!

Running a Scenario#

To debug a scenario with a real browser, use the open command:

greenframe open SCENARIO BASEURL

Example : greenframe open ./scenario.js https://greenframe.io

A Chromium or Google chrome browser is required to be installed on your computer to execute this command correctly. If it's not the case you can install chromium by typing the following command :

sudo apt-get install chromium-browser

Runing An Analysis#

The analyze command analyzes the carbon footprint of a browser running a user scenario. The analysis runs on GreenFrame servers, so the website must be accessible on the Internet (or exposed via an HTTP Tunnel):

greenframe analyze SCENARIO BASEURL --projectName PROJECT_NAME --threshold THRESHOLD --commitMessage "MY COMMIT MESSAGE" --branchName branch-name --samples SAMPLES

Example : greenframe analyze scenario.js https://greenframe.io --projectName PROJECT_NAME

--projectName Option#

To follow evolution of your analysis made on GreenFrame, use --projectName or -p to identify your project in GreenFrame.

At this time, you are allowed to pass everything you want.

The project name can be passed as the GREENFRAME_PROJECT_NAME environment variable in the CI environment.

If the project name is not specified through the command option or the environment variable, GreenFrame will automatically retrieve your git's project name and use it as the project name. Please note that the command must be executed in the corresponding git project for this to work.

Example: greenframe analyze scenario.js https://greenframe.io --projectName my_awesome_project

--threshold Option#

When using greenframe analyze in a CI environment, you typically want the build to fail if the carbon footprint exceeds a predefined threshold in Watt.hours. Use the --threshold option (or -t) for that.

Example : greenframe analyze scenario.js https://greenframe.io --threshold 0.05

--commitMessage Option#

When using greenframe analyze in a CI environment, you want to know for which commit GreenFrame made an analysis. GreenFrame CLI automatically retrieves it but in some CI you can't have access to .git folder and this detection will fail. You can pass it and override the commit message detection by using the --commitMessage option (or -c).

Example : greenframe analyze scenario.js https://greenframe.io --commitMessage "Add login feature"

--commitId Option#

When using greenframe analyze in a CI environment, you want to know for which commit GreenFrame made an analysis. GreenFrame CLI automatically retrieves it but in some CI you can't have access to .git folder and this detection will fail. You can pass it and override the commit ID detection by using the --commitId option.

Example : greenframe analyze scenario.js https://greenframe.io --commitId "SHA1_COMMIT_ID"

info

Please note if this variable is not set, you will not be able to perform automatic comparison with your default git branch. This git branch can be configured per project inside your settings directly in the application.

--branchName Option#

When using greenframe analyze in a CI environment, you want to know for which branch GreenFrame made an analysis. GreenFrame CLI automatically retrieves it but in some CI you can't have access to .git folder and this detection will fail. You can pass it and override the branch name detection by using the --branchName option (or -b).

Example : greenframe analyze scenario.js https://greenframe.io --branchName "feat/login"

--samples Option#

When using greenframe analyze in a CI environment, you might want to change the number of samples that are performed by the analysis in order to improve the precision. Use the --samples option (or -s). Its default value is 3.

Example : greenframe analyze scenario.js https://greenframe.io --samples 5

--distant Option#

When using greenframe analyze in a CI environment, you must have docker installed. The analysis will be performed locally and the GreenFrame CLI will start a container in order to run your scenario.

It's fast but if you have an unstable CI environment (e.g : Free tier), you might want to use a more stable runner.

GreenFrame provides you with distant workers to run with your CLI. By passing --distant (or -d) the GreenFrame CLI will execute this analysis on our servers.

Example : greenframe analyze scenario.js https://greenframe.io --distant

info

Please take in account that your analysis can be queued for a certain amount of time before being executed with the distant mode.

Using a .greenframe.yml configuration file#

To facilitate the configuration of GreenFrame CLI, you can add a .greenframe.yml file at the root of your project.

baseURL: YOUR_APP_BASE_URL
scenario: PATH_TO_YOUR_SCENARIO_FILE
projectName: YOUR_PROJECT_NAME
samples: 3 (or any number between 2 and 10)
threshold: 0.1 (or any number in wH)
distant: false (pass it to true if want to use the GreenFrame worker system instead of your CI)

If you use this configuration file, to launch an analysis by using GreenFrame CLI will be simplified : greenframe analyze

Please note that CLI arguments will take precedence over the configuration file.

You can also provide a path to your configuration file by using the --configFile or -C argument.

Example: greenframe analyze --configFile ./config/mygreenframefile.yml

Running multi-container analyses#

To analyze your entire application and provide a more accurate footprint, you should also monitor your whole infrastructure with your back-end and your database.

In your .greenframe.yml you can add the following lines:

containers:
- "CONTAINER_NAME"
- "ANOTHER_CONTAINER_NAME"
databaseContainers:
- "DATABASE_CONTAINER_NAME"
info

Please note that the multi-container analysis cannot be performed with --distant flag.

You can fix your containers name in Docker compose by using the container_name field or directly inside the docker command with the --name attribute

After this, you can perform an analysis as usual:

Example: greenframe analyze

Your entire app will be analyzed and will result in a more accurate footprint.

Running a GreenFrame Analyze with Custom Hosts#

Sometimes your app should run on a specific URL in local which is not localhost. You have written in your /etc/hosts a mapping between 127.0.0.1 and your specific URL.

GreenFrame CLI cannot access to this mapping and you should pass it to the CLI during an analyze in order to let the CLI to access to theses URLs.

In your .greenframe.yml you can add the following lines:

extraHosts:
- "extra-host.com"
- "another.extra-host.com"