climeter 0.1.7

The billing layer for AI tools — CLI Billing & Metering SDK

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

Method	Description
meter.configure(api_key, tool_slug, api_url)	Configure the global meter
@meter.track(price, name, metadata)	Decorator — records event after each call
meter.track_usage(name, price, metadata)	Sync context manager
meter.track_usage_async(name, price, metadata)	Async context manager
meter.record(name, price, metadata)	Manual event recording
meter.flush()	Force-flush pending events
meter.shutdown()	Flush and stop background thread
meter.status()	Returns {configured, tool_slug, queue_size}

---

CLI

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

---

License

MIT © CLIMeter