API reference

Core API

The headless engine. Every function takes an optional TokenStore; the default is an encrypted file store.

imports

import {
  login,
  startLogin,
  startDeviceLogin,
  logout,
  getSession,
  refresh,
  createClient
} from "loginwithchatgpt";

Functions

login() — loopback OAuth flow (desktop/local), stores tokens.
startDeviceLogin() — device-code flow for web/headless; returns { userCode, verificationUrl, wait }.
startLogin() — headless paste flow for SSH/CI; returns { url, complete }.
getSession() — current session, or null.
refresh() — force a token refresh.
logout() — clear stored tokens.
createClient() — a client with respond(prompt) and stream(prompt).

Login flows

1. Loopback (desktop / CLI)

Auto-opens the browser and catches the redirect on localhost:1455. No user copy-paste needed. Use this for Electron apps, local CLIs, and local-first Next.js dev tools.

login() — loopback

import { login } from "loginwithchatgpt";

// Opens the browser automatically and waits for the user to approve.
// Best for desktop apps, Electron, and local CLIs.
const session = await login({
  onUrl: (url) => console.log("Open this if the browser doesn't open:", url),
});
console.log(session.account.email); // aniki123@gmail.com

2. Device code (web / Next.js / Docker)

Shows a short code the user enters at an OpenAI page. Works on any server or container — no localhost redirect needed. This is what the playground on this site uses. Requires enabling device code login: ChatGPT → Settings → Security & Login → Allow device code login.

startDeviceLogin() — device code

import { startDeviceLogin } from "loginwithchatgpt";

// Shows a short code the user enters on an OpenAI page.
// Works anywhere — web servers, Next.js, Docker, remote machines.
// Requires: ChatGPT → Settings → Security & Login → Allow device code login
const flow = await startDeviceLogin();

console.log("Enter this code at:", flow.verificationUrl);
console.log("Code:", flow.userCode); // e.g. ABCD-1234

const session = await flow.wait(); // polls until the user enters the code
console.log(session.account.email);

3. Headless paste (SSH / CI)

Prints the auth URL for the user to open in any browser on any machine, then waits for them to paste the redirect URL back. Pure fallback — use this when there is no browser at all, e.g. an SSH session or a CI pipeline.

startLogin() — headless paste

import { startLogin } from "loginwithchatgpt";

// Prints a URL for the user to open in any browser, then waits for them
// to paste the redirect URL (or just the code) back.
// Fallback for SSH sessions and CI where there's no browser at all.
const flow = startLogin();

console.log("Open this URL and approve:", flow.url);
const pasted = await readLine("Paste the redirect URL: "); // your own stdin helper

const session = await flow.complete(pasted); // accepts the full URL or just the code
console.log(session.account.email);

Models

These models work with the ChatGPT subscription backend. They are not the same as direct OpenAI API models — they only work when the user is signed in with a ChatGPT Plus or Pro account.

Model	Description	Plan
gpt-5.5	Newest frontier model. Best for complex coding. (default)	Plus / Pro
gpt-5.4	Flagship. Strong coding, reasoning, tool use.	Plus / Pro
gpt-5.4-mini	Faster, lighter. Good for quick tasks and subagents.	Plus / Pro
gpt-5.3-codex-spark	Near-instant coding iteration. Research preview.	Pro only

pick a model

// default is gpt-5.5; override per call
const text = await createClient().respond("Refactor this", { model: "gpt-5.4-mini" });

// streaming
for await (const delta of createClient().stream("Write tests", { model: "gpt-5.4" })) {
  process.stdout.write(delta);
}

Token storage

Tokens are encrypted at rest (AES-256-GCM) with a key kept in the OS keychain where available. Storage is pluggable through the TokenStore interface.

custom store

import { createClient, type TokenStore } from "loginwithchatgpt";

const myStore: TokenStore = { load, save, clear };
const client = createClient(myStore);

Entry points

loginwithchatgpt — engine (Node).
loginwithchatgpt/react — button + hook (browser).
loginwithchatgpt/next — App Router handlers (Node).

Back to the Quickstart.