# Quickstart: ohauthcat init

`ohauthcat init` reads your project's framework declaration, shows every change it would make as a diff, and after you approve applies them and registers your local callback URI in your sandbox. It works in existing projects, next to the auth you already have, and `ohauthcat init --undo` reverses it. It never edits a package manifest or lock file and never reads `.env` files; see [what init reads](/get-started/init-security/). Install the CLI as described in [Install the CLI and sign in](/get-started/cli/).

## Before you run it

1. Sign in with `ohauthcat login --profile work-sandbox`. Registration needs a sandbox environment.
   No account yet? Run `ohauthcat init` without signing in and it offers a free [claimable sandbox](/get-started/claimable-sandboxes/#from-the-cli) instead; `ohauthcat init --sandbox` creates one without asking.
2. Run the command from the project root, or pass `--project <directory>`. The project must declare exactly one supported framework.
3. Decide the local origin your app listens on. The default is `http://127.0.0.1:3000`; pass `--app-origin http://localhost:<port>` to change it. Only `localhost` and loopback addresses are accepted. The callback is always `<origin>/auth/callback`.

## Preview, then approve

Run `ohauthcat init --dry-run` first. It prints the detected framework and package manager, each proposed file as a diff, and the remote action, without creating anything. `ohauthcat init --dry-run --json` prints the same plan as JSON.

Run `ohauthcat init` to review the same plan and type `yes` to approve it, or pass `--yes` in a non-interactive run. The CLI applies the changes, then calls `POST /v1/dev/init` to register the exact redirect URI. A file that already exists is shown as a diff against the proposed contents and is replaced only after you approve; a file identical to the proposal is left alone. Running `init` again on a finished project is refused ("a previous init change set exists … run ohauthcat init --undo first"); run `ohauthcat init --undo` before planning again. If registration fails after the files are created, rerun with `ohauthcat init --register-only` and the same `--app-origin`.

The CLI writes `.env.template` only when the project has none. It holds placeholders only. Put real values in your server process environment, never in a committed file. Get them from the API keys page of your sandbox in the dashboard; see [your sandbox keys](/get-started/sandbox-keys/).

## Existing projects

`init` detects the auth your project already uses from its dependencies and a few conventional configuration files (checked for existence only): Auth0, Amazon Cognito, Firebase Authentication, Supabase Auth, Clerk, or a custom stack such as Passport.js or a session library. It keeps that auth in place and prints how OhAuthCat sits next to it; see [working with existing auth](/sso/working-with-existing-auth/).

Where the framework allows, it also inserts a small block into your own code, between `>>> ohauthcat init` and `<<< ohauthcat init` comments:

- Express with a TypeScript entry file: the OhAuthCat routes are mounted on the app you create with `express()`;
- Django: the routes are added to the `urlpatterns` of your `ROOT_URLCONF`.

Other frameworks get new files only, and the CLI prints how to mount them.

## Undo

Every applied change is recorded in `.ohauthcat/init-changes.json`, with the original contents of each file it changed. `ohauthcat init --undo` shows the reversal as a diff and applies it after you approve (`--dry-run` to only show it, `--yes` to skip the prompt). It removes created files, restores replaced ones and removes inserted blocks. A file you edited after `init` is kept for you to resolve, though an intact inserted block in it is still removed. Undo never contacts the API, so the registered callback stays in your sandbox.

## What each framework gets

The CLI detects the framework from `package.json` for Node projects, and from the `[project]` dependencies in `pyproject.toml` or from `requirements.txt` for Python projects.

### `Next.js`

Adds `app/auth/sign-in/route.ts`, `app/auth/callback/route.ts`, `app/webhooks/route.ts` and helpers under `ohauthcat/`. Only a root `app/` App Router layout is supported; a `src/app` layout is refused. Compilation of the generated routes is not yet verified.

### Express

Adds `ohauthcat/express/` and `ohauthcat/shared/`. Mount `createApp(...)` with `app.use(...)`, or compile the files and run `ohauthcat/express/server.js`.

### Fastify

Adds `ohauthcat/fastify/` and `ohauthcat/shared/`. Use the Fastify instance that `createApp(...)` returns, or compile the files and run `ohauthcat/fastify/server.js`.

### FastAPI

Adds `ohauthcat_examples/`. Run `uvicorn ohauthcat_examples.fastapi_app:create_app --factory --host 127.0.0.1 --port 3000 --workers 1`.

### Django

Adds `ohauthcat_examples/`. Run `django-admin runserver 127.0.0.1:3000 --settings=ohauthcat_examples.django_settings --noreload`, or add its routes to your `urlpatterns`.

### Flask

Adds `ohauthcat_examples/`. Build the app from a launcher you own; the CLI prints the exact calls. The Flask development server is not a production host.

For Node projects the CLI keeps the package manager your project declares (`npm`, `pnpm` or `yarn`) and refuses when its lock files disagree. A project that lists two frameworks, for example `Next.js` with Express as an adapter, is refused; integrate that project by hand.

## A test connection from the API

`POST /v1/dev/init` also accepts `"test_connection": true`. The response then includes the sandbox's test organization, its SAML connection to the hosted test IdP and a fresh one-time `test_url` with `test_url_expires_at`. The first call creates the organization, with the fixed external ID `ohauthcat-test-organization`; later calls find the same one. Where no hosted test IdP is available, the call answers 503 [`service_unavailable`](/errors/service_unavailable/). See the [management reference](/reference/api/management/).

`ohauthcat init` sends this option after it registers your callback. It checks that the returned `test_url` is on the trusted broker for that connection (`OHAUTHCAT_AUTH_BASE` when you set it) and opens it in your browser, so your first sign-in goes through the [test IdP](/get-started/sandbox-and-test-idp/#the-test-idp). Pass `--no-open` to print the URL instead. Where the environment has no test IdP, `init` still registers the callback and says the test sign-in is unavailable.

## What it does not do yet

- It does not install the SDK. Add it yourself with `npm install @ohauthcat/node` or `pip install ohauthcat`.
- It does not check that the test sign-in completed. Watch the test result page, or follow [sandbox and test IdP](/get-started/sandbox-and-test-idp/) to try failure scenarios.
- It mounts routes into your existing server only for Express TypeScript entry files and Django. For the other frameworks, follow the printed instructions.

After the routes run, continue with the [Node quickstart](/get-started/quickstart-node/) or the [Python quickstart](/get-started/quickstart-python/) for how the sign-in and callback handlers work.
