@cartanova/qgrid-cli 2.3.8 → 2.4.0

package/README.ko.md

@@ -0,0 +1,131 @@
+# @cartanova/qgrid-cli
+
+[English](./README.md) · **한국어**
+
+Qgrid 서버를 한 줄로 실행. OpenAI/Anthropic 구독 크레딧을 HTTP API + 대시보드로 제공하는 LLM 프록시.
+
+## 설치
+
+```bash
+npm i -g @cartanova/qgrid-cli
+```
+
+설치 시 qgrid skills가 자동 동기화됨:
+
+- global install: `~/.codex/skills/qgrid`, `~/.claude/skills/qgrid`
+- project install: `.agents/skills/qgrid`, `.claude/skills/qgrid`
+
+project install에서는 symlink를 만들고, symlink가 실패하면 copy로 fallback함.
+
+## PostgreSQL 준비
+
+Qgrid는 OAuth 토큰과 request log를 저장하기 위해 PostgreSQL이 필요함.
+이미 접근 가능한 PostgreSQL이 있으면 `--db` 또는 `QGRID_DB_*` 환경변수로 연결하면 됨.
+로컬에 PostgreSQL이 없으면 Docker로 띄울 수 있음:
+
+```bash
+docker run --name qgrid-postgres \
+  -e POSTGRES_USER=postgres \
+  -e POSTGRES_PASSWORD=postgres \
+  -e POSTGRES_DB=qgrid \
+  -p 5432:5432 \
+  -d postgres:18
+```
+
+## 사용법
+
+```bash
+# DB URL로 실행
+qgrid --db postgres://user:password@host:port/dbname
+
+# 포트 지정
+qgrid --db postgres://... -p 3000
+
+# 환경변수로 DB 설정 (플래그 생략 가능)
+export QGRID_DB_HOST=dev.example.com
+export QGRID_DB_PORT=5432
+export QGRID_DB_USER=postgres
+export QGRID_DB_PASSWORD=postgres
+export QGRID_DB_NAME=qgrid
+qgrid
+```
+
+서버가 뜨면 `http://localhost:44900`에서 대시보드 접속 → OAuth 로그인으로 토큰 등록.
+`-p, --port`를 지정하면 해당 포트로 접속.
+
+서버 포트는 기본값 `44900` 또는 `--port`로만 결정됨. `PORT` 환경변수는 CLI 서버 포트 입력으로 사용하지 않음.
+선택한 포트가 이미 사용 중이면 기존 프로세스를 종료하거나 다른 포트로 폴백하지 않고 에러와 함께 종료.
+
+Ctrl+C로 종료.
+
+## 옵션
+
+```
+qgrid [options]
+
+  --db <url>         PostgreSQL 연결 URL
+  -p, --port <port>  서버 포트 (기본: 44900)
+  --skip-update      자동 업데이트 확인 생략
+  -V, --version      버전 출력
+  -h, --help         도움말
+```
+
+CLI는 실행 시 npm의 최신 버전을 확인하고 patch를 포함해 설치된 버전과 다르면 자동 업데이트함.
+업데이터는 방금 확인한 정확한 배포 버전을 설치하고 업데이트된 binary로 재시작함.
+
+## 환경변수
+
+`--db` 플래그가 없으면 아래 환경변수에서 DB 접속 정보를 읽음:
+
+| 변수 | 기본값 |
+|------|--------|
+| `QGRID_DB_HOST` | `localhost` |
+| `QGRID_DB_PORT` | `5432` |
+| `QGRID_DB_USER` | `postgres` |
+| `QGRID_DB_PASSWORD` | `postgres` |
+| `QGRID_DB_NAME` | `qgrid` |
+
+서버 동작 관련 환경변수:
+
+| 변수 | 설명 | 기본값 |
+|------|------|--------|
+| `QGRID_WORKERS_PER_TOKEN` | OpenAI 토큰당 codex worker 수 | `3` (최대 5) |
+| `QGRID_PUBLIC_BASE_URL` | Anthropic OAuth callback 공개 베이스 URL. 원격 접속 환경에서 설정 | 미설정 시 `http://localhost:<port>/callback` |
+| `QGRID_OPENAI_THREAD_REUSE` | `false`로 설정 시 OpenAI thread reuse(prompt cache) 비활성화 | 활성 |
+
+## 사전 요구사항
+
+- Node.js >= 20
+- PostgreSQL
+- Docker (로컬 PostgreSQL을 컨테이너로 실행할 경우)
+- [Codex CLI](https://github.com/openai/codex) (OpenAI 모델 사용 시)
+- [Claude Code](https://www.anthropic.com/claude-code) (Anthropic 모델 사용 시)
+
+## 동작 방식
+
+CLI는 Sonamu 기반 서버를 내장 번들로 포함. 실행 시:
+
+1. DB 연결 확인
+2. 서버 시작 (API + 대시보드 웹 UI)
+3. DB의 등록된 토큰 로드. 이후 토큰 등록/변경은 PostgreSQL LISTEN/NOTIFY로 실행 중인 서버에 실시간 반영
+4. **OpenAI 토큰**: 토큰당 persistent codex app-server 프로세스 N개 spawn (기본 3, 최대 5). JSON-RPC로 통신. 요청은 idle worker에 round-robin 라우팅, 전부 busy면 큐 대기 (최대 60초). `sessionKey` 멀티턴 요청은 같은 thread로 재라우팅되어 prompt cache 적중
+5. **Anthropic 토큰**: 요청마다 격리된 claude 프로세스를 fresh spawn (`stream-json` 입출력). 토큰은 least-used 우선으로 선택. OAuth 토큰 자동 refresh
+6. 토큰별 quota threshold(기본 80%)를 넘은 토큰은 라우팅에서 제외 (사용률 조회 실패 시에는 fail-open으로 통과)
+
+Qgrid 앱 자체는 Docker에 의존하지 않지만 PostgreSQL은 필요함. 로컬 PostgreSQL이 없으면 Docker로 PostgreSQL을 띄우는 구성이 가장 간단함.
+
+## SDK 연동
+
+서버를 띄운 뒤 [`@cartanova/qgrid-ai-sdk`](../ai-sdk/README.ko.md)로 호출:
+
+```typescript
+import { generateText } from "ai";
+import { qgrid } from "@cartanova/qgrid-ai-sdk";
+
+const { text } = await generateText({
+  model: qgrid("openai/gpt-5.4-mini"),
+  prompt: "서울 날씨 알려줘",
+});
+```
+
+자세한 사용법은 [`@cartanova/qgrid-ai-sdk` README](../ai-sdk/README.ko.md) 참조.

package/README.md

@@ -1,18 +1,27 @@
 # @cartanova/qgrid-cli
 
-Qgrid 서버를 한 줄로 실행. OpenAI/Anthropic 구독 크레딧을 HTTP API + 대시보드로 제공하는 LLM 프록시.
+**English** · [한국어](./README.ko.md)
 
-## 설치
+Run the Qgrid server in one line. An LLM proxy that exposes OpenAI/Anthropic subscription credits as an HTTP API + dashboard.
+
+## Install
 
 ```bash
 npm i -g @cartanova/qgrid-cli
 ```
 
-## PostgreSQL 준비
+Installing also syncs the qgrid skills automatically:
+
+- global install: `~/.codex/skills/qgrid`, `~/.claude/skills/qgrid`
+- project install: `.agents/skills/qgrid`, `.claude/skills/qgrid`
+
+Project installs create symlinks, falling back to copies when symlinking fails.
 
-Qgrid는 OAuth 토큰과 request log를 저장하기 위해 PostgreSQL이 필요함.
-이미 접근 가능한 PostgreSQL이 있으면 `--db` 또는 `QGRID_DB_*` 환경변수로 연결하면 됨.
-로컬에 PostgreSQL이 없으면 Docker로 띄울 수 있음:
+## Preparing PostgreSQL
+
+Qgrid needs PostgreSQL to store OAuth tokens and request logs.
+If you already have a reachable PostgreSQL, connect with `--db` or the `QGRID_DB_*` environment variables.
+If you don't have one locally, you can spin one up with Docker:
 
 ```bash
 docker run --name qgrid-postgres \
@@ -23,16 +32,16 @@ docker run --name qgrid-postgres \
   -d postgres:18
 ```
 
-## 사용법
+## Usage
 
 ```bash
-# DB URL로 실행
+# Run with a DB URL
 qgrid --db postgres://user:password@host:port/dbname
 
-# 포트 지정
+# Specify a port
 qgrid --db postgres://... -p 3000
 
-# 환경변수로 DB 설정 (플래그 생략 가능)
+# Configure the DB with environment variables (flags can be omitted)
 export QGRID_DB_HOST=dev.example.com
 export QGRID_DB_PORT=5432
 export QGRID_DB_USER=postgres
@@ -41,66 +50,73 @@ export QGRID_DB_NAME=qgrid
 qgrid
 ```
 
-서버가 뜨면 `http://localhost:44900`에서 대시보드 접속 → OAuth 로그인으로 토큰 등록.
-`-p, --port`를 지정하면 해당 포트로 접속.
+Once the server is up, open the dashboard at `http://localhost:44900` → register tokens through OAuth login.
+With `-p, --port` set, connect on that port instead.
 
-서버 포트는 기본값 `44900` 또는 `--port`로만 결정됨. `PORT` 환경변수는 CLI 서버 포트 입력으로 사용하지 않음.
-선택한 포트가 이미 사용 중이면 기존 프로세스를 종료하거나 다른 포트로 폴백하지 않고 에러와 함께 종료.
+The server port is determined only by the default `44900` or `--port`. The `PORT` environment variable is not read as CLI server port input.
+If the selected port is already in use, the CLI exits with an error instead of killing the existing process or falling back to another port.
 
-Ctrl+C로 종료.
+Stop with Ctrl+C.
 
-## 옵션
+## Options
 
 ```
 qgrid [options]
 
-  --db <url>         PostgreSQL 연결 URL
-  -p, --port <port>  서버 포트 (기본: 44900)
-  --skip-update      자동 업데이트 확인 생략
-  -V, --version      버전 출력
-  -h, --help         도움말
+  --db <url>         PostgreSQL connection URL
+  -p, --port <port>  Server port (default: 44900)
+  --skip-update      Skip the automatic update check
+  -V, --version      Print version
+  -h, --help         Help
 ```
 
-CLI는 실행 시 npm의 최신 버전을 확인하고 major/minor 버전이 올라간 경우에만 자동 업데이트함.
-patch 버전 차이는 자동 업데이트 대상으로 보지 않음.
+On startup the CLI checks the latest version on npm and self-updates whenever the installed version differs, including patch releases.
+The updater installs the exact published version it just resolved and restarts from the updated binary.
 
-## 환경변수
+## Environment variables
 
-`--db` 플래그가 없으면 아래 환경변수에서 DB 접속 정보를 읽음:
+Without the `--db` flag, DB connection info is read from:
 
-| 변수 | 기본값 |
+| Variable | Default |
 |------|--------|
 | `QGRID_DB_HOST` | `localhost` |
 | `QGRID_DB_PORT` | `5432` |
 | `QGRID_DB_USER` | `postgres` |
 | `QGRID_DB_PASSWORD` | `postgres` |
 | `QGRID_DB_NAME` | `qgrid` |
-| `QGRID_WORKERS_PER_TOKEN` | `3` (OpenAI 토큰당 codex worker 수, 최대 5) |
 
-## 사전 요구사항
+Server behavior variables:
+
+| Variable | Description | Default |
+|------|------|--------|
+| `QGRID_WORKERS_PER_TOKEN` | codex workers per OpenAI token | `3` (max 5) |
+| `QGRID_PUBLIC_BASE_URL` | Public base URL for the Anthropic OAuth callback. Set it when the server is accessed remotely | `http://localhost:<port>/callback` when unset |
+| `QGRID_OPENAI_THREAD_REUSE` | Set to `false` to disable OpenAI thread reuse (prompt caching) | enabled |
+
+## Prerequisites
 
 - Node.js >= 20
 - PostgreSQL
-- Docker (로컬 PostgreSQL을 컨테이너로 실행할 경우)
-- [Codex CLI](https://github.com/openai/codex) (OpenAI 모델 사용 시)
-- [Claude Code](https://www.anthropic.com/claude-code) (Anthropic 모델 사용 시)
+- Docker (if running PostgreSQL locally as a container)
+- [Codex CLI](https://github.com/openai/codex) (for OpenAI models)
+- [Claude Code](https://www.anthropic.com/claude-code) (for Anthropic models)
 
-## 동작 방식
+## How it works
 
-CLI는 Sonamu 기반 서버를 내장 번들로 포함. 실행 시:
+The CLI ships the Sonamu-based server as a built-in bundle. On launch:
 
-1. DB 연결 확인
-2. 서버 시작 (API + 대시보드 웹 UI)
-3. DB의 등록된 토큰 로드
-4. **OpenAI 토큰**: 토큰당 codex app-server 프로세스 N개 spawn (기본 3). JSON-RPC로 통신. 병렬 요청 처리 + 큐잉.
-5. **Anthropic 토큰**: claude CLI를 통한 호출. OAuth 토큰 자동 refresh.
-6. 요청 도착 → idle worker에 라우팅 (round-robin) → 전부 busy면 큐 대기 (최대 60초)
+1. Verify the DB connection
+2. Start the server (API + dashboard web UI)
+3. Load registered tokens from the DB. Later token additions/changes propagate to the running server in real time via PostgreSQL LISTEN/NOTIFY
+4. **OpenAI tokens**: spawn N persistent codex app-server processes per token (default 3, max 5), communicating over JSON-RPC. Requests are routed round-robin across idle workers; when all are busy they queue (up to 60 seconds). Multi-turn requests carrying a `sessionKey` are routed back to the same thread for prompt-cache hits
+5. **Anthropic tokens**: spawn a fresh, isolated claude process per request (`stream-json` in/out). Tokens are selected least-used-first. OAuth tokens are refreshed automatically
+6. Tokens over their quota threshold (default 80%) are excluded from routing (usage-lookup failures fail open)
 
-Qgrid 앱 자체는 Docker에 의존하지 않지만 PostgreSQL은 필요함. 로컬 PostgreSQL이 없으면 Docker로 PostgreSQL을 띄우는 구성이 가장 간단함.
+The Qgrid app itself does not depend on Docker, but PostgreSQL is required. If you don't run PostgreSQL locally, running it in Docker is the simplest setup.
 
-## SDK 연동
+## SDK integration
 
-서버를 띄운 뒤 [`@cartanova/qgrid-ai-sdk`](../ai-sdk/README.md)로 호출:
+Once the server is running, call it with [`@cartanova/qgrid-ai-sdk`](../ai-sdk/README.md):
 
 ```typescript
 import { generateText } from "ai";
@@ -108,8 +124,8 @@ import { qgrid } from "@cartanova/qgrid-ai-sdk";
 
 const { text } = await generateText({
   model: qgrid("openai/gpt-5.4-mini"),
-  prompt: "서울 날씨 알려줘",
+  prompt: "What's the weather in Seoul?",
 });
 ```
 
-자세한 사용법은 [`@cartanova/qgrid-ai-sdk` README](../ai-sdk/README.md) 참조.
+See the [`@cartanova/qgrid-ai-sdk` README](../ai-sdk/README.md) for details.