Quick Start

This guide walks you through adding UseBetter Console to an existing Hono application. Choose the tab that matches your environment — development (instant setup, no database) or production (magic link auth with Drizzle).

Development (auto-approve)

Auto-approve issues a stateless JWT immediately — no database tables, no email flow. Use this for local development.

1. Generate a connection token

   npx @usebetterdev/console-cli init --email admin@localhost -n

   This prints two environment variables. Copy BETTER_CONSOLE_TOKEN_HASH — you’ll need it in the next step.

2. Add to your .env

   .env

   BETTER_CONSOLE_TOKEN_HASH=sha256:e5f6a7b8...

3. Add the middleware

   src/index.ts

   import { Hono } from "hono";
   import { betterConsole } from "@usebetterdev/console";
   import { createConsoleMiddleware } from "@usebetterdev/console/hono";
   
   const app = new Hono();
   
   const consoleInstance = betterConsole({
     connectionTokenHash: process.env.BETTER_CONSOLE_TOKEN_HASH!,
     sessions: { autoApprove: process.env.NODE_ENV === "development" },
   });
   
   app.use("*", createConsoleMiddleware(consoleInstance));
   
   // Your existing routes below...
   app.get("/", (c) => c.text("Hello!"));
   
   export default app;

4. Verify the health endpoint

   curl http://localhost:3000/.well-known/better/console/health

   You should see {"status":"ok"}.

5. Open the Console UI

   Visit console.usebetter.dev, enter your server URL (e.g., http://localhost:3000), and authenticate. Auto-approve grants a session token instantly.

Caution

Auto-approve is blocked outside of development. It throws ConsoleAutoApproveInProductionError when NODE_ENV is not "development" or "test". Use magic link auth for production — see the Production tab.

Production (magic link)

Magic link uses a 3-step handshake with email verification. Requires Drizzle and a PostgreSQL database.

1. Generate a connection token

   npx @usebetterdev/console-cli init --email [email protected]

   This prints two environment variables. Copy both.

2. Add to your .env

   .env

   BETTER_CONSOLE_TOKEN_HASH=sha256:e5f6a7b8...
   BETTER_CONSOLE_ALLOWED_EMAILS=[email protected]

3. Create the database tables

   Generate the migration SQL and apply it:

   # Option A: Generate a file, then apply with your migration tool
   npx @usebetterdev/console-cli migrate -o drizzle/console_tables.sql
   
   # Option B: Pipe directly to psql
   npx @usebetterdev/console-cli migrate --dry-run | psql $DATABASE_URL

   This creates two tables: better_console_sessions and better_console_magic_links.

4. Add the middleware with Drizzle adapter

   src/index.ts

   import { Hono } from "hono";
   import { drizzle } from "drizzle-orm/node-postgres";
   import { Pool } from "pg";
   import { betterConsole } from "@usebetterdev/console";
   import { drizzleConsoleAdapter } from "@usebetterdev/console/drizzle";
   import { createConsoleMiddleware } from "@usebetterdev/console/hono";
   
   const pool = new Pool({ connectionString: process.env.DATABASE_URL });
   const db = drizzle(pool);
   
   const app = new Hono();
   
   const consoleInstance = betterConsole({
     adapter: drizzleConsoleAdapter(db),
     connectionTokenHash: process.env.BETTER_CONSOLE_TOKEN_HASH!,
     sessions: {
       magicLink: {
         allowedEmails: process.env.BETTER_CONSOLE_ALLOWED_EMAILS!,
       },
     },
   });
   
   app.use("*", createConsoleMiddleware(consoleInstance));
   
   // Your existing routes below...
   app.get("/", (c) => c.text("Hello!"));
   
   export default app;

5. Verify the setup

   npx @usebetterdev/console-cli check --database-url $DATABASE_URL

   All checks should pass.

6. Open the Console UI

   Visit console.usebetter.dev, enter your server URL (e.g., https://myapp.com), and authenticate via magic link. A 6-character code is sent to your email — enter it in the UI to complete authentication.

What just happened?

1. The CLI generated a connection token pair. The hash is stored in your environment and used server-side to sign/verify session JWTs. The raw token is only shown once during init.
2. The middleware intercepts all /.well-known/better/* requests and delegates them to handleConsoleRequest().
3. The Console UI at console.usebetter.dev calls your server’s endpoints to authenticate and discover registered products. No data leaves your infrastructure — the UI is a static frontend that talks directly to YOUR server.

Next steps

• Configuration — all config options, permissions, CORS, environment variables
• Authentication — auto-approve, magic link, custom auth hook
• Product Registration — expose data to the Console UI
• CLI — all CLI commands