faustine-next CLI | Faustine Docs

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

terminal

npx faustine-next <command> [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:

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`	Generate the registry, the route handler and the `AGENTS.md` block.
`sync`	Update the registry after Server Actions or data functions change.
`doctor`	Compare the running app with what Faustine expects.

init

terminal

npx faustine-next init --setup <SETUP_CODE>

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 `<!-- BEGIN:faustine -->` and `<!-- END:faustine -->` 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 <code>`	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 <id>`	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.

terminal

npx faustine-next init --setup <SETUP_CODE> --dry-run
npx faustine-next init --setup <SETUP_CODE> --operations deals.createDeal,deals.getDeal

sync

terminal

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.

terminal

npx faustine-next sync --check

doctor

terminal

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 <origin>`	`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/<AGENT_ID>.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: when to run sync and how to gate it in CI.
@faustine-ai/next reference: the registry and the handler the generator writes.