@talesofai/neta-skills 0.15.3 → 0.16.2

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @neta/skills-neta
 
+## 0.16.2
+
+### Patch Changes
+
+- fix auth api endpoint
+
+## 0.16.1
+
+### Patch Changes
+
+- fix some env problems
+
+## 0.16.0
+
+### Minor Changes
+
+- support oauth2 device flow with login command
+
 ## 0.15.3
 
 ### Patch Changes

package/README.md

@@ -1,7 +1,7 @@
 # NETA Skills
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node](https://img.shields.io/badge/Node-%3E%3D20-green)](https://nodejs.org/)
+[![Node](https://img.shields.io/badge/Node-%3E%3D22-green)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
 
 [English](./README.md) · [简体中文](./README.zh_cn.md)
@@ -12,7 +12,7 @@
 
 **NETA Skills** is a collection of powerful AI agent skills and accompanying CLI tools designed for interacting with the [Neta Art](https://www.neta.art/) API. Built for developers and AI agents, it seamlessly extends any agent's capabilities to generate multimedia, manage characters, and process audio/video workflows.
 
-You can get your access token / NETA TOKEN from the [Neta Open Portal](https://www.neta.art/open/).
+You can get your access token (`NETA_TOKEN`) from the [Neta Open Portal](https://www.neta.art/open/). On the **global** API host, you may also sign in with the CLI `login` command (OAuth device flow) instead of pasting a token into every environment—see [Authentication](#authentication-neta_token-vs-login) below.
 
 ---
 
@@ -26,6 +26,7 @@ You can get your access token / NETA TOKEN from the [Neta Open Portal](https://w
 - 🧭 **Smart Discovery & Suggestions:** Explore interactive feeds and get keyword, tag, and category suggestions for progressive content discovery.
 - 📖 **Interactive Story Adventures:** Craft and play AI-driven narrative campaigns (Adventure) — the agent acts as DM and character roleplayer for immersive interactive fiction.
 - 🤖 **Agent First:** Designed from the ground up to plug into your favorite AI agent frameworks.
+- 🔐 **CLI sign-in (optional):** On the **global** API host (`api.talesofai.com`), you can use OAuth **device authorization** via `neta login` instead of copying `NETA_TOKEN` into every environment.
 
 ---
 
@@ -68,10 +69,12 @@ npx skills add talesofai/neta-skills/skills/neta-adventure
 
 ### Available Commands
 
-The skill includes **42 commands** for various tasks:
+The skill includes **45 commands** for various tasks:
 
 | Category | Command | Description |
 |----------|---------|-------------|
+| **User** | `login` | Start OAuth device login (`request-code`) or complete it (`verify-code`); stores tokens locally on success |
+| | `logout` | Clear stored CLI session (access token and any in-progress device flow) |
 | **Adventure Campaigns** | `create_adventure_campaign` | Create an AI-driven interactive story adventure |
 | | `update_adventure_campaign` | Update an existing adventure campaign |
 | | `list_my_adventure_campaigns` | List your created adventure campaigns |
@@ -139,6 +142,30 @@ Configure your environment:
 export NETA_TOKEN=your_token_here
 ```
 
+### Authentication (`NETA_TOKEN` vs `login`)
+
+You can authenticate in either of these ways:
+
+1. **Environment token (works everywhere)**  
+   Set `NETA_TOKEN` from the [Neta Open Portal](https://www.neta.art/open/). The CLI and API client send it as the `x-token` header when no stored session exists.
+
+2. **CLI device login (global API only)**  
+   When `NETA_API_BASE_URL` points at the **global** host (`…talesofai.com`), you can run:
+
+   ```bash
+   npx -y @talesofai/neta-skills@latest login
+   ```
+
+   The command returns OAuth device fields. Open **`verification_uri_complete`** in a browser, finish sign-in, then run:
+
+   ```bash
+   npx -y @talesofai/neta-skills@latest login --action verify-code
+   ```
+
+   On success, tokens are stored under the app config directory (see `NETA_CONFIG_DIR` below). Subsequent API calls use `Authorization: Bearer …` until the session expires or you run `logout`.
+
+If the CLI reports that login is not supported for your **region** (non-global API), use `NETA_TOKEN` instead.
+
 ### Running Commands
 
 ```bash
@@ -180,7 +207,7 @@ neta-skills/
 │       └── neta-adventure/
 ├── src/                            # TypeScript source for the CLI
 │   ├── apis/                       # Typed Neta API client helpers (incl. commerce)
-│   ├── commands/                   # CLI command groups: creative, community, adventure, VToken, premium, …
+│   ├── commands/                   # CLI command groups: user, creative, community, adventure, VToken, premium, …
 │   ├── utils/                      # Shared utilities
 │   └── cli.ts                      # CLI entrypoint (TypeScript)
 ├── bin/                            # Built JavaScript output for the CLI
@@ -221,10 +248,15 @@ Both the AI agent skills and the CLI require the following environment configura
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `NETA_TOKEN` | ✅ | - | Your Neta Art API access token. |
-| `NETA_API_BASE_URL` | ❌ | default: `https://api.talesofai.com` | Base URL for the Neta API. |
+| `NETA_TOKEN` | Conditional* | - | API access token from the [Neta Open Portal](https://www.neta.art/open/). Required when not using a CLI session from `login`. |
+| `NETA_API_BASE_URL` | ❌ | `https://api.talesofai.com` | Base URL for the Neta API. Device login is only available when this resolves to the **global** host (`…talesofai.com`). |
+| `NETA_AUTH_API_BASE_URL` | ❌ | derived from `NETA_API_BASE_URL` | OIDC / token endpoints for `login` and refresh (override for custom stacks). |
+| `NETA_CLIENT_ID` | ❌ | built-in public client id | OAuth client id for device login and refresh. |
+| `NETA_CONFIG_DIR` | ❌ | OS-specific config path | Directory where the CLI stores OAuth tokens and device-flow state (see `env-paths` + `neta-cli`). |
 | `DISABLE_TELEMETRY` | ❌ | unset | Set to `1` to disable CLI usage analytics (see below). |
 
+\* If you have completed `login` / `verify-code` successfully on the global API, the CLI can run without `NETA_TOKEN` until you `logout` or the refresh session is cleared.
+
 ### CLI usage analytics (telemetry)
 
 The `@talesofai/neta-skills` CLI sends lightweight usage data—such as which command ran, the options you passed, CLI version and locale, a coarse API-region hint, outcomes and timing, and your user UUID when signed in (not your API token)—so we can measure reliability and improve the experience.

package/README.zh_cn.md

@@ -1,7 +1,7 @@
 # NETA Skills
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node](https://img.shields.io/badge/Node-%3E%3D20-green)](https://nodejs.org/)
+[![Node](https://img.shields.io/badge/Node-%3E%3D22-green)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
 
 [简体中文](./README.md) · [English](./README.en.md)
@@ -18,8 +18,7 @@
 - 通过推荐引擎和互动 Feed 进行玩法内容发现
 - 创作与游玩 AI 驱动的交互式故事冒险（奇遇剧本），Agent 担任 DM 与角色扮演者
 
-你可以在 [Neta 开放平台](https://www.neta.art/open/) 获取访问令牌 `NETA_TOKEN`。
-也可以在[国内登陆账号后台](https://app.nieta.art/security) 获取访问令牌 `NETA_TOKEN`。
+你可以在 [Neta 开放平台](https://www.neta.art/open/) 或[国内账号后台](https://app.nieta.art/security) 获取访问令牌 `NETA_TOKEN`。在**全球** API 环境下，也可使用 CLI 的 `login`（OAuth 设备流）登录，详见下文「身份验证」小节。
 
 ---
 
@@ -31,6 +30,7 @@
 - 🏷️ **社区与标签集成**：浏览热门标签、空间、玩法合集与角色。
 - 🧭 **智能内容探索**：通过关键词建议、标签推荐、分类导航与智能内容流，渐进式发现玩法与内容。
 - 🤖 **Agent 优先设计**：面向 AI Agent 场景设计，易于在各类 Agent 框架中集成调用。
+- 🔐 **CLI 登录（可选）**：在**全球** API 环境（`api.talesofai.com`）下，可通过 `login` 使用 OAuth **设备授权**登录，无需在每台环境手动配置 `NETA_TOKEN`。
 
 ---
 
@@ -69,10 +69,12 @@ npx skills add talesofai/neta-skills/skills/zh_cn/neta-adventure
 
 ### 可用指令总览
 
-当前技能共包含 **34 个命令**，覆盖创作、奇遇、角色与社区探索等场景：
+当前技能共包含 **36 个命令**，覆盖创作、奇遇、角色与社区探索等场景：
 
 | 分类 | 命令 | 说明 |
 |------|------|------|
+| **用户 User** | `login` | OAuth 设备流：默认 `request-code` 发起登录；浏览器完成后用 `verify-code` 换票并写入本地会话 |
+| | `logout` | 清除本地保存的访问令牌及未完成的设备授权状态 |
 | **奇遇剧本 Adventure** | `create_adventure_campaign` | 创建 AI 驱动的交互式故事冒险剧本 |
 | | `update_adventure_campaign` | 更新已有奇遇剧本 |
 | | `list_my_adventure_campaigns` | 列出你创建的奇遇剧本 |
@@ -136,6 +138,30 @@ pnpm dlx @talesofai/neta-skills --help
 export NETA_TOKEN=your_token_here
 ```
 
+### 身份验证（`NETA_TOKEN` 与 `login`）
+
+任选其一即可：
+
+1. **环境变量令牌（通用）**  
+   在 [Neta 开放平台](https://www.neta.art/open/) 或国内后台获取 `NETA_TOKEN`。未建立 CLI 会话时，客户端会将其作为 `x-token` 发送。
+
+2. **CLI 设备授权登录（仅全球 API）**  
+   当 `NETA_API_BASE_URL` 为全球域名（`…talesofai.com`）时，可执行：
+
+   ```bash
+   npx -y @talesofai/neta-skills@latest login
+   ```
+
+   命令会返回 OAuth 设备授权字段。请让用户在浏览器中打开 **`verification_uri_complete`** 完成登录与授权，完成后执行：
+
+   ```bash
+   npx -y @talesofai/neta-skills@latest login --action verify-code
+   ```
+
+   成功后令牌保存在本机配置目录（见下文 `NETA_CONFIG_DIR`）。之后在会话有效期内，请求会携带 `Authorization: Bearer …`，直至执行 `logout` 或刷新失效。
+
+若 CLI 提示**当前区域不支持**设备登录（非全球 API），请改用 `NETA_TOKEN`。
+
 ### 运行示例
 
 ```bash
@@ -181,7 +207,7 @@ neta-skills/
 │       └── neta-adventure/
 ├── src/                            # CLI 对应的 TypeScript 源码
 │   ├── apis/                       # 封装后的 Neta API 调用
-│   ├── commands/                   # CLI 命令定义（TS + YAML 描述）
+│   ├── commands/                   # CLI 命令定义（含 user / creative / community 等）
 │   ├── utils/                      # 通用工具方法
 │   └── cli.ts                      # CLI 入口（TypeScript）
 ├── bin/                            # 构建后的 JavaScript 产物
@@ -220,10 +246,15 @@ neta-skills/
 
 | 变量名 | 必需 | 默认值 | 说明 |
 |--------|------|--------|------|
-| `NETA_TOKEN` | ✅ | - | Neta Art API 访问令牌 |
-| `NETA_API_BASE_URL` | ❌ | default: `https://api.talesofai.com` | Neta API 网关地址 |
+| `NETA_TOKEN` | 视情况* | - | 从开放平台或国内后台获取的 API 令牌；未使用 `login` 会话时必填 |
+| `NETA_API_BASE_URL` | ❌ | `https://api.talesofai.com` | Neta API 网关；设备登录仅在指向**全球**域名（`…talesofai.com`）时可用 |
+| `NETA_AUTH_API_BASE_URL` | ❌ | 由 `NETA_API_BASE_URL` 推导 | OIDC / 换票端点；自建环境可显式覆盖 |
+| `NETA_CLIENT_ID` | ❌ | 内置公共客户端 ID | 设备流与刷新令牌使用的 OAuth `client_id` |
+| `NETA_CONFIG_DIR` | ❌ | 系统配置目录 | CLI 存放 OAuth 令牌与设备流状态的目录（`env-paths` + `neta-cli`） |
 | `DISABLE_TELEMETRY` | ❌ | 未设置 | 设为 `1` 可关闭 CLI 使用数据统计（见下文） |
 
+\* 若你已在**全球** API 上成功执行 `login` / `verify-code`，在会话有效期间可不设 `NETA_TOKEN`，直至 `logout` 或刷新会话失效。
+
 ### CLI 使用数据（埋点 / 遥测）
 
 `@talesofai/neta-skills` CLI 会上报轻量使用数据（例如执行的命令、命令行参数、CLI 版本与语言、大致 API 区域、执行结果与耗时、登录时的用户 UUID 等；**不包含** API Token），用于衡量稳定性并改进产品体验。

package/bin/apis/index.js

@@ -1,4 +1,6 @@
 import axios, { AxiosError } from "axios";
+import { isTokenExpired, readToken, refreshToken } from "../utils/auth.js";
+import { NETA_TOKEN } from "../utils/env.js";
 import { catchErrorResponse, handleAxiosError } from "../utils/errors.js";
 import { createActivityApis } from "./activity.js";
 import { createArtifactApis } from "./artifact.js";
@@ -29,10 +31,23 @@ export const createApis = (option) => {
         },
         timeout: 10 * 1000,
     });
-    client.interceptors.request.use((config) => {
+    client.interceptors.request.use(async (config) => {
         const now = Date.now();
         config.start_time = now;
         logger.debug("[api] request: %s %s", config.method, config.url);
+        let token = await readToken();
+        if (token && isTokenExpired(token)) {
+            token = await refreshToken().catch((e) => {
+                logger.warn("[api] refresh token error: %o", e);
+                return null;
+            });
+        }
+        if (!token) {
+            config.headers.set("x-token", NETA_TOKEN);
+        }
+        else {
+            config.headers.set("Authorization", `Bearer ${token.access_token}`);
+        }
         return config;
     });
     client.interceptors.response.use((response) => {

package/bin/cli.js

@@ -1,16 +1,12 @@
 #!/usr/bin/env node
 import { program } from "@commander-js/extra-typings";
-import dotenv from "dotenv-flow";
 import pkg from "../package.json" with { type: "json" };
 import { buildCommands } from "./commands/load.js";
-// Load environment variables
-dotenv.config({
-    silent: true,
-});
+import { setupEnvPaths } from "./utils/config.js";
+setupEnvPaths();
 program
     .name("neta")
     .description("NETA CLI - Neta API Client")
     .version(pkg.version);
-const cli = program.option("--api_base_url <string>", "api base url (default: NETA_API_BASE_URL or locale-based default)");
-await buildCommands(cli);
-cli.parse(process.argv);
+await buildCommands(program);
+program.parse(process.argv);

package/bin/commands/adventure_campaign/create_adventure_campaign.cmd.js

@@ -41,7 +41,7 @@ export const createAdventureCampaign = createCommand({
     inputSchema: createAdventureCampaignParameters,
 }, async ({ name, mission_plot, subtitle, status, header_img, background_img, mission_task, mission_plot_attention, }, { user, apis }) => {
     if (!user) {
-        throw new Error("Not authenticated. Please check your NETA_TOKEN.");
+        throw new Error("Not authenticated. Please check your NETA_TOKEN or login.");
     }
     const result = await apis.travelCampaign.createCampaign({
         name,

package/bin/commands/adventure_campaign/list_my_adventure_campaigns.cmd.js

@@ -30,7 +30,7 @@ export const listMyAdventureCampaigns = createCommand({
     inputSchema: listMyAdventureCampaignsParameters,
 }, async ({ page_index, page_size }, { user, apis }) => {
     if (!user) {
-        throw new Error("Not authenticated. Please check your NETA_TOKEN.");
+        throw new Error("Not authenticated. Please check your NETA_TOKEN or login.");
     }
     const result = await apis.travelCampaign.listMyCampaigns({
         user_uuid: user.uuid,

package/bin/commands/adventure_campaign/update_adventure_campaign.cmd.js

@@ -42,7 +42,7 @@ export const updateAdventureCampaign = createCommand({
     inputSchema: updateAdventureCampaignParameters,
 }, async ({ campaign_uuid, name, mission_plot, subtitle, status, header_img, background_img, mission_task, mission_plot_attention, }, { user, apis }) => {
     if (!user) {
-        throw new Error("Not authenticated. Please check your NETA_TOKEN.");
+        throw new Error("Not authenticated. Please check your NETA_TOKEN or login.");
     }
     const patch = Object.fromEntries(Object.entries({
         name,

package/bin/commands/creative/upload.cmd.js

@@ -146,7 +146,7 @@ export const upload = createCommand({
     }),
 }, async ({ file_path }, { apis, user, log }) => {
     if (!user) {
-        throw new Error("Not authenticated. Please check your NETA_TOKEN.");
+        throw new Error("Not authenticated. Please check your NETA_TOKEN or login.");
     }
     const regionOptions = apis.baseUrl.endsWith(".cn")
         ? OSS_STS_OPTIONS_CN

package/bin/commands/load.js

@@ -13,8 +13,10 @@ import { Option, } from "@commander-js/extra-typings";
 import { Type } from "@sinclair/typebox";
 import { AssertError, Value } from "@sinclair/typebox/value";
 import { createApis } from "../apis/index.js";
+import { API_BASE_URL, IS_DEV } from "../utils/env.js";
 import { ApiResponseError } from "../utils/errors.js";
-import { getLocale } from "../utils/lang.js";
+import { getSysLocale } from "../utils/lang.js";
+import { logger } from "../utils/logger.js";
 import { setLocale } from "../utils/parse_meta.js";
 import { formatCommandParams, track, trackConfig, trackConfigUser, } from "../utils/telemetry.js";
 import { isCommand } from "./factory.js";
@@ -38,18 +40,6 @@ export const loadCommands = async (domains) => {
             .map((name) => module[name]);
     })).then((commands) => commands.flat());
 };
-const IS_DEV = process.env["NODE_ENV"] === "development";
-const logger = IS_DEV
-    ? console
-    : {
-        // biome-ignore lint/suspicious/noConsole: use console
-        error: console.error,
-        // biome-ignore lint/suspicious/noConsole: use console
-        warn: console.warn,
-        // biome-ignore lint/suspicious/noConsole: use console
-        info: console.info,
-        debug: () => { },
-    };
 export const buildCommands = async (cli) => {
     setLocale();
     const commands = await loadCommands([
@@ -58,15 +48,16 @@ export const buildCommands = async (cli) => {
         "character_elementum",
         "adventure_campaign",
         "premium",
+        "user",
     ]);
-    return commands.map((cmd) => {
+    commands.forEach((cmd) => {
         const command = cli.command(cmd.name);
         command.description(cmd.title || cmd.description || "");
         const inputSchema = cmd.inputSchema;
         if (inputSchema && "properties" in inputSchema) {
             const properties = inputSchema.properties;
             if (!properties)
-                return command;
+                return;
             Object.entries(properties).forEach(([key, property]) => {
                 if (typeof property !== "object")
                     return;
@@ -97,28 +88,25 @@ export const buildCommands = async (cli) => {
             });
         }
         command.action(async (args) => {
-            const { api_base_url } = cli.opts();
-            const baseUrl = typeof api_base_url === "string"
-                ? api_base_url
-                : (process.env["NETA_API_BASE_URL"] ?? "https://api.talesofai.com");
             trackConfig({
-                app_region: baseUrl.endsWith("cn") ? "cn" : "global",
-                app_language: getLocale(),
+                app_region: API_BASE_URL.endsWith("cn") ? "cn" : "global",
+                app_language: getSysLocale(),
             });
             const apis = createApis({
                 logger,
-                baseUrl,
+                baseUrl: API_BASE_URL,
                 headers: {
-                    "x-token": process.env["NETA_TOKEN"] ?? "",
                     "x-platform": "nieta-app/web",
                 },
             });
-            const user = await apis.user.me().catch((e) => {
-                if (e instanceof ApiResponseError) {
+            const user = cmd.name === "login" || cmd.name === "logout"
+                ? null
+                : await apis.user.me().catch((e) => {
+                    if (e instanceof ApiResponseError) {
+                        return null;
+                    }
                     return null;
-                }
-                return null;
-            });
+                });
             const startTime = Date.now();
             logger.debug("[telemetry] user: %s", user?.uuid);
             trackConfigUser(user ? { user_unique_id: user.uuid } : null);
@@ -128,9 +116,7 @@ export const buildCommands = async (cli) => {
             });
             const type = cmd.inputSchema ?? Type.Object({});
             const input = Value.Parse(type, args);
-            if (IS_DEV) {
-                logger.debug("[command] %s, params: %o", cmd.name, input);
-            }
+            logger.debug("[command] %s, params: %o", cmd.name, input);
             await cmd
                 .execute(input, {
                 apis,
@@ -166,7 +152,7 @@ export const buildCommands = async (cli) => {
                             type: e.name,
                             message: e.message,
                             path: e.error?.path,
-                            schema: e.error?.schema,
+                            schema: JSON.stringify(e.error?.schema),
                         },
                     });
                     return null;
@@ -213,6 +199,5 @@ export const buildCommands = async (cli) => {
                 return null;
             });
         });
-        return command;
     });
 };

package/bin/commands/premium/create_premium_order.cmd.js

@@ -1,5 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import { parseDate } from "../../utils/date.js";
+import { IS_GLOBAL } from "../../utils/env.js";
 import { parseMeta } from "../../utils/parse_meta.js";
 import { createCommand } from "../factory.js";
 const meta = parseMeta(Type.Object({
@@ -18,7 +19,7 @@ export const createPremiumOrder = createCommand({
         spu_uuid: Type.String({ description: meta.parameters.spu_uuid }),
     }),
 }, async ({ spu_uuid }, { apis }) => {
-    if (!apis.baseUrl.endsWith("talesofai.com")) {
+    if (!IS_GLOBAL) {
         throw new Error("This command is not supported in the current region");
     }
     const order = await apis.commerce.createOrder({

package/bin/commands/premium/get_current_premium_plan.cmd.js

@@ -1,5 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import { parseDate } from "../../utils/date.js";
+import { IS_GLOBAL } from "../../utils/env.js";
 import { parseMeta } from "../../utils/parse_meta.js";
 import { createCommand } from "../factory.js";
 const PlanningMap = {
@@ -17,12 +18,12 @@ export const getCurrentPremiumPlan = createCommand({
     name: meta.name,
     title: meta.title,
     description: meta.description,
-}, async (_, { apis, user }) => {
-    if (!apis.baseUrl.endsWith("talesofai.com")) {
+}, async (_, { user }) => {
+    if (!IS_GLOBAL) {
         throw new Error("This command is not supported in the current region");
     }
     if (!user) {
-        throw new Error("Not authenticated. Please check your NETA_TOKEN.");
+        throw new Error("Not authenticated. Please check your NETA_TOKEN or login.");
     }
     const level = user.properties?.vip_level ?? 0;
     return {

package/bin/commands/premium/get_premium_order.cmd.js

@@ -1,5 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import { parseDate } from "../../utils/date.js";
+import { IS_GLOBAL } from "../../utils/env.js";
 import { parseMeta } from "../../utils/parse_meta.js";
 import { createCommand } from "../factory.js";
 const meta = parseMeta(Type.Object({
@@ -18,7 +19,7 @@ export const getPremiumOrder = createCommand({
         order_uuid: Type.String({ description: meta.parameters.order_uuid }),
     }),
 }, async ({ order_uuid }, { apis }) => {
-    if (!apis.baseUrl.endsWith("talesofai.com")) {
+    if (!IS_GLOBAL) {
         throw new Error("This command is not supported in the current region");
     }
     const order = await apis.commerce.order({ order_uuid });

package/bin/commands/premium/list_premium_orders.cmd.js

@@ -1,5 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import { parseDate } from "../../utils/date.js";
+import { IS_GLOBAL } from "../../utils/env.js";
 import { parseMeta } from "../../utils/parse_meta.js";
 import { createCommand } from "../factory.js";
 const meta = parseMeta(Type.Object({
@@ -29,7 +30,7 @@ export const listPremiumOrders = createCommand({
         }),
     }),
 }, async ({ page_index, page_size }, { apis }) => {
-    if (!apis.baseUrl.endsWith("talesofai.com")) {
+    if (!IS_GLOBAL) {
         throw new Error("This command is not supported in the current region");
     }
     const { list, total } = await apis.commerce.orders({

package/bin/commands/premium/list_premium_plans.cmd.js

@@ -1,5 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import { Value } from "@sinclair/typebox/value";
+import { IS_GLOBAL } from "../../utils/env.js";
 import { safeParseJson } from "../../utils/json.js";
 import { parseMeta } from "../../utils/parse_meta.js";
 import { createCommand } from "../factory.js";
@@ -44,7 +45,7 @@ export const listPremiumPlans = createCommand({
     title: meta.title,
     description: meta.description,
 }, async (_, { apis }) => {
-    if (!apis.baseUrl.endsWith("talesofai.com")) {
+    if (!IS_GLOBAL) {
         throw new Error("This command is not supported in the current region");
     }
     const plansConfigValue = await apis.commerce.listPlansConfig();

package/bin/commands/premium/pay_premium_order.cmd.js

@@ -1,5 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import { parseDate } from "../../utils/date.js";
+import { IS_GLOBAL } from "../../utils/env.js";
 import { parseMeta } from "../../utils/parse_meta.js";
 import { createCommand } from "../factory.js";
 const meta = parseMeta(Type.Object({
@@ -22,7 +23,7 @@ export const payPremiumOrder = createCommand({
         }),
     }),
 }, async ({ order_uuid, channel }, { apis }) => {
-    if (!apis.baseUrl.endsWith("talesofai.com")) {
+    if (!IS_GLOBAL) {
         throw new Error("This command is not supported in the current region");
     }
     const order = await apis.commerce.order({ order_uuid });

package/bin/commands/user/login.cmd.en_us.yml

@@ -0,0 +1,8 @@
+name: login
+title: Login
+description: Login to your Neta account
+parameters:
+  action: Action to perform (request-code or verify-code)
+
+errors:
+  not_supported_in_current_region: This command is not supported in the current region, please set NETA_TOKEN environment variable for authentication.

package/bin/commands/user/login.cmd.js

@@ -0,0 +1,41 @@
+import { Type } from "@sinclair/typebox";
+import { requestDeviceCode, verifyDeviceCode } from "../../utils/auth.js";
+import { IS_GLOBAL } from "../../utils/env.js";
+import { parseMeta } from "../../utils/parse_meta.js";
+import { createCommand } from "../factory.js";
+export const meta = parseMeta(Type.Object({
+    name: Type.String(),
+    title: Type.String(),
+    description: Type.String(),
+    parameters: Type.Object({
+        action: Type.String(),
+    }),
+    errors: Type.Object({
+        not_supported_in_current_region: Type.String(),
+    }),
+}), import.meta);
+export const login = createCommand({
+    name: meta.name,
+    title: meta.title,
+    description: meta.description,
+    inputSchema: Type.Object({
+        action: Type.Union([Type.Literal("request-code"), Type.Literal("verify-code")], {
+            default: "request-code",
+            description: meta.parameters.action,
+        }),
+    }),
+}, async ({ action }, { apis }) => {
+    if (!IS_GLOBAL) {
+        throw new Error(meta.errors.not_supported_in_current_region);
+    }
+    if (action === "verify-code") {
+        await verifyDeviceCode();
+        const user = await apis.user.me();
+        return {
+            uuid: user.uuid,
+            nick_name: user.nick_name,
+            avatar_url: user.avatar_url,
+        };
+    }
+    return requestDeviceCode();
+});

package/bin/commands/user/login.cmd.zh_cn.yml

@@ -0,0 +1,8 @@
+name: login
+title: 登录
+description: 登录到你的 Neta 账户
+parameters:
+  action: 要执行的操作 (request-code 请求验证码, verify-code 验证验证码)
+
+errors:
+  not_supported_in_current_region: 当前区域不支持此命令, 请设置 NETA_TOKEN 环境变量进行身份验证

package/bin/commands/user/logout.cmd.en_us.yml

@@ -0,0 +1,5 @@
+name: logout
+title: Logout
+description: Logout from your Neta account
+
+success: Logout success

package/bin/commands/user/logout.cmd.js

@@ -0,0 +1,19 @@
+import { Type } from "@sinclair/typebox";
+import { deleteDeviceCode, deleteToken } from "../../utils/auth.js";
+import { parseMeta } from "../../utils/parse_meta.js";
+import { createCommand } from "../factory.js";
+const meta = parseMeta(Type.Object({
+    name: Type.String(),
+    title: Type.String(),
+    description: Type.String(),
+    success: Type.String(),
+}), import.meta);
+export const logout = createCommand({
+    name: meta.name,
+    title: meta.title,
+    description: meta.description,
+}, async (_, { log }) => {
+    await deleteToken();
+    await deleteDeviceCode();
+    log.info(meta.success);
+});

package/bin/commands/user/logout.cmd.zh_cn.yml

@@ -0,0 +1,5 @@
+name: logout
+title: 退出登录
+description: 退出登录你的 Neta 账户
+
+success: 退出登录成功

package/bin/utils/auth.js

@@ -0,0 +1,192 @@
+import { Type } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import { deleteConfig, readConfig, writeConfig } from "./config.js";
+import { API_BASE_URL, AUTH_API_BASE_URL, CLIENT_ID } from "./env.js";
+import { ApiResponseError } from "./errors.js";
+import { safeParseJson } from "./json.js";
+import { logger } from "./logger.js";
+const DeviceCodeResponse = Type.Object({
+    device_code: Type.String(),
+    user_code: Type.String(),
+    verification_uri: Type.String(),
+    verification_uri_complete: Type.String(),
+    expires_in: Type.Number(),
+    created_at: Type.Number(),
+});
+const TokenResponse = Type.Object({
+    access_token: Type.String(),
+    id_token: Type.Optional(Type.String()),
+    refresh_token: Type.Optional(Type.String()),
+    token_type: Type.Literal("Bearer"),
+    expires_in: Type.Number(),
+    scope: Type.String(),
+    created_at: Type.Number(),
+});
+export const storeDeviceCode = (deviceCode) => {
+    return writeConfig("device_code", JSON.stringify(deviceCode));
+};
+export const readDeviceCode = async () => {
+    const config = await readConfig("device_code");
+    if (!config)
+        return null;
+    const json = safeParseJson(config);
+    if (!json)
+        return null;
+    try {
+        return Value.Parse(DeviceCodeResponse, json);
+    }
+    catch (e) {
+        logger.warn("[auth] read device code: invalid device code, error: %o", e);
+        return null;
+    }
+};
+export const deleteDeviceCode = async () => {
+    return deleteConfig("device_code");
+};
+export const storeToken = (token) => {
+    return writeConfig("token", JSON.stringify(token));
+};
+export const readToken = async () => {
+    const config = await readConfig("token");
+    if (!config)
+        return null;
+    const json = safeParseJson(config);
+    if (!json)
+        return null;
+    try {
+        return Value.Parse(TokenResponse, json);
+    }
+    catch (e) {
+        logger.warn("[auth] read token: invalid token, error: %o", e);
+        return null;
+    }
+};
+export const deleteToken = async () => {
+    return deleteConfig("token");
+};
+export const isDeviceCodeExpired = (deviceCode) => {
+    return deviceCode.created_at + deviceCode.expires_in * 1000 < Date.now();
+};
+export const isTokenExpired = (token) => {
+    return token.created_at + token.expires_in * 1000 < Date.now();
+};
+export const verifyDeviceCode = async () => {
+    logger.debug("[auth] verify device code");
+    const config = await readConfig("device_code");
+    if (!config) {
+        throw new Error("Device code is not found, please request login again");
+    }
+    const deviceCodeConfig = Value.Parse(DeviceCodeResponse, safeParseJson(config));
+    if (isDeviceCodeExpired(deviceCodeConfig)) {
+        throw new Error("Device code is expired, please request login again");
+    }
+    const res = await fetch(`${AUTH_API_BASE_URL}/oidc/token`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: new URLSearchParams({
+            client_id: CLIENT_ID,
+            grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+            device_code: deviceCodeConfig.device_code,
+        }),
+    });
+    if (!res.ok) {
+        throw new ApiResponseError(res.status, await res.text());
+    }
+    const data = await res.json();
+    if (typeof data !== "object") {
+        throw new Error("Invalid response", { cause: data });
+    }
+    const token = Value.Parse(TokenResponse, {
+        ...data,
+        created_at: Date.now(),
+    });
+    if (await storeToken(token)) {
+        logger.debug("[auth] verify device code success");
+        await deleteDeviceCode();
+    }
+    else {
+        throw new Error("Failed to store token, please try again");
+    }
+    return token;
+};
+export const requestDeviceCode = async () => {
+    logger.debug("[auth] request device code");
+    const res = await fetch(`${AUTH_API_BASE_URL}/oidc/device/auth`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: new URLSearchParams({
+            client_id: CLIENT_ID,
+            scope: "profile email offline_access",
+            resource: API_BASE_URL,
+        }),
+    });
+    if (!res.ok) {
+        throw new ApiResponseError(res.status, await res.text());
+    }
+    const data = await res.json();
+    if (typeof data !== "object") {
+        throw new Error("Invalid response", { cause: data });
+    }
+    const deviceCode = Value.Parse(DeviceCodeResponse, {
+        ...data,
+        created_at: Date.now(),
+    });
+    if (await storeDeviceCode(deviceCode)) {
+        logger.debug("[auth] request device code success");
+    }
+    else {
+        throw new Error("Failed to store device code, please try again");
+    }
+    return deviceCode;
+};
+const REFRESH_TOKEN_EXPIRES_IN = 3600 * 24 * 90; // 90 days in seconds
+export const refreshToken = async () => {
+    logger.debug("[auth] refresh token");
+    const config = await readConfig("token");
+    if (!config) {
+        throw new Error("Token is not found, please login again");
+    }
+    const tokenConfig = Value.Parse(TokenResponse, safeParseJson(config));
+    if (!tokenConfig.refresh_token) {
+        throw new Error("Refresh token is not found, please login again");
+    }
+    if (tokenConfig.created_at + REFRESH_TOKEN_EXPIRES_IN * 1000 < Date.now()) {
+        await deleteToken();
+        throw new Error("Refresh token is expired, please login again");
+    }
+    const res = await fetch(`${AUTH_API_BASE_URL}/oidc/token`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: new URLSearchParams({
+            client_id: CLIENT_ID,
+            grant_type: "refresh_token",
+            refresh_token: tokenConfig.refresh_token,
+            scope: "profile email offline_access",
+            resource: API_BASE_URL,
+        }),
+    });
+    if (!res.ok) {
+        throw new ApiResponseError(res.status, await res.text());
+    }
+    const data = await res.json();
+    if (typeof data !== "object") {
+        throw new Error("Invalid response", { cause: data });
+    }
+    const token = Value.Parse(TokenResponse, {
+        ...data,
+        created_at: Date.now(),
+    });
+    if (await storeToken(token)) {
+        logger.debug("[auth] refresh token success");
+        return token;
+    }
+    else {
+        throw new Error("Failed to store token, please try again");
+    }
+};

package/bin/utils/config.js

@@ -0,0 +1,60 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { readFile, unlink, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import envPaths from "env-paths";
+import { IS_DEV } from "./env.js";
+import { logger } from "./logger.js";
+const paths = envPaths("neta-cli", {
+    suffix: IS_DEV ? "dev" : "",
+});
+const CONFIG_DIR = process.env["NETA_CONFIG_DIR"] ?? paths.config;
+export const setupEnvPaths = () => {
+    try {
+        if (!existsSync(CONFIG_DIR)) {
+            mkdirSync(CONFIG_DIR, { recursive: true });
+        }
+    }
+    catch (error) {
+        logger.error("Failed to setup env paths, try to set NETA_CONFIG_DIR manually, error: %o", error);
+    }
+};
+export const readConfig = async (name) => {
+    try {
+        const filePath = resolve(CONFIG_DIR, name);
+        if (!existsSync(filePath))
+            return null;
+        const data = await readFile(filePath, "utf-8");
+        if (!data)
+            return null;
+        return Buffer.from(data, "base64").toString("utf-8");
+    }
+    catch (e) {
+        logger.warn("Failed to read config: %s, error: %o", name, e);
+        return null;
+    }
+};
+export const writeConfig = async (name, value) => {
+    try {
+        const filePath = resolve(CONFIG_DIR, name);
+        const encoded = Buffer.from(value, "utf-8").toString("base64");
+        await writeFile(filePath, encoded, "utf-8");
+        return true;
+    }
+    catch (e) {
+        logger.warn("Failed to write config: %s, error: %o", name, e);
+        return false;
+    }
+};
+export const deleteConfig = async (name) => {
+    try {
+        const filePath = resolve(CONFIG_DIR, name);
+        if (!existsSync(filePath))
+            return true;
+        await unlink(filePath);
+        return true;
+    }
+    catch (e) {
+        logger.warn("Failed to delete config: %s, error: %o", name, e);
+        return false;
+    }
+};

package/bin/utils/env.js

@@ -0,0 +1,11 @@
+import dotenv from "dotenv-flow";
+// Load environment variables
+dotenv.config({
+    silent: true,
+});
+export const IS_DEV = process.env["NODE_ENV"] === "development";
+export const API_BASE_URL = process.env["NETA_API_BASE_URL"] ?? "https://api.talesofai.com";
+export const AUTH_API_BASE_URL = process.env["NETA_AUTH_API_BASE_URL"] ?? "https://auth.talesofai.com";
+export const CLIENT_ID = process.env["NETA_CLIENT_ID"] ?? "ft6zb5zp7fqmq8y807okv";
+export const NETA_TOKEN = process.env["NETA_TOKEN"] ?? "";
+export const IS_GLOBAL = API_BASE_URL.endsWith("talesofai.com");

package/bin/utils/errors.js

@@ -34,6 +34,9 @@ export const catchErrorResponse = (data) => {
     return message;
 };
 export const handleAxiosError = (error) => {
+    if (error instanceof ApiResponseError) {
+        throw error;
+    }
     if (error instanceof AxiosError) {
         if (error.response?.status) {
             let message = error.message;

package/bin/utils/lang.js

@@ -1,5 +1,5 @@
 import osLocale from "os-locale";
-export const getLocale = () => {
+export const getSysLocale = () => {
     const locale = osLocale();
     if (locale.startsWith("zh")) {
         return "zh_cn";

package/bin/utils/logger.js

@@ -0,0 +1,10 @@
+/** biome-ignore-all lint/suspicious/noConsole: use console */
+import { IS_DEV } from "./env.js";
+export const logger = IS_DEV
+    ? console
+    : {
+        error: console.error,
+        warn: console.warn,
+        info: console.info,
+        debug: () => { },
+    };

package/bin/utils/parse_meta.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { Value } from "@sinclair/typebox/value";
 import yaml from "yaml";
-import { getLocale as getLocaleFromLang } from "./lang.js";
+import { getSysLocale as getLocaleFromLang } from "./lang.js";
 let _locale = "en_us";
 export const setLocale = (locale) => {
     _locale = locale ?? getLocaleFromLang();

package/bin/utils/telemetry.js

@@ -1,7 +1,8 @@
 import axios from "axios";
 import pkg from "../../package.json" with { type: "json" };
+import { IS_DEV } from "./env.js";
+import { logger } from "./logger.js";
 const DISABLE_TELEMETRY = process.env["DISABLE_TELEMETRY"] === "1";
-const IS_DEV = process.env["NODE_ENV"] === "development";
 const api = axios.create({
     baseURL: "https://gator.volces.com/v2/event/json",
     headers: {
@@ -24,10 +25,11 @@ export const trackConfig = (config) => {
         ...config,
     };
 };
-const logger = console;
 export const track = (event, params) => {
     if (DISABLE_TELEMETRY)
         return;
+    if (!_user)
+        return;
     api
         .post("/", {
         user: _user,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talesofai/neta-skills",
-  "version": "0.15.3",
+  "version": "0.16.2",
   "description": "Neta API pi coding agent skills for interacting with Neta API to generate images, videos, songs, and manage characters/elements.",
   "type": "module",
   "repository": {
@@ -51,6 +51,7 @@
     "dayjs": "^1.11.20",
     "dotenv": "^16.4.7",
     "dotenv-flow": "^4.1.0",
+    "env-paths": "^4.0.0",
     "magic-bytes.js": "^1.13.0",
     "os-locale": "^8.0.0",
     "p-limit": "^7.3.0",

package/skills/neta/SKILL.md

@@ -49,6 +49,25 @@ npx skills add talesofai/neta-skills/skills/neta-adventure
    - Creating or managing visual style elements (scenes, props, clothing, poses, atmospheres, memes) → use `neta-elementum`
 3. Use this skill only when boundaries are unclear or when you need to explain which sub-skill to pick.
 
+## Authorization
+
+Use this when the user needs a **logged-in Neta identity** for CLI-backed flows and no valid session exists (or you would otherwise rely on `NETA_TOKEN`).
+
+1. **Start the flow**: run **`neta login`** (default action is `request-code`). 
+```bash
+npx -y @talesofai/neta-skills@latest login --action request-code
+```
+This begins the OAuth **device authorization** flow stored by the CLI.
+
+2. **Browser step**: When the command returns device-authorization fields, show the user **`verification_uri_complete`** (the ready-to-open URL), tell them to open it in a browser and finish sign-in/consent there, then **return to the chat and explicitly say the browser step is done** so you know when to continue.
+
+3. **Complete login**: After they confirm in chat, run **`neta login --action verify-code`** to exchange the device code for tokens. On success, show the returned **account basics**: **`uuid`** (long user id), **`nick_name`**, and **`avatar_url`**.
+```bash
+npx -y @talesofai/neta-skills@latest login --action verify-code
+```
+
+**Region / fallback**: Device login is only supported when the CLI is using the **global** API host (see `NETA_API_BASE_URL` / `talesofai.com`). If the command errors with “not supported in the current region”, tell the user to authenticate via the **`NETA_TOKEN`** environment variable instead.
+
 ## Capability map and sub-skill overview
 
 ### 1. Spaces and worldbuilding: `neta-space`

package/skills/neta-adventure/SKILL.md

@@ -20,6 +20,23 @@ Determine mode before acting. Do not ask multiple questions.
 
 Once mode is established, do not re-ask.
 
+## Authorization
+
+Use this when the user needs a **logged-in Neta identity** for CLI-backed flows and no valid session exists (or you would otherwise rely on `NETA_TOKEN`).
+
+1. **Start the flow**: run **`neta login`** (default action is `request-code`). 
+```bash
+npx -y @talesofai/neta-skills@latest login --action request-code
+```
+This begins the OAuth **device authorization** flow stored by the CLI.
+
+2. **Browser step**: When the command returns device-authorization fields, show the user **`verification_uri_complete`** (the ready-to-open URL), tell them to open it in a browser and finish sign-in/consent there, then **return to the chat and explicitly say the browser step is done** so you know when to continue.
+
+3. **Complete login**: After they confirm in chat, run **`neta login --action verify-code`** to exchange the device code for tokens. On success, show the returned **account basics**: **`uuid`** (long user id), **`nick_name`**, and **`avatar_url`**.
+```bash
+npx -y @talesofai/neta-skills@latest login --action verify-code
+```
+
 ## Commands
 
 **Create a campaign**

package/skills/neta-character/SKILL.md

@@ -9,6 +9,23 @@ Guide users from inspiration to forging, completing the creation and management
 
 > This skill requires the **neta-creative** skill to use `make_image` for visual previews.
 
+## Authorization
+
+Use this when the user needs a **logged-in Neta identity** for CLI-backed flows and no valid session exists (or you would otherwise rely on `NETA_TOKEN`).
+
+1. **Start the flow**: run **`neta login`** (default action is `request-code`). 
+```bash
+npx -y @talesofai/neta-skills@latest login --action request-code
+```
+This begins the OAuth **device authorization** flow stored by the CLI.
+
+2. **Browser step**: When the command returns device-authorization fields, show the user **`verification_uri_complete`** (the ready-to-open URL), tell them to open it in a browser and finish sign-in/consent there, then **return to the chat and explicitly say the browser step is done** so you know when to continue.
+
+3. **Complete login**: After they confirm in chat, run **`neta login --action verify-code`** to exchange the device code for tokens. On success, show the returned **account basics**: **`uuid`** (long user id), **`nick_name`**, and **`avatar_url`**.
+```bash
+npx -y @talesofai/neta-skills@latest login --action verify-code
+```
+
 ## Command Usage
 
 ### Create Character

package/skills/neta-community/SKILL.md

@@ -17,6 +17,23 @@ Used to interact with the Neta API for community feed browsing, interactions, an
 3. If the user needs **systematic research or complex filtering by categories/keywords**, switch to `neta-suggest`.
 4. If the user wants to **create new content** (images/videos/songs/MVs), switch to `neta-creative`.
 
+## Authorization
+
+Use this when the user needs a **logged-in Neta identity** for CLI-backed flows and no valid session exists (or you would otherwise rely on `NETA_TOKEN`).
+
+1. **Start the flow**: run **`neta login`** (default action is `request-code`). 
+```bash
+npx -y @talesofai/neta-skills@latest login --action request-code
+```
+This begins the OAuth **device authorization** flow stored by the CLI.
+
+2. **Browser step**: When the command returns device-authorization fields, show the user **`verification_uri_complete`** (the ready-to-open URL), tell them to open it in a browser and finish sign-in/consent there, then **return to the chat and explicitly say the browser step is done** so you know when to continue.
+
+3. **Complete login**: After they confirm in chat, run **`neta login --action verify-code`** to exchange the device code for tokens. On success, show the returned **account basics**: **`uuid`** (long user id), **`nick_name`**, and **`avatar_url`**.
+```bash
+npx -y @talesofai/neta-skills@latest login --action verify-code
+```
+
 ## Commands
 
 ### Collection

package/skills/neta-creative/SKILL.md

@@ -15,6 +15,23 @@ Used to interact with the Neta API for multimedia content creation, creation‑r
 2. If, during creation, you discover that the real need is more like “browse recommendations / casually explore / research topics”, combine this skill with `neta-community` or `neta-suggest` instead of overloading this skill.
 3. **Premium** (plans, orders, Stripe): use the commands below. Run **`get_current_premium_plan`** before and after checkout so the user can confirm tier (and end time if returned). Commerce needs the **global** Neta API—see the premium reference. If creation is blocked by **quota / credits (电量)** or **usage frequency (频率)**, say why in one beat; if an upgrade fits their goal, offer the path once (list plans → create order → pay)—**do not** repeat upgrade nudges in the same conversation unless the user asks.
 
+## Authorization
+
+Use this when the user needs a **logged-in Neta identity** for CLI-backed flows and no valid session exists (or you would otherwise rely on `NETA_TOKEN`).
+
+1. **Start the flow**: run **`neta login`** (default action is `request-code`). 
+```bash
+npx -y @talesofai/neta-skills@latest login --action request-code
+```
+This begins the OAuth **device authorization** flow stored by the CLI.
+
+2. **Browser step**: When the command returns device-authorization fields, show the user **`verification_uri_complete`** (the ready-to-open URL), tell them to open it in a browser and finish sign-in/consent there, then **return to the chat and explicitly say the browser step is done** so you know when to continue.
+
+3. **Complete login**: After they confirm in chat, run **`neta login --action verify-code`** to exchange the device code for tokens. On success, show the returned **account basics**: **`uuid`** (long user id), **`nick_name`**, and **`avatar_url`**.
+```bash
+npx -y @talesofai/neta-skills@latest login --action verify-code
+```
+
 ## Commands
 
 ### Content creation

package/skills/neta-elementum/SKILL.md

@@ -9,6 +9,23 @@ Through the "Elementum Alchemy" workflow, forge any visual concept into a reusab
 
 > This skill requires the **neta-creative** skill to use `make_image` for visual previews.
 
+## Authorization
+
+Use this when the user needs a **logged-in Neta identity** for CLI-backed flows and no valid session exists (or you would otherwise rely on `NETA_TOKEN`).
+
+1. **Start the flow**: run **`neta login`** (default action is `request-code`). 
+```bash
+npx -y @talesofai/neta-skills@latest login --action request-code
+```
+This begins the OAuth **device authorization** flow stored by the CLI.
+
+2. **Browser step**: When the command returns device-authorization fields, show the user **`verification_uri_complete`** (the ready-to-open URL), tell them to open it in a browser and finish sign-in/consent there, then **return to the chat and explicitly say the browser step is done** so you know when to continue.
+
+3. **Complete login**: After they confirm in chat, run **`neta login --action verify-code`** to exchange the device code for tokens. On success, show the returned **account basics**: **`uuid`** (long user id), **`nick_name`**, and **`avatar_url`**.
+```bash
+npx -y @talesofai/neta-skills@latest login --action verify-code
+```
+
 ## Command Usage
 
 ### Create Elementum

package/skills/neta-space/SKILL.md

@@ -17,6 +17,23 @@ Used to interact with the Neta API to browse space‑level content.
    - If needed, fetch characters and playable content inside the space.
 3. If the user says “now generate an image/video/song for this space”, first collect the relevant space/collection info here, then switch to `neta-creative` for creation.
 
+## Authorization
+
+Use this when the user needs a **logged-in Neta identity** for CLI-backed flows and no valid session exists (or you would otherwise rely on `NETA_TOKEN`).
+
+1. **Start the flow**: run **`neta login`** (default action is `request-code`). 
+```bash
+npx -y @talesofai/neta-skills@latest login --action request-code
+```
+This begins the OAuth **device authorization** flow stored by the CLI.
+
+2. **Browser step**: When the command returns device-authorization fields, show the user **`verification_uri_complete`** (the ready-to-open URL), tell them to open it in a browser and finish sign-in/consent there, then **return to the chat and explicitly say the browser step is done** so you know when to continue.
+
+3. **Complete login**: After they confirm in chat, run **`neta login --action verify-code`** to exchange the device code for tokens. On success, show the returned **account basics**: **`uuid`** (long user id), **`nick_name`**, and **`avatar_url`**.
+```bash
+npx -y @talesofai/neta-skills@latest login --action verify-code
+```
+
 ## Space concepts
 
 > A space is a themed collection of gameplay experiences — a scene where content is produced and consumed.

package/skills/neta-suggest/SKILL.md

@@ -12,6 +12,23 @@ description: Neta API research and recommendation skill — provide keyword/tag/
 3. Before content creation, use this skill to research topics/tags/categories, then hand off to `neta-creative` for concrete creation.
 4. When the user wants to like/comment or otherwise interact with specific works, switch to `neta-community`.
 
+## Authorization
+
+Use this when the user needs a **logged-in Neta identity** for CLI-backed flows and no valid session exists (or you would otherwise rely on `NETA_TOKEN`).
+
+1. **Start the flow**: run **`neta login`** (default action is `request-code`). 
+```bash
+npx -y @talesofai/neta-skills@latest login --action request-code
+```
+This begins the OAuth **device authorization** flow stored by the CLI.
+
+2. **Browser step**: When the command returns device-authorization fields, show the user **`verification_uri_complete`** (the ready-to-open URL), tell them to open it in a browser and finish sign-in/consent there, then **return to the chat and explicitly say the browser step is done** so you know when to continue.
+
+3. **Complete login**: After they confirm in chat, run **`neta login --action verify-code`** to exchange the device code for tokens. On success, show the returned **account basics**: **`uuid`** (long user id), **`nick_name`**, and **`avatar_url`**.
+```bash
+npx -y @talesofai/neta-skills@latest login --action verify-code
+```
+
 ## Core capabilities
 
 ### 1. suggest_keywords — keyword suggestions