---
title: "Migrations"
description: "Upgrade guides for moving between versions of the Output framework."
---

Breaking changes are rare. When they happen, each one gets a dedicated guide below with the before/after patterns and a checklist.

## How to upgrade

The fastest path is the CLI:

```bash
npx output migrate
```

It reads the `@outputai/*` version in your `package.json`, finds the matching guide below, applies the steps, and runs your type checker. If you're jumping several versions, apply each guide in order.

## Guides

<CardGroup cols={1}>
  <Card title="v0.1.12 → v0.2.0" href="/migrations/v0.1.12-to-v0.2.0">
    Dataset file format and deprecated workflow run endpoints.
  </Card>
  <Card title="v0.2.0 → v0.3.0" href="/migrations/v0.2.0-to-v0.3.0">
    LLM cost payload format and cost event name.
  </Card>
  <Card title="v0.3.0 → v0.4.0" href="/migrations/v0.3.0-to-v0.4.0">
    Package.json Output.ai config section rename.
  </Card>
  <Card title="v0.4.0 → v0.5.0" href="/migrations/v0.4.0-to-v0.5.0">
    HTTP request cost API and cost event payload changes.
  </Card>
  <Card title="v0.5.2 → v0.6.0" href="/migrations/v0.5.2-to-v0.6.0">
    Hook payload context objects and trace run ids.
  </Card>
  <Card title="v0.6.0 → v0.7.0" href="/migrations/v0.6.0-to-v0.7.0">
    Removed web search tool re-exports and provider list helper rename.
  </Card>
  <Card title="v0.7.0 → v0.8.0" href="/migrations/v0.7.0-to-v0.8.0">
    Workflow result aggregation removal, workflow invocation options, and child workflow execution semantics.
  </Card>
  <Card title="v0.8.0 → v0.9.0" href="/migrations/v0.8.0-to-v0.9.0">
    CLI replaces `--format json` with the native `--json` flag.
  </Card>
</CardGroup>
