Skip to content

CLI overview ​

The selfauth CLI is a development tool. It writes files into your project, checks them, and helps you update them later. Nothing it generates calls it at runtime, so you could delete it from your machine and the app would carry on working.

Running it ​

There's nothing to install:

bash
npx selfauth <command>

Or add it to a project as a dev dependency, so the whole team uses the same version:

bash
npm install -D @selfauth/cli
npx selfauth --version
text
0.15.0

selfauth and @selfauth/cli are the same tool. It needs Node.js 22.18 or newer.

All commands ​

CommandWhat it doesWrites files?
init [dir]Create a new project (Express, Fastify or Gin)yes
add [dir]Add SelfAuth to an existing Express or Fastify projectyes (new files only)
add-frontend [dir]Add the auth module to an existing Vue or React appyes (new files only)
detect [dir]Inspect a project and recommend the right commandno
listList the supported integrationsno
doctor [dir]Configuration and production-readiness checksno
validate [dir]Check the configuration, generated files and the schemano
diff [dir]Show what a newer version would changeno
upgrade [dir]Update generated files you have not editedyes
db status|plan|migrate|validate|rollback|generateReview and apply database migrationsdatabase
skill install [dir]Install the agent skill for Claude Code, Codex or Cursoryes

Ask any command for help:

bash
npx selfauth --help
npx selfauth init --help

Conventions ​

  • [dir] is the project folder. Leave it out to use the current one.
  • --dry-run shows what would be written and writes nothing. Use it first wherever it exists.
  • -y or --yes answers "yes" to every question, so commands can run in scripts and CI.
  • --json (on detect, list, doctor and validate) prints machine-readable output for scripts and coding agents.
  • Exit code 0 means success. Anything else means a problem was found or the command failed. doctor and validate exit non-zero when they report errors, so they can fail a CI job.
  • init, add and add-frontend only create files. They never overwrite one that exists.

In a full-stack project ​

At the root of a project with server/ and client/, doctor, validate, diff and upgrade cover both packages. The db commands find server/ on their own.

Using the CLI in CI ​

yaml
- run: npx selfauth validate
- run: npx selfauth doctor

The first fails the build if the configuration is invalid or the schema and manifest disagree. The second reports production readiness warnings.

SelfAuth is MIT licensed. Generated code is also offered under 0BSD.