climeter

Usage-based metering and billing for CLI tools and AI agents — Python SDK.

🌐 climeter.ai · 📖 Docs

Install

pip install climeter

Python 3.8+. Zero runtime dependencies (stdlib only).

Quick Start

from climeter import meter

meter.configure(api_key="clmtr_...", tool_slug="my-tool")

@meter.track(price=0.01)
def search(query: str):
    return do_search(query)

Or set environment variables and skip configure():

export CLIMETER_API_KEY=clmtr_...
export CLIMETER_TOOL_SLUG=my-tool

Usage

Decorator

from climeter import meter

@meter.track(price=0.01)
def search(query: str):
    return do_search(query)

# Async — same decorator
@meter.track(price=0.01)
async def search_async(query: str):
    return await do_search_async(query)

Context manager

with meter.track_usage("search", price=0.01):
    result = do_search(query)

# Async
async with meter.track_usage_async("search", price=0.01):
    result = await do_search_async(query)

Manual

meter.record("search", price=0.01, metadata={"query_len": len(query)})

Consumer Usage

If you're calling CLIMeter-powered tools as a user (not building them), use the call() function:

from climeter import call, InsufficientBalanceError

try:
    result = call("tool-uuid-here")
    print(f"Success — balance remaining: ${result['balance_remaining']:.4f}")
except InsufficientBalanceError as e:
    print(f"Out of credits. Top up at: {e.checkout_url}")

The call deducts from your CLIMeter wallet (or free tier). If balance is insufficient, InsufficientBalanceError is raised with a checkout_url to top up.

API

CLI

climeter init      # set up API key
climeter status    # show current config
climeter diagnose  # test connection

License

MIT © CLIMeter