Quickstart: ohauthcat init
Add reviewed sign-in, callback and webhook routes to a Node or Python web project with the CLI.
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. Install the CLI as described in Install the CLI and sign in.
Before you run it
Section titled “Before you run it”- Sign in with
ohauthcat login --profile work-sandbox. Registration needs a sandbox environment. No account yet? Runohauthcat initwithout signing in and it offers a free claimable sandbox instead;ohauthcat init --sandboxcreates one without asking. - Run the command from the project root, or pass
--project <directory>. The project must declare exactly one supported framework. - Decide the local origin your app listens on. The default is
http://127.0.0.1:3000; pass--app-origin http:to change it. Only/ / localhost: <port> localhostand loopback addresses are accepted. The callback is always<origin>./ auth/ callback
Preview, then approve
Section titled “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.
Existing projects
Section titled “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.
Where the framework allows, it also inserts a small block into your own code, between > 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
urlpatternsof yourROOT_URLCONF.
Other frameworks get new files only, and the CLI prints how to mount them.
Every applied change is recorded in ., 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
Section titled “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
Section titled “Next.js”Adds app/, app/, 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
Section titled “Express”Adds ohauthcat/express/ and ohauthcat/shared/. Mount createApp(...) with app.use(...), or compile the files and run ohauthcat/.
Fastify
Section titled “Fastify”Adds ohauthcat/fastify/ and ohauthcat/shared/. Use the Fastify instance that createApp(...) returns, or compile the files and run ohauthcat/.
FastAPI
Section titled “FastAPI”Adds ohauthcat_examples/. Run uvicorn ohauthcat_examples..
Django
Section titled “Django”Adds ohauthcat_examples/. Run django-admin runserver 127., or add its routes to your urlpatterns.
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
Section titled “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. See the management reference.
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. 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
Section titled “What it does not do yet”- It does not install the SDK. Add it yourself with
npm install @ohauthcat/ornode pip install ohauthcat. - It does not check that the test sign-in completed. Watch the test result page, or follow 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 or the Python quickstart for how the sign-in and callback handlers work.