GenAuth CLI

genauth-cli is the command line tool for GenAuth. It is designed for both developers and agents, allowing interactive setup for humans and stable non-interactive execution for scripts, CI, and autonomous agents.

The CLI manages user pools, applications, OIDC scopes, and the configuration needed to integrate an OIDC client.

Requirements

• Node.js >= 20
• pnpm
• A reachable Genauth server. The default is https://console.genauth.ai
• Management credentials: AccessKey ID/Secret, or a server environment that supports CLI browser login

In a local development environment, enter the CLI project:

cd ../genauth-cli
pnpm install
pnpm build

For local development:

pnpm dev -- --help

After build:

node dist/index.js --help

Login

The CLI supports two login modes.

AccessKey login

AccessKey login is the recommended mode for scripts, CI, and agents. It exchanges an AccessKey ID/Secret for a management token and stores the server, active user pool, and token in the local profile.

genauth login \
  --access-key-id <userpool-id> \
  --access-key-secret <access-key-secret>

Browser login

Browser login is intended for interactive local development.

genauth login --browser

The CLI opens a browser for authorization and stores the resulting session in the active profile.

Profiles and environment

Profiles store different server, user pool, and token contexts.

genauth config set server https://console.genauth.ai
genauth config get

Use separate profiles for different environments:

genauth config set server http://localhost:3000 --profile dev
genauth login --profile dev --browser
genauth userpools use <userpool-id> --profile dev

Common environment variables:

export GENAUTH_SERVER=http://localhost:3000
export GENAUTH_USERPOOL_ID=<userpool-id>

Command line flags override environment variables. Environment variables override profile values.

User pools

A user pool is the main resource isolation boundary in GenAuth. Applications and OIDC scopes are managed inside a user pool.

genauth userpools list
genauth userpools get <userpool-id>
genauth userpools create --name Demo --domain demo
genauth userpools use <userpool-id>

After setting the active user pool, later app and scope commands use it by default.

Applications

Application commands create and manage OIDC applications.

genauth apps list
genauth apps get <app-id>

Create a Web OIDC application:

genauth apps create \
  --name Demo \
  --identifier demo \
  --type web \
  --callback http://localhost:3000/callback \
  --logout-callback http://localhost:3000/logout

Update callback URLs:

genauth apps update <app-id> \
  --callback http://localhost:3000/callback

Read or rotate the application secret:

genauth apps secret <app-id>
genauth apps rotate-secret <app-id> --yes

Deleting an application requires explicit confirmation:

genauth apps delete <app-id> --yes

OIDC setup

oidc setup is the recommended quick path. It creates an OIDC application, configures redirect URLs, optionally creates custom scopes, and prints the integration settings.

genauth oidc setup \
  --app-name Demo \
  --identifier demo \
  --callback http://localhost:3000/callback \
  --logout-callback http://localhost:3000/logout

The output includes:

• issuer
• authorization_endpoint
• token_endpoint
• userinfo_endpoint
• jwks_uri
• client_id
• client_secret
• redirect_uris

Authorization server scopes

auth-servers scopes manages the custom scopes and claims that an OIDC application can request. These scopes express the access boundary for business APIs inside the OIDC authorization request.

genauth auth-servers scopes list --app <app-id>

Create a custom scope:

genauth auth-servers scopes create \
  --app <app-id> \
  --name orders:read \
  --claim orders

Update or delete a scope:

genauth auth-servers scopes update <scope-id> --app <app-id> --name orders:write
genauth auth-servers scopes delete <scope-id> --app <app-id> --yes

Agent and CI usage

Agents and CI jobs should use non-interactive flags and JSON output.

genauth oidc setup \
  --userpool "$GENAUTH_USERPOOL_ID" \
  --app-name Demo \
  --identifier demo \
  --callback http://localhost:3000/callback \
  --scope orders:read \
  --claim orders \
  --json \
  --no-input

Recommended conventions:

• Use --json for stable machine-readable output.
• Use --no-input to disable prompts and fail fast when required input is missing.
• Use genauth config set server <url> to persist the server instead of passing --server every time.
• Use --profile to isolate dev, staging, and production contexts.
• Always pass --yes for destructive actions such as deletion and secret rotation.

Output

By default, output is human-readable and lists are rendered as tables. With --json, the CLI emits stable JSON for agents and scripts.

genauth apps list --json

For debugging API responses:

DEBUG=1 genauth apps list --json

Next step

Read GenAuth to understand the identity and authorization boundary, then use genauth oidc setup to create your first OIDC application.