> ## Documentation Index
> Fetch the complete documentation index at: https://costhq.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# cs export and cs stats: Export Data and View Totals

> Use cs export to download session data as JSON or CSV, and cs stats to view aggregate metrics across all sessions including total cost, time, and tokens.

CostHQ lets you export your session history and view lifetime statistics without leaving the terminal. Whether you are generating a client invoice, doing a weekly spend review, or piping data into another tool, `cs export` and `cs stats` give you the numbers you need.

## cs export

```bash theme={null}
cs export --format csv
cs export --format json
cs export --format json --limit 10
```

### Options

| Flag            | Description                                                                                     |                                 |
| --------------- | ----------------------------------------------------------------------------------------------- | ------------------------------- |
| \`--format json | csv\`                                                                                           | Output format (default: `json`) |
| `--limit <n>`   | Maximum number of sessions to include (most recent first)                                       |                                 |
| `--json`        | Machine-readable output (same as `--format json`; included for consistency with other commands) |                                 |

### What's Included

Each exported record contains:

* Session ID and name
* Start and end times
* Duration
* Files changed
* Commits made
* AI tokens used
* AI cost (USD)
* Notes

***

## cs stats

```text theme={null}
cs stats [options]
```

Display aggregate metrics across every session in your history. Use `--json` to pipe results into scripts or dashboards.

| Flag     | Description             |
| -------- | ----------------------- |
| `--json` | Machine-readable output |

```text theme={null}
$ cs stats

Overall Statistics:

┌───────────────────┬──────────┐
│ Total Sessions    │ 52       │
│ Total Time        │ 138h 20m │
│ Average Session   │ 2h 39m   │
│ Files Changed     │ 412      │
│ Total Commits     │ 184      │
│ AI Tokens Used    │ 3.1M     │
│ Total AI Cost     │ $104.72  │
└───────────────────┴──────────┘
```

***

## Use Cases

### Freelance Billing

Pull the exact time and AI spend for a specific piece of work before writing an invoice:

```bash theme={null}
cs show        # precise duration and AI cost for the most recent session
cs show 12     # target a specific session by ID
```

### Weekly Review

Scan the last twenty sessions and then check lifetime totals:

```bash theme={null}
cs list -l 20
cs stats
```

### Export Reports

Capture a dated snapshot of recent sessions or overall stats as plain-text files:

```bash theme={null}
cs list -l 50 > weekly-report-$(date +%Y%m%d).txt
cs stats > monthly-stats-$(date +%Y-%m).txt
```

***

## Advanced: Shell Aliases

Add these aliases to `~/.bashrc` or `~/.zshrc` to cut down on typing for the commands you use most:

```bash theme={null}
# Add to ~/.bashrc or ~/.zshrc
alias csr="cs run"
alias css="cs start"
alias cse="cs end"
alias csl="cs list"
alias csst="cs stats"
```

***

## Advanced: Dynamic Session Notes

Capture git context automatically when you end a session so the notes always reflect exactly what changed:

```bash theme={null}
cs end -n "Branch: $(git branch --show-current)"
cs end -n "Made $(git rev-list --count HEAD ^origin/main) commits"
```