# Tetra

> Tetra is a SaaS framework for Node.js: auth, database security (Supabase +
> RLS), billing, UI components and developer tooling, installed with one
> command. Free for a single developer; see https://tetrasaas.com/pricing for
> what changes once a second person joins your organization.

This file is for AI coding assistants (Claude Code, Codex, OpenCode, Cursor,
and similar) that are asked to set up a new Tetra project. It states the
install steps plainly so an assistant does not have to infer them from HTML.

## Install

```
npx create-tetra my-app
```

Requires Node 24 or newer. Nothing to install first, no account to create
beforehand. The target directory must be empty, except that it may already
contain exactly: README.md, CLAUDE.md, AGENTS.md, .claude/, .git/, .gitignore.
That is the state a directory is in after following the starter-files
scaffolding below, so running create-tetra after it is expected, not an error.

## Approval — read this before running the command

The command prints a confirmation code and a link, then opens that link in a
browser and waits. A human has to open the link and approve there — an e-mail
address is entered and a magic link is sent to it; that is the whole account,
no password. This step cannot be automated or skipped by an agent: it is the
one human-in-the-loop checkpoint in the whole flow, and it exists on purpose.

What an assistant running this command should do:
- Run `npx create-tetra <project-name>`.
- Show the human the printed link and confirmation code, and ask them to open
  it and approve.
- Wait. Do not restart or re-run the command while it is waiting.

What an assistant running this command should NOT do:
- Do not open the approval link or submit the e-mail form yourself — a human
  has to do this step.
- Do not treat a wait of several minutes as a hang and restart the process.
  The code is valid for ten minutes, and the command automatically requests a
  fresh code and link if the current one expires (up to four times, roughly
  fifty minutes of total budget) without any need to re-run anything. Killing
  and restarting the command only throws away an approval that is already in
  progress and makes the human start over for no reason.
- Do not retry the command in a loop on a transient failure. The CLI already
  retries its own transient (5xx/429) failures with backoff.

After approval, create-tetra finishes the install on its own: it fetches the
scaffolder with your registry access, generates the project, and writes your
registry token and licence key into files inside the project (.env, .npmrc,
ci/npmrc — see https://tetrasaas.com/get-started for exactly which files and
what each one holds).

## After install

```
cd my-app
npm run dev:local
```

Needs the Supabase CLI (`supabase start`, then `supabase db reset`) and
nothing else — this is the command that works immediately after install, with
no further setup. Once Doppler is connected for shared secrets, `npm run dev`
is the command to use instead. The generated project's README explains both.

## Working with an AI assistant — scaffolding

A starter kit of agent instructions (AGENTS.md/CLAUDE.md additions, Claude
Code hooks, skills for installing Tetra and compiling manifests) is available
separately and is meant to be layered on top of a project create-tetra already
created:

- Guide: https://soulbatical.github.io/starter-files/tetra/PROJECT_SETUP.md
- Scaffolding script: `bash tetra/apply-project-scaffolding.sh <project-dir>`

Running create-tetra first and the scaffolding script second (or the other
way around) both work: create-tetra's directory check explicitly allows a
target that already holds only that scaffolding.

## Reference

- Get started (human-readable, same steps, more detail): https://tetrasaas.com/get-started
- Pricing: https://tetrasaas.com/pricing
- Framework source and docs: https://github.com/soulbatical/tetra
- create-tetra CLI source: https://github.com/soulbatical/create-tetra