Configuration

Configuration options

Pass any of these to init() or the CostTracker constructor. All fields are optional.

init() returns the CostTracker instance it created, which is stored globally and returned by getTracker() thereafter. Calling init() when a global instance already exists throws an Error — call close() or closeAsync() first to reset.

Environment variables

Environment variables are read during CostTracker construction (inside resolveConfig), so they take effect when init() is called.

Development mode

Pass environment: "development" (or set DEXCOST_ENV=development) to enable dev mode:

import { init, track } from 'dexcost';

init({ environment: 'development' });

await track({ taskType: 'my_task', customerId: 'local-test' }, async (task) => {
  task.recordCost('pdf_parser', 0.002);
});

In dev mode:

• Every llm_call and external_cost event is printed to stderr as it is recorded.
• Task completion is printed with aggregated cost totals.
• No data is written to the cloud — the EventPusher is not started.
• An API key is not required.

Dev mode is detected by isDevMode(), which returns true when enableDevMode() has been called (triggered by environment === "development" or DEXCOST_ENV=development).

Attribution & context

setContext() stores attribution values in an AsyncLocalStorage store so every subsequent auto-instrumented LLM call and track() call in the same async chain inherits them automatically. Call it once at the beginning of a request or job:

import { setContext, clearContext } from 'dexcost';

setContext({
  customerId: 'acme-corp',
  projectId: 'chatbot-v2',
  metadata: { tier: 'enterprise', region: 'us-east-1' },
  agent: 'support_agent',
});

setContext() uses AsyncLocalStorage.enterWith() (Node 18+), so it affects the remaining async chain without wrapping in a callback. For concurrent request isolation (e.g., an Express server), call setContext() inside per-request middleware — each request's async context is isolated by Node's AsyncLocalStorage.

getContext() returns the current DexcostContext, or undefined if setContext() has not been called. clearContext() replaces the current context with an empty object, effectively clearing it for the remaining async chain.

const ctx = getContext();
// ctx?.customerId, ctx?.projectId, ctx?.metadata, ctx?.agent

clearContext();

CLI

The dexcost CLI requires no API key and works offline against the local SQLite buffer.

dexcost status

Show the state of the local buffer:

dexcost status
dexcost status --db /path/to/buffer.db

Output includes: DB location, event count, task count, pending/synced event counts, last task timestamp, pricing engine version, and detected versions of LLM SDKs (openai, @anthropic-ai/sdk).

dexcost rates

Manage the per-service cost rate registry:

# List all registered rates
dexcost rates --list

# Import rates from a YAML file
dexcost rates --import rates.yaml

# Export current rates to a YAML file
dexcost rates --export rates.yaml

--import and --export can be combined. Import runs first, so --list after --import shows the loaded rates.

YAML format expected by --import:

rates:
  maps.googleapis.com:
    per: request
    cost_usd: "0.005"
  ocr-api.com:
    per: page
    cost_usd: "0.01"

YAML support requires js-yaml to be installed (npm install js-yaml).

dexcost scan

Static-analysis scan of your TypeScript/JavaScript codebase to find cost points that are not yet tracked:

dexcost scan ./src
dexcost scan ./src --generate-stubs

scan walks .ts, .tsx, .js, .jsx, and .mjs files (skipping node_modules, dist, .git, coverage), detects LLM calls (reported as auto-instrumentable), and flags external API calls that likely incur cost but have no recordCost() call nearby (reported as needing manual recording).

--generate-stubs prints ready-to-paste recordCost() snippets for each untracked cost point found. No API key or network connection is required.