UIA Better Stack CLI

A simple CLI tool to scaffold and maintain a Better Stack project structure. It ensures that all required folders, configuration files, and environment files exist in your project.

Installation

npm install -g uia-better-stack

or run directly with:

npx uia-better-stack

Commands

1. Initialize Project

Creates the full project structure and required files.

uia-better-stack

or

uia-better-stack init

What it does

Creates:

/lib/db.ts
/lib/auth.ts
/lib/auth-client.ts
/app/api/auth/[...all]/route.ts (Next.js only)
/lib
/api
.env.example

And installs recommended dependencies.

Verify Command

The verify command checks if your project structure is correct.

If files or folders are missing, it will automatically create them.

This is useful when:

• Someone cloned the repo
• Files were deleted accidentally
• Environment files are missing
• You want to validate the project structure

Usage

uia-better-stack verify

What Verify Checks

The command verifies the existence of required files:

| File / Folder | Action | | --------------------------------- | ----------------- | | /lib/db.ts | Create if missing | | /lib/auth.ts | Create if missing | | /lib/auth-client.ts | Create if missing | | /app/api/auth/[...all]/route.ts | Create if missing | | .env.example | Create if missing |

Example Output

✔ Checking project structure...

✔ /lib/db.ts exists
✔ /lib/auth.ts exists
✔ /lib/auth-client.ts exists
✔ /app/api/auth/[...all]/route.ts exists
✖ .env.example missing → creating...

✔ Project verified successfully

Example Implementation (Node.js)

Below is a basic implementation of the verify command.

import fs from "fs-extra";
import path from "path";
import kleur from "kleur";

export async function verifyTemplates({ cwd, templateDir, typescript = true }) {
  console.log(kleur.gray("Checking required files...\n"));

  const ext = typescript ? "ts" : "js";

  const requiredFiles = [
    {
      name: "Database",
      target: path.join(cwd, `lib/db.${ext}`),
      template: path.join(templateDir, `lib/db.ts`),
    },
    {
      name: "Auth instance",
      target: path.join(cwd, `lib/auth.${ext}`),
      template: path.join(templateDir, `lib/auth.ts`),
    },
    {
      name: "Auth client",
      target: path.join(cwd, `lib/auth-client.${ext}`),
      template: path.join(templateDir, `lib/auth-client.ts`),
    },
    {
      name: "Auth route",
      target: path.join(cwd, `app/api/auth/[...all]/route.${ext}`),
      template: path.join(templateDir, `api/route.ts`),
    },
    {
      name: "Environment Variables",
      target: path.join(cwd, `.env.example`),
      template: path.join(templateDir, `.env.example`),
    },
  ];

  for (const file of requiredFiles) {
    if (await fs.pathExists(file.target)) {
      console.log(kleur.green("✔"), file.target);
    } else {
      console.log(kleur.red("✖ Missing"), file.target);

      await fs.ensureDir(path.dirname(file.target));
      await fs.copy(file.template, file.target);

      console.log(kleur.yellow("→ Recreated"), file.target);
    }
  }

  console.log(kleur.green("\n✔ Verification complete\n"));
}

Why Use Verify?

Instead of running the full scaffold again, verify safely fixes only missing parts.

Benefits:

• Keeps existing files intact
• Prevents accidental overwrites
• Ensures project consistency
• Helps contributors quickly fix their setup

Typical Workflow

git clone project
cd project
npm install
uia-better-stack verify

This guarantees that all required project files exist.

Future Improvements

Possible enhancements:

• --fix flag to auto repair
• --strict mode to warn about extra files
• check for installed dependencies
• validate .env variables
• verify Node.js version

Example:

uia-better-stack verify --strict

License

MIT