{"_id":"@58pic/cli","_rev":"2-a1ba13cbcc5bdf5570193f7cf200ec2f","name":"@58pic/cli","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@58pic/cli","version":"0.1.0","keywords":["58pic","qiantu","cli","open-api"],"license":"MIT","_id":"@58pic/cli@0.1.0","maintainers":[{"name":"58pic","email":"xunaiwei@58pic.com"}],"homepage":"https://github.com/58pic-open/cli#readme","bugs":{"url":"https://github.com/58pic-open/cli/issues"},"bin":{"58pic":"dist/cli.js","58pic-cli":"dist/cli.js"},"dist":{"shasum":"23c297b0976b854043260b5577004e47a2849992","tarball":"https://registry.npmjs.org/@58pic/cli/-/cli-0.1.0.tgz","fileCount":19,"integrity":"sha512-ULTxdXn7mIwI0ebDq4J3s9m5owEsVhkqskcap6pJycjmrwcb6PbqaUl3WPc3ZIoWcJkkie23sHYNzmEa2kI4/Q==","signatures":[{"sig":"MEUCIQC3qv9DIOAQTKYbToCgcnZtTE+CLOiqbf9ULv6O2VslkAIgA9CwjPs+nQ/Vof5c5Y8XoUPMsrpWq4Xl8nefXxve9z8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":56169},"main":"dist/cli.js","type":"module","types":"./dist/cli.d.ts","engines":{"node":">=18.0.0"},"gitHead":"36c0b587a2fb6a4f2216b6ddccdcf8b540ead90b","scripts":{"cli":"node dist/cli.js","dev":"tsx src/cli.ts","build":"node node_modules/typescript/lib/tsc.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"58pic","email":"xunaiwei@58pic.com"},"repository":{"url":"git+https://github.com/58pic-open/cli.git","type":"git"},"_npmVersion":"11.6.2","description":"千图 AI 开放平台命令行工具（Open API）","directories":{},"_nodeVersion":"24.11.1","dependencies":{"commander":"^11.1.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.3","typescript":"~4.9.5","@types/node":"^18.19.0"},"_npmOperationalInternal":{"tmp":"tmp/cli_0.1.0_1775210833963_0.7317751154364864","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@58pic/cli","version":"0.1.1","description":"千图 AI 开放平台命令行工具（Open API）","type":"module","engines":{"node":">=18.0.0"},"bin":{"58pic":"dist/cli.js","58pic-cli":"dist/cli.js"},"main":"dist/cli.js","repository":{"type":"git","url":"git+https://github.com/58pic-open/cli.git"},"scripts":{"build":"node node_modules/typescript/lib/tsc.js","dev":"tsx src/cli.ts","cli":"node dist/cli.js","prepublishOnly":"npm run build"},"keywords":["58pic","qiantu","cli","open-api"],"license":"MIT","dependencies":{"commander":"^11.1.0"},"devDependencies":{"@types/node":"^18.19.0","tsx":"^4.19.3","typescript":"~4.9.5"},"gitHead":"6c933a1b88c66b24646637a7f2a059558511a035","types":"./dist/cli.d.ts","_id":"@58pic/cli@0.1.1","bugs":{"url":"https://github.com/58pic-open/cli/issues"},"homepage":"https://github.com/58pic-open/cli#readme","_nodeVersion":"24.11.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-HAlgucSjP9vSiUasEFRjx7SUz0/MvvicdgGjpBhwmzPMeUlQBlj+sYAqO5nNUCvDxODF4bLTvOYNhFGjZmBDhQ==","shasum":"7226cc67a0c79f7f0596be2a50c77f7825b26c4d","tarball":"https://registry.npmjs.org/@58pic/cli/-/cli-0.1.1.tgz","fileCount":19,"unpackedSize":58033,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCHxXxgMsyvZum1IwXjCx4b9z5wyugL4LdYMS3nicQYNMCIQCGfIOW3SL6l6A4CS4Ozq2344HyIFL9a6q957UcbH1sxA=="}]},"_npmUser":{"name":"58pic","email":"xunaiwei@58pic.com"},"directories":{},"maintainers":[{"name":"58pic","email":"xunaiwei@58pic.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cli_0.1.1_1778551334502_0.09977489305325449"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-03T10:07:13.885Z","modified":"2026-05-12T02:02:14.765Z","0.1.0":"2026-04-03T10:07:14.191Z","0.1.1":"2026-05-12T02:02:14.644Z"},"bugs":{"url":"https://github.com/58pic-open/cli/issues"},"license":"MIT","homepage":"https://github.com/58pic-open/cli#readme","keywords":["58pic","qiantu","cli","open-api"],"repository":{"type":"git","url":"git+https://github.com/58pic-open/cli.git"},"description":"千图 AI 开放平台命令行工具（Open API）","maintainers":[{"name":"58pic","email":"xunaiwei@58pic.com"}],"readme":"# 58pic（@58pic/cli）\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n[English](#english) | 中文\n\n**新手文档（图文快速上手）：** [58pic-cli · 快速上手指南](https://ai.58pic.com/58pic-cli-tutorial.html)\n\n面向 [千图 AI 开放平台](https://ai.58pic.com/history?openHistory=1&historyType=5) 的命令行工具：本地配置、常用接口快捷命令、通用 `api` 透传。支持 `config init`、`auth status`、`--format`、`dry-run` 等与常见开放平台 CLI 相近的用法。**Agent Skills** 通过开源 [**skills** CLI](https://github.com/vercel-labs/skills)（`npx skills add …`）从本仓库 `skills/` 安装到 Cursor、Claude Code 等，步骤见下文 [安装](#安装) 中的 **CLI 与 Agent Skills 配套安装**。\n\n## 为什么用 58pic-cli？\n\n- **分层清晰** — 配置一次后，优先用快捷命令；未封装的接口走 `58pic api`。\n- **Agent 友好** — `--format json` 便于管道与脚本；`dry-run` 可预览 URL。\n- **凭证灵活** — 配置文件、环境变量、命令行参数优先级明确。\n- **MIT** — 与上游开放能力条款以千图平台为准。\n\n## 功能一览\n\n| 领域 | 能力 |\n|------|------|\n| 配置 | 交互/非交互写入配置、脱敏查看、对齐 `auth status` |\n| 搜索 | 关键词搜索、AI 向量搜索、分页与分类参数 |\n| 目录 | 素材分类目录 `search-catalog` |\n| 模型 | 可用模型列表 `available-models` |\n| 下载 | 按 `pid` 取预览与下载临时链（涉及扣点，以平台规则为准） |\n| 生图 / 做同款 | 提交任务、查询状态（文生图无需垫图）；复杂 body 可用 `--body-file` |\n| 通用 | 任意 `open-platform/` 路由 + JSON 体或 GET 查询参数 |\n\n## 环境要求\n\n- **Node.js** ≥ 18（内置 `fetch`）\n- **Git** — 执行 `npx skills add 58pic-open/cli …`（从 GitHub 拉取 Skill）或 `npm install -g github:58pic-open/cli` 时，本机需已安装 **Git**，且 `git` 在 `PATH` 中可用。若只执行 `npm install -g @58pic/cli`、不安装 Skills，可不依赖 Git。\n\n## 快速开始（人类用户）\n\n> **前提：** 本机已能运行 `58pic` 命令。若尚未安装，请先完成下文 [安装](#安装)。\n\n### 1. 配置凭证（一次性）\n\n**获取 API Key：** 在浏览器登录后打开 [千图 AI 开放平台](https://ai.58pic.com/history?openHistory=1&historyType=5) 获取（页面与能力以官网为准）。\n\n交互式写入 `~/.config/58pic/config.json`（或 `XDG_CONFIG_HOME/58pic/config.json`）：\n\n> 若你曾使用旧版 `pic58` 命令，配置在 `~/.config/pic58/`，可手动把该目录改名为 `58pic`，或重新执行 `58pic config init`。\n\n```bash\n58pic config init\n```\n\n非交互：\n\n```bash\n58pic config init --api-key \"<你的 API Key>\"\n# 可选\n58pic config init --api-key \"<key>\" --base-url \"https://ai.58pic.com/api\"\n```\n\n默认 **Base URL** 为 `https://ai.58pic.com/api`，一般无需修改。\n\n### 2. 查看状态\n\n```bash\n58pic auth status\n# 等价信息也可：\n58pic config show\n```\n\n### 3. 调用接口\n\n```bash\n# 关键词搜索\n58pic search \"海报\"\n\n# AI 向量搜索（无关键词时使用 --ai）\n58pic search --ai\n\n# 分类目录\n58pic catalog\n\n# 模型列表\n58pic models\n\n# 按 pid 下载信息（临时链等，以接口返回为准）\n58pic download <pid>\n```\n\n## 快速开始（AI Agent）\n\n以下步骤面向 AI Agent（Cursor、Claude Code 等）。千图开放平台使用 **API Key** 认证，**无**浏览器 OAuth；Key 若已配置好，可从「验证」一步开始。\n\n> **给 AI 助手：** 先完成「CLI + Skills」两步安装，再配置 Key。详见下文 [安装](#安装) 中的 **CLI 与 Agent Skills 配套安装**。\n\n**第 1 步 — 安装 CLI 与 Skills**\n\n```bash\nnpm install -g @58pic/cli\n\nnpx skills add 58pic-open/cli -y -g\n```\n\n**第 2 步 — 配置凭证**\n\n若无 Key，引导用户至 [千图 AI 开放平台](https://ai.58pic.com/history?openHistory=1&historyType=5) 获取（须先登录）。\n\n任选其一：\n\n- 交互式（用户在终端完成）：`58pic config init`\n- 非交互（适合脚本 / Agent 代跑）：用户已提供 Key 时执行  \n  `58pic config init --api-key \"<API Key>\"`  \n  或在支持任意名称的环境注入（Docker、Kubernetes、CI 等）中设置 `58PIC_API_KEY`（见下节；**bash/zsh 的 `export` 不能以数字开头命名变量**，本地终端请优先用配置文件或 `--api-key`）\n\n**第 3 步 — 验证**\n\n```bash\n58pic auth status\n```\n\n**第 4 步 — 自动化调用习惯**\n\n- 管道与解析：为子命令加 **`--format json`**（默认多为 JSON；显式写出可避免歧义）。\n- 预览请求、避免误扣点：对等价 `api` 路由使用 **`58pic dry-run …`**（见下文）。\n- 敏感信息：勿把 Key 写进可被提交的仓库；在不可信环境限制 Key 暴露范围，避免日志与截屏泄露。\n\n### Agent Skills 说明\n\n| 项目 | 说明 |\n|------|------|\n| **安装命令** | `npx skills add 58pic-open/cli -y -g`（见 [安装](#安装) 中的 **CLI 与 Agent Skills 配套安装**）。 |\n| **Skill 源文件** | [`skills/58pic/SKILL.md`](skills/58pic/SKILL.md)，frontmatter 中 `name` 为 **`58pic`**（供 `npx skills add … --skill 58pic` 使用）。 |\n| **运行时** | Agent 仍通过 **终端执行 `58pic …`** 调开放平台；Skill 只提供结构化指令，不替代 CLI 二进制。 |\n| **离线 / 手动** | 若无法使用 `npx skills`，可将 `skills/58pic/` **复制或软链**到 Cursor 的 `.cursor/skills/`（或各 Agent 文档中的 skills 目录）。 |\n\n## 安装\n\n### 推荐（npm 注册表 + Skills）\n\n```bash\nnpm install -g @58pic/cli\n\nnpx skills add 58pic-open/cli -y -g\n```\n\n- CLI 包：[@58pic/cli](https://www.npmjs.com/package/@58pic/cli)（请使用官方源 `https://registry.npmjs.org/`；镜像未同步时可能 404，可加 `--registry=https://registry.npmjs.org/`）。\n- `npx skills` 由 [vercel-labs/skills](https://github.com/vercel-labs/skills) 提供；`58pic-open/cli` 为 GitHub `owner/repo` 简写，**需要本机已装 Git**；亦可使用完整地址 `https://github.com/58pic-open/cli`。\n\n### 从 GitHub 安装 CLI（备选，无需先 `git clone`）\n\nnpm 会临时拉取仓库；**`dist/` 已随仓库提交**，安装时不再执行编译，仅需安装运行时依赖（如 `commander`）后链接全局命令：\n\n```bash\n# 任选其一（需本机已装 Git）\nnpm install -g github:58pic-open/cli\n# 或\nnpm install -g https://github.com/58pic-open/cli.git\n```\n\n指定分支或 tag：\n\n```bash\nnpm install -g github:58pic-open/cli#main\nnpm install -g github:58pic-open/cli#v0.1.0\n```\n\n不全局安装、单次使用（会临时拉仓库并 build，首次较慢）：\n\n```bash\nnpx --package=github:58pic-open/cli 58pic --help\n```\n\n### 克隆仓库后本地开发\n\n```bash\ngit clone https://github.com/58pic-open/cli.git && cd cli\nnpm install              # 开发依赖；改源码后需 npm run build 更新 dist/\nnpm run build            # 如需单独编译\n\n# 全局链接（可选）\nnpm link\n```\n\n全局安装后命令名为 **`58pic`**（亦注册 **`58pic-cli`**，见 `package.json` 的 `bin`）。\n\n### CLI 与 Agent Skills 配套安装\n\n推荐顺序：**先 `npm install -g @58pic/cli`，再 `npx skills add 58pic-open/cli`**（与上文「推荐（npm 注册表 + Skills）」一致）。备选：CLI 也可从 `github:58pic-open/cli` 安装；Skills 亦支持仓库 URL `https://github.com/58pic-open/cli`。\n\n```bash\nnpm install -g @58pic/cli\nnpx skills add 58pic-open/cli -y -g\n```\n\n- **`-g`**：安装到用户级 Agent 目录（如 Cursor 的 `~/.cursor/skills/`）；去掉 `-g` 则默认装到**当前项目**（如 `./.agents/skills/`）。\n- **`-y`**：非交互、跳过确认（适合脚本与 AI Agent 代跑）。\n- Skill 源码在本仓库 [`skills/`](skills/) 下；发布到 npm 时 `skills/` 已列入 `package.json` 的 `files`。\n\n常用调试：\n\n```bash\nnpx skills add 58pic-open/cli --list\n\nnpx skills add 58pic-open/cli --skill 58pic -y -g\n\nnpx skills add 58pic-open/cli --skill 58pic -y -g -a cursor\n```\n\n更多参数见 [skills  README](https://github.com/vercel-labs/skills#readme)（`--agent`、`--copy` 等）。\n\n安装后若终端提示找不到 `58pic` / `58pic-cli`，见 [常见问题](#常见问题)。\n\n## 常见问题\n\n### 包名是 `@58pic/cli` 不是 `@58cpi/cli`\n\nnpm 上的 scope 为 **`@58pic/cli`**（**58pic** = 千图）。若误写成 `@58cpi/cli` 会安装失败。\n\n### 如何获取 API Key？\n\n在浏览器登录后打开 **[千图 AI 开放平台](https://ai.58pic.com/history?openHistory=1&historyType=5)** 获取 Key，再执行 `58pic config init`（或 `58pic config init --api-key \"<key>\"`）。具体以官网为准。\n\n### 出现 `zsh: command not found: 58pic-cli`\n\n说明 **npm 的全局 `bin` 目录不在当前 shell 的 `PATH` 里**（常见于 MxSrvs、自定义 Node 安装路径）。\n\n1. **看全局前缀并把 `bin` 加进 PATH**（把输出路径拼上 `/bin`）：\n\n   ```bash\n   npm prefix -g\n   ```\n\n   在 `~/.zshrc` 里增加一行（按你机器上的实际路径改）：\n\n   ```bash\n   export PATH=\"$(npm prefix -g)/bin:$PATH\"\n   ```\n\n   保存后执行 `source ~/.zshrc`，再试 `58pic --help`。\n\n2. **仓库内开发**：先 `npm run build`，再在项目根目录执行（不依赖全局 PATH）：\n\n   ```bash\n   npm run cli -- --help\n   # 或\n   npm exec --package=. -- 58pic --help\n   ```\n\n3. **已执行过 `npm link` 仍找不到**：同样检查第 1 步；`which npm`、`which node` 应对应同一套安装，避免混用多套 Node。\n\n### `npm install -g github:58pic-open/cli` 安装阶段报错（历史：`tsc` / code 127 / 254）\n\n**当前版本**已将编译产物 **`dist/` 提交到仓库**，并**去掉**安装时的 `prepare` 编译步骤；从 GitHub 全局安装时不再需要本机 TypeScript，一般不再出现与 `tsc` 相关的错误。请先拉取**最新** `main` 再执行：\n\n```bash\nnpm install -g github:58pic-open/cli\n```\n\n若仍失败：检查 Node ≥ 18、网络与 `npm` 缓存；可在克隆后的仓库内执行 `npm install && npm run build && npm link -g` 做本地链接，或换用官方 Node / nvm，避免混用多套 Node（如 MxSrvs 与 nvm 混用）。\n\n## 认证与凭证优先级\n\nAPI Key 解析顺序（后者覆盖前者）：\n\n1. 命令行 `--api-key`\n2. 环境变量 `58PIC_API_KEY`\n3. 配置文件中的 `apiKey`\n\nBase URL 解析顺序：\n\n1. `--base-url`\n2. `58PIC_BASE_URL`\n3. 配置文件 `baseUrl`\n4. 默认 `https://ai.58pic.com/api`\n\n> **说明：** `58PIC_API_KEY`、`58PIC_BASE_URL` 在 Node 进程内可读；在交互式 shell 里无法使用 `export 58PIC_API_KEY=…`（非合法标识符）。本地开发请用 `58pic config init` / `--api-key`，CI 与容器可在编排里正常配置上述名称。\n\n## 三层命令体系\n\n### 1. 快捷命令（常用 Open API）\n\n| 命令 | 说明 |\n|------|------|\n| `58pic search [keyword]` | `POST` `open-platform/search-images`，支持 `--page`、`--did`、`--kid`、`--ai` |\n| `58pic catalog` | `open-platform/search-catalog` |\n| `58pic models` | `open-platform/available-models` |\n| `58pic download <pid>` | `open-platform/image-download`（查询参数 `pid`） |\n| `58pic same-style` | `POST` `open-platform/same-style`，需 `-m/--model`；文生图仅需提示词（`--prompt` 或末尾多词）；垫图、pid、`--body-file` 均为可选 |\n| `58pic same-style-status <ai_id>` | `open-platform/same-style-status` |\n\n查看某命令参数：\n\n```bash\n58pic search --help\n58pic same-style --help\n\n# 文生图（不传垫图）\n58pic same-style -m <模型ID> --prompt \"一只水彩风格的猫\" --format json\n# 或末尾直接跟描述词\n58pic same-style -m <模型ID> 水彩 猫咪 特写 --format json\n```\n\n### 2. 通用 `api`（未封装路由）\n\n指定 **路由片段**（可写 `search-images` 或 `open-platform/search-images`，会自动规范为 `open-platform/...`），以及 JSON 请求体或 GET 查询对象。\n\n```bash\n# POST + JSON 字符串\n58pic api search-images --body '{\"keyword\":\"海报\",\"page\":1,\"did\":0,\"kid\":0,\"ai_search\":false}'\n\n# POST + 文件\n58pic api same-style --body-file ./payload.json\n\n# GET：将 JSON 对象的键值展开为 query（用于支持 GET 的路由）\n58pic api some-route -X GET --body '{\"foo\":\"bar\"}'\n```\n\n### 3. `dry-run`（不发起请求）\n\n仅打印将要请求的 **Method** 与完整 **URL**（含 `?r=open-platform/...`）：\n\n```bash\n58pic dry-run search-images -X POST\n```\n\n## 高级用法\n\n### 输出格式\n\n全局选项（适用于多数子命令）：\n\n| 值 | 行为 |\n|----|------|\n| `--format json` | 单行 JSON；`api`/快捷命令在封装层会输出 `{ http, body }` |\n| `--format pretty` | 缩进 JSON |\n| `--format table` | 当业务 `code === 200` 且 `data` 含 `list` 数组时，打印 `pid` 与标题简表；否则回退为 JSON |\n\n### 请求 URL 形式\n\n客户端将请求发至：`{baseUrl}/?r=open-platform/<route>`，Header：`Authorization: Bearer <apiKey>`。子命令按千图开放平台当前路由约定组织。\n\n## 开发\n\n```bash\nnpm run dev -- --help          # 直接跑 ts\nnpm run build                  # 编译到 dist/（提交前请把 dist 一并 commit，便于 github: 全局安装免编译）\n```\n\n发布到 npm 前 `prepublishOnly` 会执行 `npm run build`。\n\n## 安全提示\n\n- **API Key** 等同于账号能力，勿提交到仓库；优先用环境变量或本地配置文件权限控制。\n- **下载 / 做同款** 等接口可能产生扣点或计费，请在正式环境前阅读千图开放平台说明并在测试 Key 上验证。\n- 将 CLI 交给 AI Agent 使用时：限制 Key 与凭证可见范围，勿在不可信环境暴露；勿让自动化在未经确认时调用可能扣点的接口。\n\n## 开源协议\n\nMIT。调用千图开放平台接口时，须遵守平台用户协议、隐私政策及开放能力相关约定。\n\n---\n\n## English\n\n**Getting started (tutorial):** [58pic-cli quick guide](https://ai.58pic.com/58pic-cli-tutorial.html)\n\n**API Key:** after signing in, open the [Qiantu AI Open Platform](https://ai.58pic.com/history?openHistory=1&historyType=5) page to obtain a key, then run `58pic config init`.\n\n**58pic-cli** is a CLI for the [Qiantu (58pic) AI Open Platform](https://ai.58pic.com/history?openHistory=1&historyType=5): `config` / shortcut commands / generic `api` calls. Supports familiar patterns such as `config init`, `auth status`, `--format`, and `dry-run`.\n\n**Requirements:** Node.js ≥ 18. **Git** is required for `npx skills add 58pic-open/cli …` or `npm install -g github:58pic-open/cli`; ensure `git` is on your `PATH`. Global `npm install -g @58pic/cli` alone (no Skills from GitHub) may omit Git.\n\n**Install (recommended):**\n\n```bash\nnpm install -g @58pic/cli\nnpx skills add 58pic-open/cli -y -g\n```\n\nUse the official registry `https://registry.npmjs.org/` if a mirror returns 404 for `@58pic/cli`.\n\n**Install (CLI, alternatives):** From GitHub: `npm install -g github:58pic-open/cli` (prebuilt `dist/`; no compile at install). Local dev: `git clone`, `npm install`, `npm run build` after TS changes, use `58pic` (also `58pic-cli`).\n\n**Install (Agent Skills):** [vercel-labs/skills](https://github.com/vercel-labs/skills). `npx skills add 58pic-open/cli -y -g`. List: `npx skills add 58pic-open/cli --list`. Single skill: `npx skills add 58pic-open/cli --skill 58pic -y -g`. Full repo URL `https://github.com/58pic-open/cli` is also supported. Skills live under [`skills/`](skills/) and are included in the npm `files` field.\n\n**Credentials:** `--api-key` → `58PIC_API_KEY` → config file `apiKey`. Base URL: `--base-url` → `58PIC_BASE_URL` → config → default `https://ai.58pic.com/api`.\n\n**Quick examples:** `58pic config init`, `58pic auth status`, `58pic search \"keyword\"`, `58pic api <route> --body '{}'`.\n\n**Agents:** Install Skills with `npx skills add 58pic-open/cli -y -g`, then run **`58pic` in the terminal** as documented in [`skills/58pic/SKILL.md`](skills/58pic/SKILL.md).\n\n**FAQ:** The npm package is **`@58pic/cli`** (58**pic**), not `@58cpi/cli`. If you see `command not found: 58pic` / `58pic-cli`, add `$(npm prefix -g)/bin` to `PATH` (see **常见问题** above).\n\nSee the Chinese section above for the full command table, Agent flow, and options.\n","readmeFilename":"README.md"}