Documentation — Carbonah

Installation

Install Carbonah with a single command. Binaries are available for macOS, Linux, and Windows.

Quick install (macOS / Linux)

Terminal

$ curl -fsSL https://carbonah.dev/install.sh | sh

Homebrew (macOS)

Terminal

$ brew install andrevanzuydam/tap/carbonah

Chocolatey (Windows)

PowerShell

> choco install carbonah

From source (Rust)

Terminal

$ cargo install carbonah

Download binaries

Pre-built binaries for all platforms are available on the Releases page.

Quick Start

Three steps to your first carbon measurement:

1. Lint your code

Terminal

$ carbonah lint ./src # Scans for carbon-inefficient patterns (N+1 queries, polling loops, etc.)

2. Analyse dependencies

Terminal

$ carbonah analyse requirements.txt # Finds oversized, duplicate, or dev-only packages

3. Measure a command

Terminal

$ carbonah measure -- python app.py # Wraps any command and calculates its SCI carbon score

Tip: Carbonah generates a CARBONAH.md scorecard in your project root after linting. Commit it to track your carbon grade over time.

Measuring Any Command

The measure command wraps any executable and calculates its carbon intensity using the ISO/IEC 21031:2024 SCI formula.

Key syntax: carbonah measure [options] -- <your-command>
The -- separates carbonah flags from the command being measured.

Measure a Python app

Terminal

$ carbonah measure -- python app.py

Measure a compiled binary

Terminal

$ carbonah measure -- ./myapp --port 8080

Measure a build

Terminal

$ carbonah measure --region ZA -- cargo build --release

Measure with CI gating

Terminal

$ carbonah measure --fail-on 100 -- ./run-tests.sh # Exits non-zero if SCI exceeds 100 gCO2eq/run

Flags

Flag	Description	Default
`--region <code>`	ISO country or cloud region (e.g. `ZA`, `aws-us-east-1`)	Auto-detect
`--format <fmt>`	Output format: `text`, `json`	text
`--fail-on <n>`	Exit 1 if SCI exceeds n gCO2eq/run	—
`--warn-on <n>`	Print warning if SCI exceeds n	—

Works with anything: Node.js servers, PHP apps, Docker builds, test suites, compiled binaries, shell scripts — if you can run it, Carbonah can measure it.

Lint

Scan source code for carbon-inefficient patterns across 12 languages.

Terminal

$ carbonah lint ./src $ carbonah lint ./src --format markdown # generates CARBONAH.md $ carbonah lint ./src --fail-on E002 # fail CI on N+1 queries

Flags

Flag	Description	Default
`--format <fmt>`	`text`, `json`, `sarif`, `markdown`	text
`--fail-on <rule>`	Exit 1 if rule is triggered	—
`--config <path>`	Path to `.carbonah.toml`	Auto-detect

Supported languages

Python, JavaScript, TypeScript, PHP, Ruby, Go, Rust, C, C++, C#, Java, Delphi/Pascal

See the full Rules Reference for all lint rule codes and examples.

Analyse

Scan dependency manifests for oversized, duplicate, or unnecessary packages.

Terminal

$ carbonah analyse requirements.txt $ carbonah analyse composer.json $ carbonah analyse package.json --format json

Supported manifests

requirements.txt, pyproject.toml, Pipfile, composer.json, package.json, Cargo.toml, go.mod, Gemfile, .dproj

Session

Track your development machine's carbon emissions over time with a background daemon.

Terminal

$ carbonah session start # start background tracking $ carbonah session status # check running total $ carbonah session stop # stop and print full report $ carbonah session reset # clear and start fresh

The daemon samples CPU usage every 30 seconds with near-zero overhead. The final report includes energy breakdown, carbon totals, and extrapolations (per hour, per day, per year, per team).

Configuration

Create a .carbonah.toml in your project root to set defaults:

# .carbonah.toml [measure] region = "ZA" # ISO country or cloud region hardware_profile = "apple-macbook-air-m2" [thresholds] warn_on = 10.0 # warn if SCI > 10 gCO2eq/run fail_on = 100.0 # exit 1 if SCI > 100 [output] format = "text" # text | json | markdown

Inline Suppression

Suppress specific rules on a per-line basis with a comment:

example.py

# carbonah:ignore E002 for user in users: dept = db.query("SELECT * FROM departments ...") # This query won't be flagged

The comment must appear on the line immediately before the flagged code. Supports all rule codes.