# Xerg — Complete Reference for LLMs

Xerg is the economic control layer for AI agents. It audits, tracks, and optimizes agent inference spend across any model provider.

## Installation

```bash
npm install -g @xerg/cli
# or run directly
npx @xerg/cli audit
```

## Core Commands

### Local audit
```bash
xerg audit                        # Audit local OpenClaw logs
xerg audit --since 24h            # Last 24 hours only
xerg audit --json                 # Machine-readable JSON output
xerg audit --compare              # Compare against previous audit
```

### Remote audit
```bash
xerg audit --remote user@host     # Audit a remote VPS over SSH
xerg audit --remote-config ~/.xerg/remotes.json  # Multi-source audit
```

### Push to dashboard
```bash
xerg audit --push                 # Push results to xerg.ai/dashboard (Pro workspace required)
xerg audit --push --dry-run       # Inspect payload without sending
```

### CI gating
```bash
xerg audit --fail-above-waste-rate 0.30   # Exit 3 if waste > 30%
xerg audit --fail-above-waste-usd 50      # Exit 3 if waste > $50
```

## Exit Codes

- 0: Success
- 1: Runtime error
- 2: No data found
- 3: Threshold exceeded (CI gating)

## API Endpoints

Base URL: `https://api.xerg.ai`

### POST /v1/audits
Push an audit payload. Requires `Authorization: Bearer <api_key>`.

Request body: `AuditPushPayload` (see Wire Schema below).

### GET /v1/audits
List audits for your workspace. Query params: `?since=24h`, `?source=production`, `?limit=50`.

### GET /v1/audits/:id
Single audit detail.

### GET /v1/trends
Time-series metrics. Query params: `?since=30d`, `?source=production`, `?metric=wasteRate`.
Supported metrics: totalSpend, wasteSpend, wasteRate, runCount, callCount.

## Wire Schema (AuditPushPayload)

The push payload is a versioned, privacy-safe wire schema. Types are published as `@xerg/schemas` on npm.

```typescript
interface AuditPushPayload {
  version: 1;
  summary: {
    auditId: string;
    generatedAt: string;
    comparisonKey: string;
    runCount: number;
    callCount: number;
    totalSpendUsd: number;
    wasteSpendUsd: number;
    opportunitySpendUsd: number;
    structuralWasteRate: number;
    findings: WireFinding[];
    spendByWorkflow: SpendBreakdown[];
    spendByModel: SpendBreakdown[];
    comparison?: WireComparison | null;
  };
  meta: {
    cliVersion: string;
    sourceId: string;
    sourceHost: string;
    environment: "local" | "remote" | "ci";
    pushedAt: string;
  };
}

interface WireFinding {
  id: string;
  classification: "waste" | "opportunity";
  confidence: "high" | "medium" | "low";
  kind: string;
  title: string;
  summary: string;
  scope: string;
  scopeId: string;
  costImpactUsd: number;
}
```

## Authentication

- Dashboard: Clerk session via web sign-in
- CLI: `XERG_API_KEY` environment variable or `~/.xerg/config.json`
- API keys are Clerk-managed and scoped to workspaces

## Pricing

- Open Source CLI: Free forever, local-first, no account required
- Pro ($29/seat/mo): Hosted dashboard, hosted MCP server, workspace API keys, unlimited pushes
- Enterprise: Custom pricing for SSO, self-hosting, and policy controls

## Links

- Website: https://xerg.ai
- Dashboard: https://xerg.ai/dashboard
- MCP: https://xerg.ai/mcp
- GitHub: https://github.com/xergai/xerg
- npm CLI: https://www.npmjs.com/package/@xerg/cli
- npm schemas: https://www.npmjs.com/package/@xerg/schemas
- Pilot program: https://xerg.ai/pilot