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

# Project Setup

> outkit init: detect your framework, pick a profile, install the SDK, and write the proxy

`outkit init` is the one command that wires your project to Outkit. It detects your
framework, lets you pick (or create) a profile, installs the right SDK, writes the backend
proxy endpoint, and prints the swap snippet for your stack.

## Prerequisites

```bash theme={null}
npm install -g @outkit-dev/cli@latest
outkit login
```

If you have not signed in yet, see [CLI Overview](/docs/cli/overview).

## `outkit init`

Run it from the root of your project:

```bash theme={null}
outkit init
```

What it does:

1. **Detects your framework** — React, Next.js, Vue, Svelte, Astro, vanilla JS — and picks the
   right SDK package.
2. **Detects your design tokens** — and applies them to your profile.
3. **Picks a profile** — uses your team's active profile, or offers to create one seeded with
   the detected tokens.
4. **Installs the SDK** — `@outkit-dev/react` or `@outkit-dev/core` (use `--no-install` to
   skip).
5. **Writes the backend proxy** — server route that forwards to `POST /render/enhance` and
   keeps your API key on the server.
6. **Writes `outkit.json`** — repo-local config the rest of the CLI reads.
7. **Prints the swap snippet** — the exact JSX/HTML to drop into your component.

### Flags

| Flag             | Effect                                                           |
| ---------------- | ---------------------------------------------------------------- |
| `--no-install`   | Don't install the SDK package — just write configs and snippets. |
| `--profile <id>` | Skip the profile picker and bind to a specific profile.          |

### `outkit.json`

```json theme={null}
{
  "version": 1,
  "mode": "react",
  "teamId": "61e19e7d-…",
  "profileId": "1ff19764-…",
  "backendUrl": "${OUTKIT_API_BASE_URL}",
  "sdkVersion": "latest",
  "themeMap": { "primary": "--brand-pink", "bg": "--page-bg" }
}
```

Commit this file. The CLI rewrites it in place when you switch profiles or run `outkit upgrade`.

## After init

You'll see something like:

```text theme={null}
✔ React detected (Next.js 15)
✔ Profile: ok-demo (1ff19764)
✔ Installed @outkit-dev/react
✔ Wrote app/api/enhance/[id]/route.ts
✔ Wrote outkit.json
✔ Wrote outkit.theme.json

Next:
  1. outkit keys create -n "dev key"   # generate a key, written to .env.local
  2. outkit dev                         # tail render logs while you work
  3. Copy the snippet below into your chat component:

import { AIRenderer, useBlockStream } from '@outkit-dev/react';
…
```

## Switching profiles or teams

```bash theme={null}
outkit switch          # interactive picker
outkit profiles use <profileId>
```

Both commands rewrite `outkit.json`. To pull the new profile's tokens into your repo:

```bash theme={null}
outkit theme pull
```

## Upgrading

When the SDK gets a new release:

```bash theme={null}
outkit upgrade
```

This bumps the `@outkit-dev/*` packages and runs any required codemods. To preview migrations
between two specific versions:

```bash theme={null}
outkit migrate <from> <to>
```

## Undo

`init`, `theme apply`, `upgrade`, and `agent` are all journaled to `~/.outkit/undo.json`. To
reverse the most recent code-mutating command:

```bash theme={null}
outkit undo
```

The undo refuses to clobber files you have edited since the command ran. Dependencies are
**not** auto-removed — the CLI prints the uninstall command for you.

## Health check

After init (and any time things look off):

```bash theme={null}
outkit doctor --full
```

`doctor` checks auth, network reachability, project mode, SDK packages, the wire format end
to end, and the design-token meta event. Use `--json` to consume it from CI.

## Next Steps

<CardGroup cols={2}>
  <Card title="Generate API keys" icon="key" href="/docs/cli/keys">
    Plaintext keys are shown once. The CLI offers to write them to `.env.local`.
  </Card>

  <Card title="Sync design tokens" icon="palette" href="/docs/cli/theme">
    `outkit theme detect / apply / sync` keeps your profile in lockstep with your codebase.
  </Card>
</CardGroup>