# Installation and setup

This guide sets up Flow in your AdonisJS app. You will:

- Sign in to the AdonisJS Plus registry
- Install Flow and set it up for your coding agents
- Check that your agent sees the Flow skills

You can let your coding agent do every step with one prompt, or do them by hand. Both end in the same place.

## Before you start

- An AdonisJS 7 app, on Node.js 24 or later.
- A coding agent: Claude Code, Cursor, Codex CLI, GitHub Copilot or OpenCode.
- npm, pnpm, Bun or Yarn. With Yarn, the app must use `nodeLinker: node-modules`. Plug'n'Play is not supported yet.

## Let your agent set it up

::agent-prompt
Paste this prompt into your coding agent, in the root of your project. It signs you in, installs Flow, and asks before it commits anything.

```
Set up AdonisJS Plus Flow in this project. If a step fails, work out what is wrong and fix it.

1. Find the package manager from the lockfile. If the project uses Yarn with Plug'n'Play, stop and tell me that Flow does not support Plug'n'Play yet.
   Check whether the project is a monorepo: the AdonisJS app, the folder with adonisrc.ts, is in a folder below the lockfile. If it is, follow "In a monorepo" below.

2. Point the @adonisplus scope at the Plus registry.
   - npm, pnpm or Bun: add `@adonisplus:registry=https://plus.adonisjs.com/registry/` to the project's .npmrc.
   - Yarn: add this to the project's .yarnrc.yml:
     npmScopes:
       adonisplus:
         npmRegistryServer: "https://plus.adonisjs.com/registry"

3. Sign me in to the registry, unless `npm whoami --registry=https://plus.adonisjs.com/registry/` already prints my email.
   - npm, pnpm or Bun: `npm login --registry=https://plus.adonisjs.com/registry/ --scope=@adonisplus --auth-type=web`
   - Yarn: `printf 'n\n' | yarn npm login --scope adonisplus --web-login`
   The command prints a link. Show it to me, and wait while I approve the sign-in in my browser. Never print or copy the token.

4. Install @adonisplus/flow as a dev dependency.

5. Ask me: "Would you like to configure Flow for coding agents other than <you>?" The others are claude, cursor, codex, copilot and opencode.

6. Run `npx @adonisplus/flow install --yes --agent <you>`, with one more `--agent` for each agent I picked. If it cannot detect the stack, decide it from the code (controllers that only return JSON: api; Edge views: hypermedia) and run it again with `--stack`. Ask me only when the code does not make it clear.

7. Tell me what Flow installed: the agents, the stack, and the number of docs and skills. Then ask me: "Flow has been installed. Should I add and commit these changes?" The changes are .npmrc or .yarnrc.yml, package.json, the lockfile, flow.lock, .flow/review.yml and the ESLint config.

8. Last, tell me to start a new session of my coding agent and type /flow- to see the Flow skills.

In a monorepo:
- If more than one folder has adonisrc.ts, ask me which app to set up.
- Step 2: add the registry line to the file at the workspace root, not in the folder of the app.
- Steps 4 and 6: run the commands in the folder of the app. In step 6, add `--workspace`.
- Step 7: the changes also include CLAUDE.md or AGENTS.md at the workspace root.
- Step 8: tell me to start the new session in the folder of the app.

If the install fails:
- A 404 from registry.npmjs.org means the scope line of step 2 is missing or wrong.
- A 401 from plus.adonisjs.com means you have no token. Sign me in again.
- Only when signing in keeps failing: open https://plus.adonisjs.com/account/tokens in the browser, create a token, and save it without printing it, with `npm config set //plus.adonisjs.com/registry/:_authToken <token>` (Yarn: `yarn config set --home npmScopes.adonisplus.npmAuthToken <token>`).
```
::

## Set up by hand

::steps
### Point your project at the registry

Flow and the premium packages are published under the `@adonisplus` scope, on the AdonisJS Plus registry. This line sends that scope to the registry. It holds no token, so commit it.

::code-group{sync="pm"}
```ini [npm]
@adonisplus:registry=https://plus.adonisjs.com/registry/
```

```ini [pnpm]
@adonisplus:registry=https://plus.adonisjs.com/registry/
```

```yaml [yarn]
npmScopes:
  adonisplus:
    npmRegistryServer: "https://plus.adonisjs.com/registry"
```

```ini [bun]
@adonisplus:registry=https://plus.adonisjs.com/registry/
```
::

The line goes in `.npmrc` at the root of your project. With Yarn, it goes in `.yarnrc.yml`. In a monorepo, that is the workspace root, not your app's folder.

### Sign in to the registry

The command prints a link. Open it, and approve the sign-in on the page it opens. The token is saved in your user config (`~/.npmrc`, or `~/.yarnrc.yml` with Yarn), never in the project.

::code-group{sync="pm"}
```sh [npm]
npm login --registry=https://plus.adonisjs.com/registry/ --scope=@adonisplus --auth-type=web
```

```sh [pnpm]
npm login --registry=https://plus.adonisjs.com/registry/ --scope=@adonisplus --auth-type=web
```

```sh [yarn]
yarn npm login --scope adonisplus --web-login
```

```sh [bun]
npm login --registry=https://plus.adonisjs.com/registry/ --scope=@adonisplus --auth-type=web
```
::

The sign-in creates a token named after your package manager and your system, for example "npm on macOS". It is listed in Tokens on your dashboard, where you can revoke it.

### Install Flow

Flow is a command line tool, so it is a dev dependency. Run the command in your app's folder, so that in a monorepo Flow goes into your app and not into the workspace root.

::code-group{sync="pm"}
```sh [npm]
npm i -D @adonisplus/flow
```

```sh [pnpm]
pnpm add -D @adonisplus/flow
```

```sh [yarn]
yarn add -D @adonisplus/flow
```

```sh [bun]
bun add -d @adonisplus/flow
```
::

### Set up Flow for your agents

Run the installer in your app's folder. It asks which coding agents you use, your stack, and the packages to install docs for. It detects each answer, so the defaults are usually right.

```sh
npx @adonisplus/flow install
```

Your answers are saved in `flow.lock`. The next run reads them, and asks only about what is new.

In a monorepo, add `--workspace` the first time. It also writes a pointer to your app in the `CLAUDE.md` or `AGENTS.md` at the workspace root, so that an agent started there finds your app. Read [Monorepos](/docs/get-started/monorepos) to learn more.

### Commit the changes

Commit `.npmrc` (or `.yarnrc.yml`), `package.json`, the lockfile, `flow.lock`, `.flow/review.yml` and the change to your ESLint config. In a monorepo, also commit the `CLAUDE.md` or `AGENTS.md` at the workspace root.

### Check that it works

Start a new session of your coding agent in your app's folder and type `/flow-`. The Flow skills show up in the list. On your dashboard, the Install Flow card shows "Registry token created" and "Flow installed in a project".
::

## What the installer writes

The installer writes these files in your app's folder, also in a monorepo.

::file-tree
```
.flow/docs/  # docs for the packages your app uses
.flow/lenses/  # the lenses of the code review
.flow/review.yml  # the settings of the code review, commit it
.claude/skills/  # the Flow skills, in the folder of each agent
CLAUDE.md  # Flow's section, or AGENTS.md for the other agents
flow.lock  # your answers, commit it
```
::

Each run writes the docs, the lenses and the skills again, so do not edit them. In `CLAUDE.md` and `AGENTS.md`, only Flow's section is replaced, and the rest of the file stays yours. The installer adds the missing entries to `.gitignore` and `.prettierignore`, so the docs and the skills stay out of git. Once `.flow/review.yml` and your ESLint config exist, the installer leaves them as they are.

To use your own docs, skills or lenses next to Flow's, read [Customizing Flow](/docs/flow/customizing).

## Premium packages

Once your project points at the registry, Persona and Permissions install like any AdonisJS package.

```sh
node ace add @adonisplus/persona
```

Read the docs of [Persona](/docs/packages/persona/introduction) and [Permissions](/docs/packages/permissions/introduction) to set them up.

## Removing Flow

The uninstaller removes the skills, the docs and Flow's section of `CLAUDE.md` and `AGENTS.md`. It asks which agents to remove Flow from.

```sh
npx @adonisplus/flow uninstall
```

## Next steps

::card-group
:::card{title="CI and deployment" to="/docs/get-started/ci-and-deployment"}
A token for each place that installs your app without you.
:::

:::card{title="Pull request reviews" to="/docs/flow/reviews/setup"}
Turn on the Flow review on your GitHub repositories.
:::
::
