---
title: Billing & Credits
description: >-
  Track usage, manage subscriptions, and monitor credit spending from the
  command line.
tags:
  - billing
  - credits
  - usage
  - subscription
  - pricing
---

  beginner

The ivybloom CLI is the scriptable surface for the platform, and billing commands let you track usage, manage subscriptions, and monitor credit spending without leaving the command line. Reach for them when a scripted workflow needs to check its own cost footprint — computational jobs consume credits based on the tool and AI model used — or when you want to manage billing programmatically rather than through the web interface. They give your automation visibility into its spend; for the full command surface, see the [CLI overview](/docs/cli).

## Billing & Credits

Track usage, manage subscriptions, and monitor credit spending from the command line.

---

## Overview

.bloom* uses a credit-based system for computational jobs. Credits are consumed based on the tool used and the AI model selected. The CLI provides full billing management without needing the web interface.

---

## Credit Balance

### Check Current Balance

```bash
ivybloom credits summary
```

**Table (default)**

```
BALANCE    DAILY USED    DAILY LIMIT    MONTHLY USED    MONTHLY LIMIT
1,250      87            500            312             5,000
```

**JSON**

```json
{
  "balance": 1250,
  "daily": {"used": 87, "limit": 500},
  "monthly": {"used": 312, "limit": 5000},
  "tier": "standard"
}
```

### Credit Statistics

```bash
ivybloom credits stats
```

Aggregated usage statistics broken down by tool and time period.

---

## Usage Tracking

### Credit History

```bash
ivybloom credits history
```

View a chronological log of credit transactions (charges and additions).

### Usage Trends

```bash
ivybloom credits trends
```

Shows usage trends and projections based on your recent activity. Helpful for estimating when credits will run out.

---

## Subscription Management

### View Current Plan

```bash
ivybloom billing status
```

Shows your current plan, renewal date, and included credits.

### List Available Plans

```bash
ivybloom billing plans
```

Compare available subscription tiers and their included credits.

### Token Balance

```bash
ivybloom billing tokens
```

Check your current token balance (tokens are the billing unit for AI model usage).

### Billing Portal

```bash
ivybloom billing portal
```

Opens the billing portal in your browser for payment method management, plan changes, and invoice downloads.

### Invoices

```bash
ivybloom billing invoices
ivybloom billing invoices --limit 5
```

List billing invoices with pagination.

---

## Spending Alerts

### View Alert Settings

```bash
ivybloom credits alerts show
```

### Set Alert Thresholds

```bash
# Alert when daily spending exceeds 100 credits
ivybloom credits alerts set --type daily_limit --threshold 100

# Alert when monthly spending exceeds 1000 credits
ivybloom credits alerts set --type monthly_limit --threshold 1000
```

Alerts notify you via email and in the TUI when thresholds are reached.

---

## AI Model Pricing

Model calls draw credits by one rule for every model, spelled out in [plans and tiers](/docs/plans-and-tiers#how-the-platform-meters-and-gates).

View available models:

```bash
ivybloom config models list
ivybloom config models list --available
```

> With [BYOK (Bring Your Own Key)](/docs/cli/configuration#byok-bring-your-own-key), model calls that run on your own key skip the platform markup. They are still metered in research credits, at the provider's cost.

---

## Usage Export

Export credit usage data for analysis or accounting:

```bash
# Export as JSON
ivybloom credits export --format json

# Export as CSV (for spreadsheets)
ivybloom credits export --format csv
```

---

## Account Usage

### Overview

```bash
ivybloom account usage
```

Shows high-level usage statistics including total jobs run, API calls, and storage used.

### Account Info

```bash
ivybloom account info
```

Detailed account information including plan details, usage limits, and current quotas.

---

## CI/CD Cost Tracking

For automated pipelines, use agent mode to get structured billing data:

```bash
# Check credits before submitting expensive jobs
BALANCE=$(ivybloom credits summary --agent | jq -r '.data.balance')
if [ "$BALANCE" -gt 100 ]; then
  ivybloom batch submit screen.yaml
fi
```

> For CI/CD automation, add `--agent` for structured JSON output. See [Agent Mode](/docs/cli/agent-mode) for the full envelope schema.

---

## Read next

- [Configuration](/docs/cli/configuration) — BYOK setup to use your own API keys
- [Organizations](/docs/cli/organizations) — Team billing and shared usage
- [Batch Processing](/docs/cli/batch) — Estimate costs for batch jobs
- [Commands Reference](/docs/cli/commands) — Full command documentation