@oiioii/cli 0.1.1 → 0.1.6

package/README.md

@@ -12,7 +12,9 @@ human-readable output and a stable JSON envelope for AI agents and automation.
 
 | Command | Capability | Status |
 |---|---|---|
-| `auth login` | Persist API Key and backend configuration | Implemented |
+| `auth login` | Browser authorization for terminal/Codex/WorkBuddy/Kimi/Claude Code/DeepSeek, or explicit API Key persistence | Implemented |
+| `auth status` | Check configured authentication without exposing the API Key | Implemented |
+| `auth logout` | Remove locally persisted authentication without exposing the API Key | Implemented |
 | `workspace create/set/current/rename` | Create, configure, inspect, and rename workspaces | Implemented |
 | `workspace assets list/download` | List workspace assets and download ready resources | Implemented |
 | `image text` | Text-to-image generation | Implemented |
@@ -44,7 +46,7 @@ Important current limitations:
 ## Requirements
 
 - Node.js 18.18 or newer when running from source or the npm package.
-- An existing Hogi MCP API Key.
+- A Hogi account for browser authorization, or an existing Hogi MCP API Key.
 - A workspace ID for image/video/audio generation and resource upload. It can be
   created with `oiioii workspace create` or supplied from an existing project.
 - `npm` is the repository package manager.
@@ -123,20 +125,20 @@ rebuilt from the checkout.
 
 ## Build Environments
 
-The default backend URL is embedded into the generated bundle at build time.
+The default backend URL and browser authorization page are embedded into the generated bundle at build time.
 
-| Build command | Environment | Embedded default backend |
-|---|---|---|
-| `npm run build:production` | production | `OIIOII_PRODUCTION_BASE_URL` from `.env` |
-| `npm run build:test` | test | `OIIOII_TEST_BASE_URL` from `.env` |
-| `npm run build:local` | local | `http://localhost:4000` |
+| Build command | Environment | Embedded default backend | Authorization page |
+|---|---|---|---|
+| `npm run build:production` | production | `https://api.oiioii.ai` (optional `OIIOII_PRODUCTION_BASE_URL` override) | `https://oiioii.tv/auth/cli` |
+| `npm run build:test` | test | `OIIOII_TEST_BASE_URL` from `.env` | Build-specific test authorization page |
+| `npm run build:local` | local | `http://localhost:4000` | `http://localhost:3000/auth/cli` |
 
-Copy the environment template once, then use the environment-specific build
-entry points:
+Use the environment-specific build entry points. Only test builds require a
+URL in `.env`:
 
 ```bash
-cp .env.example .env
 npm run build:production
+cp .env.example .env
 npm run build:test
 ```
 
@@ -168,8 +170,36 @@ The embedded URL is a fallback. Existing runtime overrides remain available:
 
 ## Authentication and Workspace
 
-Persist an existing MCP API Key. The CLI keeps the backend URL embedded for its
-build environment unless you explicitly override it:
+Authorize through the Hogi browser page for the application that launched the CLI:
+
+```bash
+oiioii auth login
+oiioii auth login --codex
+oiioii auth login --workbuddy
+oiioii auth login --kimi
+oiioii auth login --claude-code
+oiioii auth login --deepseek
+```
+
+Without an application option, `auth login` opens the browser authorization page
+and asks the user to return to the terminal when authorization completes. The
+application options label the authorization for the selected host. Codex and
+WorkBuddy use verified macOS/Windows activation contracts; other targets print
+the localized manual-return fallback when no verified OS activation contract is
+available. The browser flow uses a loopback callback, state validation, and PKCE. It creates
+an API Key through the current build's backend, stores it locally, and requests
+that macOS or Windows return to the selected application after the hosted success
+page acknowledges it is ready, with a bounded fallback if that acknowledgement is blocked. If the browser or app
+cannot be opened, the CLI prints a localized manual fallback. Use `--no-browser`
+to print the authorization URL for a headless environment.
+
+Browser authorization only runs against the backend paired with the current CLI
+build. Remove `OIIOII_BASE_URL` and use `--reset-base-url` when an older persisted
+override is present. For a custom backend, use the explicit `--api-key` mode.
+
+You can still persist an existing MCP API Key only through the explicit
+`--api-key` mode. The CLI keeps the backend URL
+embedded for its build environment unless you explicitly override it:
 
 ```bash
 oiioii auth login --api-key "oii_sk_..."
@@ -180,6 +210,23 @@ The CLI writes the API Key to `~/.oiioii/config.json` with file permissions
 `OIIOII_API_KEY` remains available as a temporary process override. A legacy
 `~/.oiioii/credentials.json` file, if present, is ignored.
 
+Check whether the current process is authenticated, or remove the locally
+persisted API Key:
+
+```bash
+oiioii auth status
+oiioii auth logout
+```
+
+Neither command prints the API Key. `auth status` exits with status `0` when an
+API Key is configured for the current process and `1` when unauthenticated. It identifies only whether
+the credential comes from local configuration or `OIIOII_API_KEY`. `auth logout`
+is idempotent and preserves unrelated settings such as the Base URL and active
+workspace. It cannot unset an inherited `OIIOII_API_KEY`; when that override is
+present, the command reports that effective authentication remains active. If
+the local config is unreadable, logout removes that unusable file so credential
+fragments cannot remain on disk.
+
 Remove an existing backend override and return to the default embedded in the
 current CLI build:
 
@@ -717,15 +764,43 @@ feature.started
   -> feature.completed | feature.failed
 ```
 
-This is CLI-side observability only. It does not collect or depend on logs from
-inside the Hogi backend.
-
-Recorded API events use the same `request_id` for correlation:
+Logs remain local; backend response IDs link them to server logs without
+downloading server logs. Recorded API events use the same `clientRequestId`
+(also stored as the backwards-compatible `request_id`) for local correlation:
 
 ```text
 api.request -> api.response | api.error
 ```
 
+| Field | Meaning |
+| --- | --- |
+| `id` | Unique local log record ID, not a backend chain ID. |
+| `trace_id` | One CLI command, including all of its HTTP calls. |
+| `clientRequestId` / legacy `request_id` | One local API call, pairing its start and result/error. |
+| `logid` | Backend chain ID read from response header `x-logid`. |
+| `requestId` | Current gateway request ID read from response header `x-request-id`; never generated by CLI. |
+| `uid` | Server request identity returned in `x-hogi-log-uid`, or already verified for the command's endpoint/credential. Public routes can return `anonymous_user`. |
+| `workspaceId` | Explicit business target, command workspace, or `x-hogi-log-workspace-id` from the response. |
+
+CLI sends an optional `x-workspace-id` diagnostic hint. Authentication still uses
+the API Key; neither a client-provided uid nor a workspace hint authorizes access.
+Incoming response fields are optional, including when talking to older servers.
+Malformed/missing diagnostics and logging failures do not reject requests.
+
+Before the response arrives, `api.request` cannot know its backend/gateway IDs.
+They appear on `api.response` or `api.error` after receiving headers. Network
+failures without a response legitimately have neither. Follow `clientRequestId`
+back to the start event and `trace_id` to other steps of the command. Command
+steps do not inherit the last HTTP request's `logid` or `requestId`: concurrent
+calls, polling and follow-up requests retain their own IDs. The REST envelope's
+legacy `request_id` is another API-generated ID, not the gateway `requestId`.
+
+Resource downloads retain IDs from the backend's 302 redirect and emit
+`api.redirect` before following the CDN URL. Cross-origin redirects strip
+credentials and workspace hints; CDN request IDs do not replace backend IDs.
+Public resource reads retain their existing anonymous access/watermark behavior;
+an anonymous response does not erase the command's previously verified identity.
+
 Feature traces cover workspace, image/video/audio generation, upload, records,
 inspection, preview, task commands, and their local storage steps. API boundary
 events cover:
@@ -733,10 +808,12 @@ events cover:
 - GenAI and Asset MCP calls.
 - Resource upload and download.
 - Generation-record lookup.
+- Workspace REST, debug APIs, model catalog and authorization exchange.
+- Each VOD token, commit and polling HTTP request (third-party byte upload is separate).
 
 Logs contain safe operational fields such as source, operation, HTTP method,
 path, status, duration, and selected non-sensitive metadata. They do not record
-request headers, API Keys, bearer tokens, prompts, request bodies, or response
+arbitrary request headers, API Keys, bearer tokens, prompts, request bodies, or response
 bodies. Sensitive key names and recognizable secret values are redacted again
 inside the central logger before persistence.
 
@@ -759,6 +836,9 @@ oiioii logs list --category api --level error --limit 20 --json
 oiioii logs list --source hogi_mcp_client --since 2026-08-14T00:00:00Z --json
 oiioii logs list --feature image.text --json
 oiioii logs list --trace trace_<id> --json
+oiioii logs list --logid <backend-logid> --json
+oiioii logs list --request-id <gateway-requestId> --json
+oiioii logs list --uid <uid> --workspace-id <workspaceId> --json
 ```
 
 Export logs as JSONL or JSON:
@@ -838,8 +918,9 @@ Environment variables:
 | `OIIOII_BASE_URL` | Override the backend URL at runtime |
 | `OIIOII_WORKSPACE_ID` | Override the active workspace |
 | `OIIOII_BUILD_ENV` | Select `production`, `test`, or `local` while building |
-| `OIIOII_PRODUCTION_BASE_URL` | URL embedded by the production build |
+| `OIIOII_PRODUCTION_BASE_URL` | Optional override for the production build's canonical backend URL |
 | `OIIOII_TEST_BASE_URL` | URL embedded by the test build |
+| `OIIOII_TEST_AUTHORIZATION_PAGE_URL` | Browser authorization page embedded by the test build |
 | `OIIOII_BUILD_BASE_URL` | One-off URL override for a local/custom build; rejected by publish preparation |
 | `OIIOII_API_KEY` | Temporarily override the persisted API Key for the current process |
 | `OIIOII_E2E` | Explicit opt-in marker for credit-consuming E2E workflows |