### Run the example with pnpm

Source: https://github.com/glincker/theauth/blob/main/examples/basic-agent/README.md

Install dependencies and start the development server using pnpm.

```bash
pnpm install
pnpm dev
```

--------------------------------

### Getting started commands

Source: https://github.com/glincker/theauth/blob/main/packages/create-theauth-app/templates/next-saas/README.md

Commands to set up and run the project: copy the environment file, edit it to set THEAUTH_SECRET and DATABASE_URL, install dependencies, push the database schema, and start the development server.

```bash
cp .env.example .env
# Edit .env: set THEAUTH_SECRET and DATABASE_URL

pnpm install
pnpm run db:push
pnpm run dev
```

--------------------------------

### Run the single-binary example

Source: https://github.com/glincker/theauth/blob/main/docs/go/guides/single-binary-go-app.mdx

Commands to run the example app in the examples/single-binary-sqlite directory. It runs vet and tests, then starts the server with a setup token.

```sh
cd examples/single-binary-sqlite
go vet ./... && go test ./...
SETUP_TOKEN=change-me go run .
```

--------------------------------

### Run the example with pnpm

Source: https://github.com/glincker/theauth/blob/main/examples/migrate-from-auth0/README.md

Starts the example using the workspace filter @glinr/theauth-example-migrate-from-auth0.

```bash
pnpm --filter @glinr/theauth-example-migrate-from-auth0 start
```

--------------------------------

### Initial clone, install, build, and test setup

Source: https://github.com/glincker/theauth/blob/main/CONTRIBUTING.md

Clone the repositoryholistically, install dependencies, build all packages, and run tests. Requires Node.js 20+ and pnpm 9+.

```bash
git clone https://github.com/glincker/theauth.git
cd theauth
pnpm install
pnpm build
pnpm test
```

--------------------------------

### Install and run the Next.js app

Source: https://github.com/glincker/theauth/blob/main/examples/nextjs-app/README.md

Install dependencies with pnpm and start the development server. The app starts on http://localhost:3000.

```bash
pnpm install
pnpm dev
# App starts on http://localhost:3000
```

--------------------------------

### Run and test the migration example

Source: https://github.com/glincker/theauth/blob/main/docs/migrate/from-auth0.mdx

Use these pnpm commands to start the example and run its smoke test. The example is pinned to the same version as the docs via the workspace protocol.

```bash
pnpm --filter @glinr/theauth-example-migrate-from-auth0 start
pnpm --filter @glinr/theauth-example-migrate-from-auth0 test
```

--------------------------------

### Install theauth-go with go get

Source: https://github.com/glincker/theauth/blob/main/sdks/go/README.md

Install the Go client library using the go get command. Requires Go 1.21+ and has no external dependencies.

```bash
go get github.com/glincker/theauth-go
```

--------------------------------

### Run the quick start server

Source: https://github.com/glincker/theauth/blob/main/docs/go/index.mdx

Runs the server and shows an example POST request to the magic-link endpoint.

```bash
go run main.go
# POST http://localhost:8080/auth/magic-link  {"email":"you@example.com"}
```

--------------------------------

### Setup and run the Hono MCP server

Source: https://github.com/glincker/theauth/blob/main/packages/create-theauth-app/templates/hono-mcp/README.md

Sets up the environment file, installs dependencies, and starts the development server. Edit .env to set THEAUTH_SECRET and ADMIN_API_KEY to 32+ byte random hex strings before running.

```bash
cp .env.example .env
# Edit .env: set THEAUTH_SECRET and ADMIN_API_KEY to 32+ byte random hex strings

pnpm install
pnpm run dev
```

--------------------------------

### Run the migration example

Source: https://github.com/glincker/theauth/blob/main/docs/migrate/from-better-auth-agent-plugin.mdx

Commands to start and test the runnable example for migrating from better-auth agent plugin. The example uses the monorepo workspace version and includes a vitest smoke suite.

```bash
pnpm --filter @glinr/theauth-example-migrate-from-better-auth-agent-plugin start
pnpm --filter @glinr/theauth-example-migrate-from-better-auth-agent-plugin test
```

--------------------------------

### Setup and useLogin example

Source: https://github.com/glincker/theauth/blob/main/packages/react/README.md

Shows how to import and set up the TheAuthQueryProvider with a client, and use the useLogin hook to handle MFA-required responses.

```tsx
import { createTheAuthGoClient } from "@glinr/theauth-client";
import { TheAuthQueryProvider, useLogin, useSession } from "@glinr/theauth-react/query";

const client = createTheAuthGoClient({ baseUrl: "https://api.example.com" });

// <QueryClientProvider><TheAuthQueryProvider client={client}>...
function Login() {
  const login = useLogin();
  const onSubmit = async () => {
    const out = await login.mutateAsync({ email, password });
    if (out.status === "mfa_required") showTotpStep();
  };
}
```

--------------------------------

### Test the example with pnpm

Source: https://github.com/glincker/theauth/blob/main/examples/migrate-from-auth0/README.md

Runs the test suite that spawns pnpm start, captures stdout, and asserts every milestone claimed by the guide.

```bash
pnpm --filter @glinr/theauth-example-migrate-from-auth0 test
```

--------------------------------

### npx theauth init

Source: https://github.com/glincker/theauth/blob/main/packages/cli/README.md

Prints setup instructions for adding theAuth to a project, including install steps, configuration scaffold, and adapter options.

```bash
npx theauth init
```

--------------------------------

### Run the demo with pnpm

Source: https://github.com/glincker/theauth/blob/main/examples/nextjs-demo/README.md

Commands to install dependencies and start the development server. The demo runs at http://localhost:3002.

```bash
cd examples/nextjs-demo
pnpm install
pnpm dev
```

--------------------------------

### Next steps after scaffolding a theAuth app

Source: https://github.com/glincker/theauth/blob/main/packages/create-theauth-app/README.md

After the scaffolder finishes, run these commands to set up and start your app. The `cp .env.example .env` command copies the example environment file, and you must set `THEAUTH_SECRET` in it. Then push the database schema and start the dev server.

```bash
cd my-theauth-app
pnpm install
cp .env.example .env       # then set THEAUTH_SECRET
pnpm db:push
pnpm dev
```

--------------------------------

### Run the Hono server with pnpm

Source: https://github.com/glincker/theauth/blob/main/examples/hono-server/README.md

Install dependencies and start the development server. The server starts on http://localhost:3000.

```bash
pnpm install
pnpm dev
# Server starts on http://localhost:3000
```

--------------------------------

### Install and run locally with pnpm

Source: https://github.com/glincker/theauth/blob/main/examples/cloudflare-workers/README.md

Install dependencies and start the local development server using wrangler. Run these commands in the project root.

```bash
pnpm install
pnpm dev
# Uses wrangler for local development
```

--------------------------------

### Run the test with pnpm

Source: https://github.com/glincker/theauth/blob/main/examples/migrate-from-better-auth-agent-plugin/README.md

Runs the test suite for the example, which launches the start command and asserts the migration milestones.

```bash
pnpm --filter @glinr/theauth-example-migrate-from-better-auth-agent-plugin test
```

--------------------------------

### Full SolidStart adapter example

Source: https://github.com/glincker/theauth/blob/main/docs/adapters/solidstart.mdx

Complete setup for the SolidStart adapter in a catch-all route. It creates the TheAuth instance, configures the MCP module, defines an authenticate function, and exports the handlers.

```typescript
// src/routes/api/theauth/[...theauth].ts
import { createTheAuth } from '@glinr/theauth';
import { createMcpModule } from '@glinr/theauth/mcp';
import { mcpStore } from './mcp-store'; // storage callbacks, see the MCP page
import { theAuthSolidStart } from '@glinr/theauth-solidstart';

const theauth = await createTheAuth({
  database: { provider: 'postgres', url: process.env.DATABASE_URL! },
  baseUrl: process.env.AUTH_BASE_URL!,
  mcp: { enabled: true }, // creates the MCP tables
});

// baseUrl is the public origin plus the adapter mount path (default /api/theauth)
const mcp = createMcpModule({
  config: {
    enabled: true,
    issuer: process.env.AUTH_BASE_URL!,
    baseUrl: `${process.env.AUTH_BASE_URL!}/api/theauth`,
    signingSecret: process.env.MCP_SIGNING_SECRET!, // at least 32 characters
  },
  ...mcpStore,
});

// Who may call the management routes. Return { id } to allow, null to reject (401).
// resolveUser needs an auth.adapter; with only auth.session, omit authenticate
// and any valid session is accepted.
const authenticate = async (request: Request) => {
  const user = await theauth.auth.resolveUser(request);
  return user ? { id: user.id } : null;
};

const handlers = theAuthSolidStart(theauth, { mcp, authenticate });

export const GET = handlers.GET;
export const POST = handlers.POST;
export const PATCH = handlers.PATCH;
export const DELETE = handlers.DELETE;
export const OPTIONS = handlers.OPTIONS;
```

--------------------------------

### Install TheAuth and Next.js adapter

Source: https://github.com/glincker/theauth/blob/main/README.md

Install the core package and the Next.js adapter with npm. Required before using the Next.js route handler example.

```bash
npm install @glinr/theauth @glinr/theauth-nextjs
```

--------------------------------

### Full example: theAuthTanStack setup

Source: https://github.com/glincker/theauth/blob/main/docs/adapters/tanstack.mdx

Complete example of setting up the TanStack adapter with MCP and authentication. It creates TheAuth, MCP module, and an authenticate function that resolves users. The handlers are exported for the TanStack route.

```typescript
// app/routes/api/theauth.$.ts
import { createTheAuth } from '@glinr/theauth';
import { createMcpModule } from '@glinr/theauth/mcp';
import { mcpStore } from './mcp-store'; // storage callbacks, see the MCP page
import { theAuthTanStack } from '@glinr/theauth-tanstack';

const theauth = await createTheAuth({
  database: { provider: 'postgres', url: process.env.DATABASE_URL! },
  baseUrl: process.env.AUTH_BASE_URL!,
  mcp: { enabled: true }, // creates the MCP tables
});

// baseUrl is the public origin plus the adapter mount path (default /api/theauth)
const mcp = createMcpModule({
  config: {
    enabled: true,
    issuer: process.env.AUTH_BASE_URL!,
    baseUrl: `${process.env.AUTH_BASE_URL!}/api/theauth`,
    signingSecret: process.env.MCP_SIGNING_SECRET!, // at least 32 characters
  },
  ...mcpStore,
});

// Who may call the management routes. Return { id } to allow, null to reject (401).
// resolveUser needs an auth.adapter; with only auth.session, omit authenticate
// and any valid session is accepted.
const authenticate = async (request: Request) => {
  const user = await theauth.auth.resolveUser(request);
  return user ? { id: user.id } : null;
};

const handlers = theAuthTanStack(theauth, { mcp, authenticate });

export const GET = handlers.GET;
export const POST = handlers.POST;
export const PATCH = handlers.PATCH;
export const DELETE = handlers.DELETE;
export const OPTIONS = handlers.OPTIONS;
```

--------------------------------

### Run chi-app example with Docker Compose

Source: https://github.com/glincker/theauth/blob/main/docs/go/getting-started/example-apps.mdx

Commands to clone the repository, set up the chi-app example, start Postgres via Docker Compose, and run the application. The app listens on :8080 by default.

```bash
git clone https://github.com/glincker/theauth-go
cd theauth-go/examples/chi-app
cp .env.example .env
docker-compose up -d  # starts Postgres
make run
```

--------------------------------

### Quickstart: Create agent and authorize

Source: https://github.com/glincker/theauth/blob/main/sdks/go/README.md

Shows how to create a client, create an autonomous agent with permissions, and authorize an action. Prints the authorization result and audit ID.

```go
package main

import (
    "context"
    "fmt"
    "time"

    theauth "github.com/glincker/theauth-go"
)

func main() {
    client := theauth.NewClient("https://your-app.com/api/theauth",
        theauth.WithToken("kv_..."),
        theauth.WithTimeout(10*time.Second),
    )

    ctx := context.Background()

    agent, err := client.Agents.Create(ctx, theauth.CreateAgentInput{
        OwnerID: "user-123",
        Name:    "github-reader",
        Type:    theauth.AgentTypeAutonomous,
        Permissions: []theauth.Permission{
            {Resource: "mcp:github:*", Actions: []string{"read"}},
        },
    })
    if err != nil {
        panic(err)
    }

    result, err := client.Authorize(ctx, agent.ID, theauth.AuthorizeRequest{
        Action:   "read",
        Resource: "mcp:github:repos",
    })
    if err != nil {
        panic(err)
    }

    fmt.Printf("allowed=%v auditId=%s\n", result.Allowed, result.AuditID)
}
```

--------------------------------

### Testing with in-memory SQLite using createTheAuth

Source: https://github.com/glincker/theauth/blob/main/docs/database.mdx

Example of using ':memory:' for isolated tests with no setup or teardown. Each createTheAuth call gets a completely isolated database.

```typescript
import { createTheAuth } from '@glinr/theauth';
import { describe, beforeEach, it } from 'vitest';

let theauth: Awaited<ReturnType<typeof createTheAuth>>;

beforeEach(async () => {
  theauth = await createTheAuth({
    database: { provider: 'sqlite', url: ':memory:' },
    agents: { enabled: true },
  });
});

it('creates an agent', async () => {
  const agent = await theauth.agent.create({
    ownerId: 'user_1',
    name: 'Test Agent',
    type: 'autonomous',
    permissions: [],
  });

  expect(agent.id).toBeDefined();
});
```

--------------------------------

### Install mcpresource with go get

Source: https://github.com/glincker/theauth/blob/main/docs/go/concepts/resource-server.mdx

Install the mcpresource module. It has no third-party dependencies.

```bash
go get github.com/glincker/theauth-go/mcpresource
```

--------------------------------

### First signup with setup token

Source: https://github.com/glincker/theauth/blob/main/docs/go/guides/single-binary-go-app.mdx

Performs the first signup using the setup token in the X-Setup-Token header. After the first user exists, further signups are refused with signup_closed unless OpenSignupAfterFirstUser is set. The first admin must use a password because magic links cannot carry the token.

```sh
curl -c jar -X POST $BASE/auth/email-password/signup \
  -H "X-Setup-Token: $SETUP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"a long passphrase here"}'
```

--------------------------------

### Install storage library with npx expo install

Source: https://github.com/glincker/theauth/blob/main/docs/expo.mdx

Install a storage library for token persistence. The example shows installing @react-native-async-storage/async-storage or expo-secure-store for encrypted storage.

```bash
npx expo install @react-native-async-storage/async-storage
# or for encrypted storage
npx expo install expo-secure-store
```

--------------------------------

### Install @glinr/theauth and @glinr/theauth-tanstack

Source: https://github.com/glincker/theauth/blob/main/docs/adapters/tanstack.mdx

Install the required packages for using theAuth with TanStack Start.

```bash
pnpm add @glinr/theauth @glinr/theauth-tanstack
```

--------------------------------

### Install @glinr/theauth-svelte with pnpm

Source: https://github.com/glincker/theauth/blob/main/docs/svelte.mdx

Install the package using pnpm. Works with Svelte 4+, SvelteKit, and plain Vite setups.

```bash
pnpm add @glinr/theauth-svelte
```

--------------------------------

### Setup main process: create storage and IPC bridge

Source: https://github.com/glincker/theauth/blob/main/docs/electron.mdx

Creates a storage adapter backed by Electron's `safeStorage` API and exposes it to the renderer over IPC using `setupTheAuthIpc`.

```ts
import { app, ipcMain } from 'electron';
import { createElectronStorage, setupTheAuthIpc } from '@glinr/theauth-electron';

const storage = createElectronStorage({ fileName: 'theauth-session.json' });
setupTheAuthIpc(storage);
```

--------------------------------

### Install theauth-go module

Source: https://github.com/glincker/theauth/blob/main/docs/go/guides/add-oauth-provider.mdx

Run this command to install the main module. All provider packages are included in the main module, so no separate install is needed.

```bash
go get github.com/glincker/theauth-go/v2
```

--------------------------------

### Install @glinr/theauth-expo with npm or pnpm

Source: https://github.com/glincker/theauth/blob/main/docs/expo.mdx

Install the @glinr/theauth-expo package using either npm or pnpm. The example shows both commands as alternatives.

```bash
npm install @glinr/theauth-expo
# or
pnpm add @glinr/theauth-expo
```

--------------------------------

### GET /auth/polar/subscription response

Source: https://github.com/glincker/theauth/blob/main/docs/auth/polar-payment.mdx

Example response for the subscription endpoint.

```json
{
  "subscription": {
    "id": "sub_xxx",
    "status": "active",
    "productId": "product_xxx",
    "currentPeriodEnd": "2025-12-31T00:00:00.000Z",
    "cancelAtPeriodEnd": false
  }
}
```

--------------------------------

### Install @glinr/theauth and @glinr/theauth-solidstart

Source: https://github.com/glincker/theauth/blob/main/docs/adapters/solidstart.mdx

Install the required packages for using theAuth with SolidStart.

```bash
pnpm add @glinr/theauth @glinr/theauth-solidstart
```

--------------------------------

### Run the example with pnpm

Source: https://github.com/glincker/theauth/blob/main/examples/migrate-from-better-auth-agent-plugin/README.md

Executes the example using pnpm with the filter for the package @glinr/theauth-example-migrate-from-better-auth-agent-plugin.

```bash
pnpm --filter @glinr/theauth-example-migrate-from-better-auth-agent-plugin start
```

--------------------------------

### Initialize MySQL storage adapter

Source: https://github.com/glincker/theauth/blob/main/docs/go/migrations/v2.3-to-v2.4.mdx

Open a MySQL database connection and create a new storage instance using the mysql adapter. Apply migrations under storage/mysql/migrations/ before first run.

```go
import "github.com/glincker/theauth-go/v2/storage/mysql"

db, _ := sql.Open("mysql", os.Getenv("MYSQL_DSN"))
store := mysql.New(db)
```

--------------------------------

### Install @glinr/theauth-client with npm

Source: https://github.com/glincker/theauth/blob/main/docs/client-sdk.mdx

Install the client package using npm. This is the first step before creating a client.

```bash
npm install @glinr/theauth-client
```

--------------------------------

### GET /auth/users/fields example

Source: https://github.com/glincker/theauth/blob/main/docs/additional-fields.mdx

Read additional fields for a user. The response shows the fields object with plan and credits.

```http
GET /auth/users/fields?userId=usr_abc
```

```json
{ "fields": { "plan": "pro", "credits": 100 } }
```

--------------------------------

### Open SQLite and migrate

Source: https://github.com/glincker/theauth/blob/main/docs/go/guides/single-binary-go-app.mdx

Open a SQLite database with foreign keys, WAL, and busy timeout, then migrate and create the store. Import the driver with _ "modernc.org/sqlite". No cgo is involved, so CGO_ENABLED=0 go build yields a static binary.

```go
db, err := sql.Open("sqlite",
    "file:app.db?_pragma=foreign_keys(1)&_pragma=busy_timeout(5000)&_pragma=journal_mode(WAL)&_txlock=immediate")
if err != nil { log.Fatal(err) }
if err := db.PingContext(ctx); err != nil { log.Fatal(err) }
if err := sqlitestore.Migrate(ctx, db); err != nil { log.Fatal(err) }
store, err := sqlitestore.New(db)
```

--------------------------------

### Install @glinr/theauth and @glinr/theauth-fastify

Source: https://github.com/glincker/theauth/blob/main/packages/adapters/fastify/README.md

Install the required packages using pnpm.

```bash
pnpm add @glinr/theauth @glinr/theauth-fastify
```

--------------------------------

### sw filter request

Source: https://github.com/glincker/theauth/blob/main/docs/auth/scim-filter-reference.mdx

Returns true when the attribute value starts with the comparison value. Example matches 'bjensen', 'bjoern' but not 'barbara'.

```http
GET /scim/v2/Users?filter=userName%20sw%20%22bj%22
```

--------------------------------

### Wire the OpenTelemetry adapter at startup

Source: https://github.com/glincker/theauth/blob/main/docs/go/guides/opentelemetry-tracing.mdx

Creates a theauth.Hooks with the OpenTelemetry tracer and passes it to theauth.New. Requires an existing store and the otelbridge package from the previous example.

```go
import (
    "go.opentelemetry.io/otel"
    "github.com/glincker/theauth-go/v2"
    otelbridge "myapp/internal/otelbridge"
)

hooks := &theauth.Hooks{
    Tracer: otelbridge.New(otel.Tracer("theauth-go")),
}

a, _ := theauth.New(theauth.Config{
    Storage:       store,
    BaseURL:       "https://myapp.com",
    Observability: hooks,
})

```

--------------------------------

### First-run bootstrap configuration

Source: https://github.com/glincker/theauth/blob/main/docs/go/guides/auth-hardening.mdx

Configure the auth instance with a BootstrapConfig to enable first-run setup. Requires Storage to implement UserCountStorage. While no user exists, signup requires a setup token; after the first user, signup returns 403 unless OpenSignupAfterFirstUser is set.

```go
a, _ := theauth.New(theauth.Config{
    Storage:   store, // must implement UserCountStorage
    Bootstrap: &theauth.BootstrapConfig{},
})
```

--------------------------------

### Run development server with pnpm dev

Source: https://github.com/glincker/theauth/blob/main/CONTRIBUTING.md

Starts the development environment with hot-reloading across packages. Expected to be run at the root after initial setup.

```bash
pnpm dev
```

--------------------------------

### Audit log entry response - JSON example

Source: https://github.com/glincker/theauth/blob/main/docs/api.mdx

Example of a 200 OK response for GET /audit. Denied entries also carry a free-text reason. tokensCost appears only on entries that recorded one. The IP address and user agent are stored but not returned.

```json
[
  {
    "id": "aud_01xyz",
    "agentId": "agt_01abc",
    "userId": "user_01abc",
    "action": "write",
    "resource": "mcp:github:create_issue",
    "parameters": { "repo": "org/repo" },
    "result": "allowed",
    "durationMs": 3,
    "timestamp": "2026-03-21T10:00:00.000Z"
  }
]
```

--------------------------------

### Async quick start with TheAuthClient

Source: https://github.com/glincker/theauth/blob/main/sdks/python/README.md

Recommended async usage. Creates an agent with permissions and checks authorization. Uses TheAuthClient with base_url and token. Prints result.allowed.

```python
import asyncio
from theauth import TheAuthClient
from theauth.types import CreateAgentInput
from theauth.permissions import read, with_approval, execute

async def main():
    async with TheAuthClient(
        base_url="https://your-app.com/api/theauth",
        token="kv_...",
    ) as client:
        # Create an agent
        agent = await client.agents.create(
            CreateAgentInput(
                owner_id="user-123",
                name="github-reader",
                type="autonomous",
                permissions=[
                    read("mcp:github:*"),
                    with_approval(execute("mcp:deploy:production")),
                ],
            )
        )

        # Check authorization
        result = await client.authorize(
            agent.id,
            AuthorizeRequest(action="read", resource="mcp:github:repos"),
        )
        print(result.allowed)  # True

asyncio.run(main())
```