# faustine-next CLI `faustine-next` is the command-line tool of `@faustine-ai/next`. It generates the Faustine adapter's files in a Next.js app and compares them with what Faustine expects. This page describes version 0.1.5. ## Usage ```bash npx faustine-next [flags] ``` Run it from the directory of the Next.js app, the one with its `package.json`. The app must use the App Router. Without an `app/` or `src/app/` directory, `init` and `sync` stop with this error and exit with `1`: ```text No `app/` or `src/app/` directory here — faustine-next supports the Next.js App Router. Run it from the Next.js project root. ``` | Command | Description | | --- | --- | | [`init`](#init) | Generate the registry, the route handler and the `AGENTS.md` block. | | [`sync`](#sync) | Update the registry after Server Actions or data functions change. | | [`doctor`](#doctor) | Compare the running app with what Faustine expects. | ## init ```bash npx faustine-next init --setup ``` Reads the operations the analysis found for the Web Agent and writes three files. When the app's code is under `src/`, the first two are written there. | File | Content | | --- | --- | | `faustine/registry.ts` | One line per bound operation. | | `app/api/faustine/[...op]/route.ts` | The route handler. | | `AGENTS.md` | A block between `` and `` that tells coding agents how to keep the registry current. The rest of the file is kept. | `init` binds every Server Action and server-only data function the analysis found. It leaves out route handlers and client-side fetches, which already have a URL, and reads written inline in a Server Component. After it writes the files, it reports the registry to Faustine. Running it again writes only what differs. | Flag | Description | | --- | --- | | `--setup ` | The setup code from the portal. The first run that uses a code exchanges it for an adapter token and stores the token on the machine, and a dry run counts. Passing the same code again reuses the stored token. | | `--web-agent ` | Which stored token to use when several are stored and there is no registry yet. | | `--operations a.b,c.d` | Bind only these operations. A name that the analysis did not find is an error. | | `--dry-run` | Print the plan and write nothing. | | `--yes` | Write the files when the command runs without a terminal. Without it, a run with no terminal stops with `Not a terminal: pass --yes to write the files (or --dry-run to only print the plan).` | Without `--setup`, the command uses the token for the Web Agent named in the registry, or the only stored token when there is no registry. ```bash npx faustine-next init --setup --dry-run npx faustine-next init --setup --operations deals.createDeal,deals.getDeal ``` ## sync ```bash npx faustine-next sync ``` Runs the same generator as `init` and takes the same flags. Without `--operations`, it keeps the operations the registry has and adds the ones that are new since the last run that wrote files. An operation whose line was removed from the registry, or that was left out before, stays out. | Flag | Description | | --- | --- | | `--check` | Write nothing. Exit with `1` when the registry, the route handler or the `AGENTS.md` block would change, and with `0` when they would not. | | `--dry-run` | Print what would change and write nothing. | ```bash npx faustine-next sync --check ``` ## doctor ```bash npx faustine-next doctor --url https://app.nimbuscrm.example ``` Requests `/api/faustine/manifest` from the running app, reads the registry in the current directory, asks Faustine for the adapter's status, and prints each difference as a finding. It exits with `4` when a finding is an error. | Flag | Default | Description | | --- | --- | --- | | `--url ` | `http://localhost:3000` | The origin of the running app. | | Finding | Level | | --- | --- | | The app's manifest did not answer `200`. | Error | | The app cannot reach Faustine and exposes nothing. | Error | | The last commit Faustine checked has a binding to a function that does not exist. | Error | | No published version enables an adapter operation. | Warning | | The app reports no build SHA. | Warning | | The app runs a different registry from the one Faustine last saw, or from the one in the checkout. | Warning | | Operations are enabled in the portal and not bound in the build, or missing from the registry. | Warning | | The machine has no adapter token, so the app is not compared with Faustine. | Warning | ## Global flags | Flag | Description | | --- | --- | | `--json` | Print the result as JSON. This is the default when the output is not a terminal. | | `--quiet` | Print nothing on standard output. | | `--help` | Print the help text. | | `--version` | Print the version. | Errors go to standard error. In JSON mode an error is `{"error":{"code":"…","message":"…"}}`. ## Adapter tokens The token is stored in `~/.config/faustine/adapters/.json`, readable by the current user only. `XDG_CONFIG_HOME` replaces `~/.config`, and `FAUSTINE_CONFIG_DIR` replaces the `faustine` directory. A token is scoped to one Web Agent and is revoked in the portal, in the agent's **Settings** tab under **Faustine adapter**. ## Exit codes | Code | Meaning | | --- | --- | | `0` | Success. | | `1` | Usage error: an unknown command or operation, a setup code that expired or was already used, no `app/` or `src/app/` directory, no terminal without `--yes`, or a run with no command. Also `sync --check` when something would change. | | `2` | The machine has no adapter token for the Web Agent, Faustine did not recognize the setup code, or Faustine rejected the token, for example after it was revoked. | | `4` | Faustine answered with an error, or `doctor` found an error. | | `5` | Faustine or the app at `--url` could not be reached. | ## Next steps - [Keep the adapter in sync](https://docs.faustine.ai/web-agents/sync-the-adapter/): when to run `sync` and how to gate it in CI. - [@faustine-ai/next reference](https://docs.faustine.ai/reference/next-package/): the registry and the handler the generator writes.