carbonlint-cli

Measure and track the carbon footprint of your software projects from the command line.

CarbonLint CLI estimates the CO₂ emissions of your codebase by analyzing file types, sizes, and regional carbon intensity data. Use it locally or in CI/CD pipelines to set carbon budgets and catch regressions.

Install

npm install -g carbonlint-cli

Quick Start

# Initialize config in your project
carbonlint init

# Scan your project
carbonlint .

# Override region for a specific scan
carbonlint . --region EU-NORTH

# JSON output for CI pipelines
carbonlint . --json

# Fail the build if over budget (CI gate)
carbonlint . --ci --budget 50

Commands

| Command | Description | |---------|-------------| | carbonlint init | Create .carbonlintrc.json with default settings | | carbonlint [path] | Scan project and generate carbon report |

Options

| Flag | Description | Default | |------|-------------|---------| | -r, --region <region> | Carbon intensity region | GLOBAL-AVG | | -b, --budget <grams> | Carbon budget threshold in grams | 100 | | --profile <profile> | Hardware profile (laptop/desktop/server) | laptop | | --json | Output structured JSON | — | | --ci | Exit code 1 if over budget | — |

Regions

| Key | Location | gCO₂/kWh | |-----|----------|-----------| | EU-NORTH | Sweden | 25 | | US-WEST | California | 210 | | EU-WEST | Ireland | 300 | | US-EAST | Virginia | 380 | | ASIA-EAST | Japan | 470 | | GLOBAL-AVG | Global Average | 475 | | ASIA-SOUTH | India | 700 |

CI/CD Integration

GitHub Actions

- name: Carbon Check
  run: |
    npm install -g carbonlint-cli
    carbonlint . --ci --budget 50 --region US-WEST

GitLab CI

carbon-check:
  script:
    - npm install -g carbonlint-cli
    - carbonlint . --ci --budget 50

Configuration

Create .carbonlintrc.json with carbonlint init:

{
  "region": "GLOBAL-AVG",
  "hardwareProfile": "laptop",
  "pue": 1.0,
  "maxCarbon": 100,
  "failOnThreshold": false
}

Programmatic API

import { scanProject, loadConfig } from 'carbonlint-cli';

const config = loadConfig('.');
const result = scanProject('.', config);
console.log(result.greenScore);  // 0-100
console.log(result.carbon_grams);

License

MIT © Nishal K