clipoox 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clipoox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# clipoox
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Clipoox from the terminal: sign in once, then call any Clipoox tool from a script or an automated job. Covers Timeline, media, AI generation, 3D Shot and SEO. These are the same tools your AI gets through the Clipoox connector (https://clipoox.com/mcp).
+
+Clipoox trong terminal: đăng nhập một lần, rồi gọi mọi công cụ Clipoox từ script hoặc tác vụ tự động. Gồm Timeline, media, tạo nội dung AI, 3D Shot và SEO. Đây cũng là bộ công cụ mà AI của bạn dùng qua connector Clipoox.
+
+Needs Node.js 18 or newer. / Cần Node.js 18 trở lên.
+
+```bash
+npx clipoox login            # opens your browser — sign in on clipoox.com
+npx clipoox tools            # the tools; ★ = uses credits
+npx clipoox call list_timelines
+npx clipoox call get_timeline '{"project_id":"…"}' --json
+npx clipoox upload intro.mp4 --timeline canvas:… --place   # a file from this computer → the project (and the timeline)
+npx clipoox export canvas:… --out film.mp4                 # export and download the MP4
+npx clipoox skill install                                  # teach Claude Code when to use this CLI
+npx clipoox logout
+```
+
+**upload** `<file> [--timeline <project>] [--place] [--at <s>] [--track <n>] [--label <name>] [--audio-rights]` — up to 100 MB. With `--timeline` it goes to the project's Media (`--place` also puts it on the timeline, `--at` / `--track` say where); without it, onto the canvas open in Clipoox. Audio needs `--audio-rights` (you confirm you may use it).
+
+**export** `<project> [--out <file.mp4>] [--quality final|review] [--start <s>] [--end <s>] [--sheet <frames.jpg>]` — waits for the export and saves the MP4 (and, with `--sheet`, the contact sheet of frames). The project must be open on the web or in the desktop app; otherwise it prints the link to open.
+
+**skill install** — writes `~/.claude/skills/clipoox-cli/SKILL.md` (or under `CLAUDE_CONFIG_DIR`): when Claude Code should use this CLI instead of the MCP tools (large results to a file, batch jobs, local files, MP4 on disk), and that credits are always confirmed with you first.
+
+**Arguments** are a JSON object, `@file.json`, or `-` to read stdin. `--json` prints the full result.
+
+**Credits.** A tool that uses credits shows its price first when it can (a `dry_run` call, nothing charged), then asks `[y/N]`. Without a keyboard (a script, CI), it needs `--yes`; otherwise it stops without calling anything. Ask for the price yourself with `'{"dry_run":true, …}'`.
+
+**Sign-in.** OAuth with PKCE in your own browser; the CLI never sees your password. The tokens are kept in `~/.config/clipoox/credentials.json` (Windows: `%APPDATA%\clipoox`), readable by your user account only. `CLIPOOX_CONFIG_DIR` puts them elsewhere.
+
+**Exit codes:** 0 ok · 1 the tool reported an error · 2 usage, or a paid call that was not confirmed · 3 not signed in.
+
+**Export.** `export_video` renders in the Clipoox editor, so the project must be open on the web or in the desktop app.
+
+Messages follow your system language (Vietnamese when `LANG` starts with `vi`).
+
+Setup for Claude Code, Codex CLI, Gemini CLI, ChatGPT and Cursor: https://platform.clipoox.com/connect

package/bin/clipoox.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// The `clipoox` command (npm package "clipoox"): see ../README.md.
+import { readFileSync } from 'node:fs'
+import { main } from '../lib/cli.mjs'
+
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+main(process.argv.slice(2), { version }).then((code) => { process.exitCode = code }, (e) => {
+  process.stderr.write(`clipoox: ${e?.message || e}\n`)
+  process.exitCode = 1
+})

package/lib/cli.mjs

@@ -0,0 +1,187 @@
+// clipoox — the Clipoox MCP tools from a terminal or a script, without an AI in between:
+//   clipoox login | logout | tools | call <tool> [json | @file.json | -] [--yes] [--json] | upload <file> | export <project> | skill install
+// Messages follow the system language (vi when LANG / LC_ALL starts with "vi", else en). Exit codes: 0 ok, 1 the tool or
+// the request failed, 2 usage / needs confirmation, 3 not signed in.
+import fs from 'node:fs'
+import readline from 'node:readline/promises'
+import { spawn } from 'node:child_process'
+import { login, refresh, expiring } from './oauth.mjs'
+import { mcpClient, spendsCredits, willSpend, quotes, resultText, AuthRequired } from './mcp.mjs'
+import { loadCredentials, saveCredentials, credentialsPath } from './store.mjs'
+import { upload, exportVideo, installSkill } from './commands.mjs'
+
+export const DEFAULT_MCP_URL = 'https://clipoox.com/mcp'
+const M = {
+  usage: {
+    vi: `Cách dùng:
+  clipoox login                      Đăng nhập Clipoox (mở trình duyệt)
+  clipoox logout                     Đăng xuất trên máy này
+  clipoox tools [--json]             Liệt kê công cụ (★ = tốn credit)
+  clipoox call <công cụ> [tham số]   Gọi một công cụ. Tham số: JSON, @tệp.json, hoặc - (đọc từ stdin)
+      --yes    đồng ý trước với công cụ tốn credit (bắt buộc khi chạy trong script)
+      --json   in kết quả đầy đủ dạng JSON
+  clipoox upload <tệp> [--timeline <dự án>] [--place] [--at <giây>] [--track <số>] [--label <tên>] [--audio-rights]
+                                     Đưa tệp trên máy (≤ 100 MB) vào Media của dự án (--place: đặt luôn lên timeline),
+                                     hoặc lên Canvas đang mở khi không có --timeline. Âm thanh cần --audio-rights.
+  clipoox export <dự án> [--out <tệp.mp4>] [--quality final|review] [--start <giây>] [--end <giây>] [--sheet <ảnh.jpg>]
+                                     Xuất MP4 rồi tải về máy (dự án phải đang mở trên web hoặc app desktop Clipoox)
+  clipoox skill install              Cài skill cho Claude Code (~/.claude/skills/clipoox-cli)
+Ví dụ:
+  clipoox call list_timelines
+  clipoox call get_timeline '{"project_id":"…"}' --json
+  clipoox upload intro.mp4 --timeline canvas:… --place
+  clipoox export canvas:… --out film.mp4`,
+    en: `Usage:
+  clipoox login                      Sign in to Clipoox (opens your browser)
+  clipoox logout                     Sign out on this computer
+  clipoox tools [--json]             List the tools (★ = uses credits)
+  clipoox call <tool> [arguments]    Call a tool. Arguments: JSON, @file.json, or - (read stdin)
+      --yes    agree in advance to a tool that uses credits (required in scripts)
+      --json   print the full result as JSON
+  clipoox upload <file> [--timeline <project>] [--place] [--at <s>] [--track <n>] [--label <name>] [--audio-rights]
+                                     Put a file from this computer (≤ 100 MB) in a project's Media (--place: on the
+                                     timeline too), or on the canvas open in Clipoox without --timeline. Audio needs --audio-rights.
+  clipoox export <project> [--out <file.mp4>] [--quality final|review] [--start <s>] [--end <s>] [--sheet <frames.jpg>]
+                                     Export an MP4 and download it (the project must be open on the web or in the desktop app)
+  clipoox skill install              Install the Claude Code skill (~/.claude/skills/clipoox-cli)
+Examples:
+  clipoox call list_timelines
+  clipoox call get_timeline '{"project_id":"…"}' --json
+  clipoox upload intro.mp4 --timeline canvas:… --place
+  clipoox export canvas:… --out film.mp4`,
+  },
+  opening: { vi: 'Mở trình duyệt để đăng nhập Clipoox. Nếu trình duyệt không mở, dán link này vào trình duyệt:', en: 'Opening your browser to sign in to Clipoox. If it does not open, paste this link into your browser:' },
+  page: { vi: 'Đã đăng nhập Clipoox CLI. Bạn có thể đóng tab này và quay lại terminal.', en: 'Clipoox CLI is signed in. You can close this tab and go back to the terminal.' },
+  signedIn: { vi: 'Đã đăng nhập. Thử: clipoox call get_account_summary', en: 'Signed in. Try: clipoox call get_account_summary' },
+  signedOut: { vi: 'Đã đăng xuất trên máy này.', en: 'Signed out on this computer.' },
+  needLogin: { vi: 'Chưa đăng nhập (hoặc phiên đã hết hạn). Chạy: clipoox login', en: 'Not signed in (or the sign-in expired). Run: clipoox login' },
+  noTool: { vi: (n) => `Không có công cụ "${n}". Xem danh sách: clipoox tools`, en: (n) => `No tool "${n}". See the list: clipoox tools` },
+  badArgs: { vi: 'Tham số phải là một đối tượng JSON, ví dụ {"limit":5}', en: 'Arguments must be a JSON object, e.g. {"limit":5}' },
+  paidAsk: { vi: (n) => `"${n}" tốn credit trong ví Clipoox của bạn. Tiếp tục? [y/N] `, en: (n) => `"${n}" uses credits from your Clipoox wallet. Continue? [y/N] ` },
+  paidNeedYes: { vi: (n) => `"${n}" tốn credit. Thêm --yes để đồng ý khi chạy không có bàn phím (script, CI).`, en: (n) => `"${n}" uses credits. Add --yes to agree when running without a keyboard (scripts, CI).` },
+  cancelled: { vi: 'Đã huỷ, không gọi công cụ.', en: 'Cancelled — the tool was not called.' },
+  paidMark: { vi: '★ tốn credit (gọi với "dry_run":true để xem giá, nếu công cụ có)', en: '★ uses credits (call with "dry_run":true for the price, when the tool has it)' },
+  uploaded: { vi: (f) => `Đã đưa ${f} vào Clipoox.`, en: (f) => `${f} is in Clipoox.` },
+  exporting: { vi: (d) => `Đang xuất${d.stage ? ` (${d.stage}${d.progress != null ? ` ${Math.round(d.progress * 100)}%` : ''})` : ''}…`, en: (d) => `Exporting${d.stage ? ` (${d.stage}${d.progress != null ? ` ${Math.round(d.progress * 100)}%` : ''})` : ''}…` },
+  exported: { vi: (f) => `Đã lưu ${f}`, en: (f) => `Saved ${f}` },
+  notOpen: { vi: 'Dự án chưa mở trong Clipoox nên chưa xuất được. Mở link này (web hoặc app desktop), để nguyên tab đó, rồi chạy lại:', en: 'The project is not open in Clipoox, so nothing was exported. Open this link (web or the desktop app), keep that tab open, then run again:' },
+  needFile: { vi: 'Thiếu tệp: clipoox upload <tệp>', en: 'Missing file: clipoox upload <file>' },
+  needProject: { vi: 'Thiếu dự án: clipoox export <dự án> (xem: clipoox call list_timelines)', en: 'Missing project: clipoox export <project> (see: clipoox call list_timelines)' },
+  skillSaved: { vi: (f) => `Đã cài skill cho Claude Code: ${f}\nMở phiên Claude Code mới để skill được nạp.`, en: (f) => `Installed the Claude Code skill: ${f}\nStart a new Claude Code session to load it.` },
+  price: { vi: 'Giá (kiểm tra trước, chưa trừ credit):', en: 'Price (checked first, nothing charged yet):' },
+}
+
+export function lang(env = process.env) { return /^vi/i.test(env.LC_ALL || env.LC_MESSAGES || env.LANG || '') ? 'vi' : 'en' }
+
+// flags that take a value (--out film.mp4 or --out=film.mp4)
+const VALUE_FLAGS = { '--timeline': 'timeline', '--at': 'at', '--track': 'track', '--label': 'label', '--out': 'out', '--quality': 'quality', '--start': 'start', '--end': 'end', '--sheet': 'sheet' }
+/** argv → { cmd, rest, flags }. Flags: --yes / -y, --json, --no-browser, --place, --audio-rights, --help / -h, --version / -v, and VALUE_FLAGS. */
+export function parseArgs(argv) {
+  const flags = {}, rest = []
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i], eq = a.indexOf('='), key = eq > 0 ? a.slice(0, eq) : a
+    if (VALUE_FLAGS[key]) { flags[VALUE_FLAGS[key]] = eq > 0 ? a.slice(eq + 1) : argv[++i]; continue }
+    if (a === '--place') flags.place = true
+    else if (a === '--audio-rights') flags.audioRights = true
+    else if (a === '--yes' || a === '-y') flags.yes = true
+    else if (a === '--json') flags.json = true
+    else if (a === '--no-browser') flags.noBrowser = true
+    else if (a === '--help' || a === '-h') flags.help = true
+    else if (a === '--version' || a === '-v') flags.version = true
+    else rest.push(a)
+  }
+  return { cmd: rest.shift(), rest, flags }
+}
+
+/** Tool arguments from the command line: inline JSON, @file, or - (stdin text given as `stdin`). */
+export function readToolArgs(spec, { stdin = '', readFile = (p) => fs.readFileSync(p, 'utf8') } = {}) {
+  if (spec == null || spec === '') return {}
+  const text = spec === '-' ? stdin : spec.startsWith('@') ? readFile(spec.slice(1)) : spec
+  const v = JSON.parse(text || '{}')
+  if (!v || typeof v !== 'object' || Array.isArray(v)) throw new Error('not an object')
+  return v
+}
+
+export function openBrowser(url, platform = process.platform) {
+  const [cmd, args] = platform === 'darwin' ? ['open', [url]] : platform === 'win32' ? ['rundll32', ['url.dll,FileProtocolHandler', url]] : ['xdg-open', [url]]
+  try { const p = spawn(cmd, args, { stdio: 'ignore', detached: true }); p.on('error', () => {}); p.unref() } catch { /* the link is printed anyway */ }
+}
+
+/**
+ * Run one command. io: { out, err, env, fetch, stdin (async → string), isTTY, ask (async question → answer), open, version }.
+ * Returns the exit code.
+ */
+export async function main(argv, io = {}) {
+  const env = io.env || process.env, L = lang(env), out = io.out || ((s) => process.stdout.write(`${s}\n`)), err = io.err || ((s) => process.stderr.write(`${s}\n`))
+  const fetch = io.fetch || globalThis.fetch, server = env.CLIPOOX_MCP_URL || DEFAULT_MCP_URL
+  const headers = { 'user-agent': `clipoox-cli/${io.version || '0'} (node ${process.versions.node})` }
+  const { cmd, rest, flags } = parseArgs(argv)
+  if (flags.version) { out(io.version || '0'); return 0 }
+  if (!cmd || flags.help || cmd === 'help') { out(M.usage[L]); return cmd || flags.help ? 0 : 2 }
+
+  if (cmd === 'login') {
+    const creds = await login(server, { fetch, headers, page: M.page[L], open: async (url) => { err(`${M.opening[L]}\n${url}`); if (!flags.noBrowser) (io.open || openBrowser)(url) } })
+    saveCredentials(server, creds, env)
+    out(M.signedIn[L]); return 0
+  }
+  if (cmd === 'logout') { saveCredentials(server, null, env); out(M.signedOut[L]); return 0 }
+  if (cmd === 'skill' && rest[0] === 'install') { out(M.skillSaved[L](installSkill(env))); return 0 }
+  if (!['tools', 'call', 'upload', 'export'].includes(cmd)) { err(M.usage[L]); return 2 }
+  if (cmd === 'upload' && !rest[0]) { err(M.needFile[L]); return 2 }
+  if (cmd === 'export' && !rest[0]) { err(M.needProject[L]); return 2 }
+  const num = (v) => (v == null ? undefined : Number(v))
+  if ([flags.at, flags.track, flags.start, flags.end].some((v) => v != null && !Number.isFinite(Number(v))) || (flags.quality && !['final', 'review'].includes(flags.quality))) { err(M.usage[L]); return 2 }
+
+  let creds = loadCredentials(server, env)
+  if (!creds) { err(M.needLogin[L]); return 3 }
+  const renew = async () => { const c = await refresh(creds, { fetch, headers }); if (!c) return false; creds = c; saveCredentials(server, c, env); return true }
+  if (expiring(creds)) await renew()
+  const client = mcpClient(server, { fetch, headers, token: () => creds.access_token, onUnauthorized: renew, clientInfo: { name: 'clipoox-cli', version: io.version || '0' } })
+  try {
+    if (cmd === 'upload') {
+      const place = flags.place || flags.at != null || flags.track != null ? { ...(flags.track != null ? { track: num(flags.track) } : {}), ...(flags.at != null ? { start: num(flags.at) } : {}) } : undefined
+      const r = await upload(client, rest[0], { project: flags.timeline, place, label: flags.label, audioRights: flags.audioRights, fetch })
+      if (flags.json) out(JSON.stringify(r.structuredContent ?? r, null, 2)); else { err(M.uploaded[L](rest[0])); out(resultText(r)) }
+      return 0
+    }
+    if (cmd === 'export') {
+      let last = ''
+      try {
+        const r = await exportVideo(client, rest[0], { out: flags.out, sheet: flags.sheet, quality: flags.quality, start: num(flags.start), end: num(flags.end), fetch, ...(io.sleep ? { sleep: io.sleep } : {}),
+          onProgress: (d) => { const s = M.exporting[L](d); if (s !== last) { err(s); last = s } } })
+        if (flags.json) out(JSON.stringify(r, null, 2)); else { out(M.exported[L](r.file)); if (r.summary) err(r.summary) }
+        return 0
+      } catch (e) { if (e.notOpen) { err(`${M.notOpen[L]}\n${e.url || ''}`); return 1 } throw e }
+    }
+    const tools = await client.listTools()
+    if (cmd === 'tools') {
+      if (flags.json) out(JSON.stringify(tools.map((t) => ({ name: t.name, title: t.title, description: t.description, usesCredits: spendsCredits(t), inputSchema: t.inputSchema })), null, 2))
+      else { for (const t of tools) out(`${spendsCredits(t) ? '★' : ' '} ${t.name}${t.title ? ` — ${t.title}` : ''}`); out(`\n${M.paidMark[L]}`) }
+      return 0
+    }
+    const name = rest[0], tool = tools.find((t) => t.name === name)
+    if (!tool) { err(M.noTool[L](name ?? '')); return 2 }
+    let args
+    try { args = readToolArgs(rest[1], { stdin: rest[1] === '-' ? await (io.stdin || readStdin)() : '' }) } catch { err(M.badArgs[L]); return 2 }
+    if (willSpend(tool, args) && !flags.yes) {
+      const tty = io.isTTY ?? (process.stdin.isTTY && process.stderr.isTTY)
+      if (!tty) { err(M.paidNeedYes[L](name)); return 2 }
+      // the price first when the tool can say it (dry_run): nothing is charged for it
+      if (quotes(tool)) { const q = await client.callTool(name, { ...args, dry_run: true }); err(`${M.price[L]}\n${resultText(q) || JSON.stringify(q.structuredContent ?? q, null, 2)}`) }
+      const a = await (io.ask || ask)(M.paidAsk[L](name))
+      if (!/^(y|yes|c|có|co)$/i.test(String(a).trim())) { err(M.cancelled[L]); return 2 }
+    }
+    const r = await client.callTool(name, args)
+    if (flags.json) out(JSON.stringify(r, null, 2))
+    else { const text = resultText(r); out(text || JSON.stringify(r.structuredContent ?? r, null, 2)) }
+    return r?.isError ? 1 : 0
+  } catch (e) {
+    if (e instanceof AuthRequired) { err(M.needLogin[L]); return 3 }
+    if (e.tool) { err(e.message); return 1 }
+    throw e
+  }
+}
+
+async function readStdin() { let s = ''; for await (const c of process.stdin) s += c; return s }
+async function ask(q) { const rl = readline.createInterface({ input: process.stdin, output: process.stderr }); try { return await rl.question(q) } finally { rl.close() } }
+export { credentialsPath }

package/lib/commands.mjs

@@ -0,0 +1,100 @@
+// The everyday jobs in one command each (0.2): upload a file from this computer, export a Timeline to an MP4 file,
+// install the Claude Code skill. Each is a short sequence of the same MCP tools `clipoox call` reaches.
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { Readable } from 'node:stream'
+import { resultText } from './mcp.mjs'
+
+export const MAX_UPLOAD_BYTES = 100 * 1024 * 1024
+const data = (r) => r?.structuredContent ?? {}
+/** A tool error as an Error (the tool's own words). */
+const fail = (r, what) => { if (r?.isError) throw Object.assign(new Error(resultText(r) || what), { tool: true }); return r }
+
+/**
+ * upload: request_upload → PUT the bytes to the private link (its exact headers) → add_media (a Timeline's Media bin,
+ * `place` also puts it on the timeline) or, without a project, push_to_canvas (the canvas open in Clipoox).
+ */
+export async function upload(client, file, { project, place, label, audioRights, fetch = globalThis.fetch } = {}) {
+  const st = fs.statSync(file)
+  if (!st.isFile()) throw new Error(`${file}: not a file`)
+  if (st.size < 1 || st.size > MAX_UPLOAD_BYTES) throw new Error(`${file}: ${st.size} bytes (1 byte – 100 MB)`)
+  const name = path.basename(file)
+  const link = data(fail(await client.callTool('request_upload', { file_name: name }), 'request_upload failed'))
+  if (!link.upload_url || !link.upload_id) throw new Error('request_upload: no upload link')
+  // the whole file in one body (≤ 100 MB): storage checks its length against the signed range
+  const put = await fetch(link.upload_url, { method: link.method || 'PUT', headers: link.headers || {}, body: fs.readFileSync(file) })
+  if (!put.ok) throw new Error(`upload: HTTP ${put.status}`)
+  const common = { upload_id: link.upload_id, ...(audioRights ? { audio_rights_confirmed: true } : {}) }
+  const r = project
+    ? await client.callTool('add_media', { project_id: project, ...common, label: label || name, ...(place ? { place } : {}) })
+    : await client.callTool('push_to_canvas', { ...common, caption: label || name })
+  return fail(r, 'adding the media failed')
+}
+
+/**
+ * export: export_video (waits up to 50 s) → get_export until it is done → the MP4 downloaded to `out`. `sheet` also saves
+ * the contact sheet (the frames the export shows). Stops after `timeoutMs`.
+ */
+export async function exportVideo(client, project, { out, sheet, quality, start, end, timeoutMs = 30 * 60_000, onProgress = () => {}, fetch = globalThis.fetch, now = () => Date.now(), sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
+  const t0 = now()
+  let r = fail(await client.callTool('export_video', { project_id: project, ...(quality ? { quality } : {}), ...(start != null ? { start_s: start } : {}), ...(end != null ? { end_s: end } : {}) }), 'export failed')
+  let d = data(r)
+  if (d.rendered === false) throw Object.assign(new Error(resultText(r).split('\n')[0] || 'the Timeline is not open in Clipoox'), { notOpen: true, url: d.url })
+  while (d.status !== 'done') {
+    if (!d.export_id) throw new Error(resultText(r).split('\n')[0] || 'export: no export id')
+    if (now() - t0 > timeoutMs) throw new Error(`export still running after ${Math.round(timeoutMs / 60000)} min (export_id ${d.export_id}: clipoox call get_export '{"export_id":"${d.export_id}"}')`)
+    onProgress(d)
+    // get_export waits up to 50 s on the server; a quick "not yet" is spaced out
+    const t = now(); r = fail(await client.callTool('get_export', { export_id: d.export_id }), 'export failed'); d = data(r)
+    if (d.status !== 'done' && now() - t < 2000) await sleep(2000)
+  }
+  if (!d.download_url) throw new Error('export: no download link')
+  const file = out || `clipoox-${d.export_id}.mp4`
+  const res = await fetch(d.download_url)
+  if (!res.ok || !res.body) throw new Error(`download: HTTP ${res.status}`)
+  const tmp = `${file}.part`
+  await new Promise((ok, bad) => { const w = fs.createWriteStream(tmp); Readable.fromWeb(res.body).on('error', bad).pipe(w).on('finish', ok).on('error', bad) })
+  fs.renameSync(tmp, file)
+  const img = (r.content || []).find((c) => c?.type === 'image' && c.data)
+  if (sheet && img) fs.writeFileSync(sheet, Buffer.from(img.data, 'base64'))
+  return { file, sheet: sheet && img ? sheet : null, summary: resultText(r).split('\n')[0], ...d }
+}
+
+/** Where Claude Code looks for personal skills (CLAUDE_CONFIG_DIR, else ~/.claude). */
+export const skillDir = (env = process.env) => path.join(env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude'), 'skills', 'clipoox-cli')
+export const SKILL = `---
+name: clipoox-cli
+description: Use the \`clipoox\` command (npm package clipoox) from the shell when working with Clipoox in Claude Code — big Timeline reads kept out of the chat (write JSON to a file, read parts with jq), batch jobs over many files or projects, uploading local files, exporting MP4s to disk, scheduled / CI runs. Prefer the Clipoox MCP tools for single small calls when they are connected.
+---
+
+# Clipoox from the shell (\`clipoox\`)
+
+The same tools as the Clipoox MCP connector, as a command. Sign-in is saved on this computer (\`npx clipoox login\` once, in the user's browser — never ask for a password).
+
+## When to use it instead of the MCP tools
+- **Large results:** \`npx clipoox call get_timeline '{"project_id":"…"}' --json > tl.json\`, then \`jq\` only what you need. The MCP call would put the whole timeline into the conversation.
+- **Many items:** a shell loop over files / projects (\`upload\`, \`call edit_timeline\`) instead of one tool call per item.
+- **Local files:** \`npx clipoox upload <file> --timeline <project_id> [--place]\` (≤ 100 MB; without --timeline it goes to the canvas open in Clipoox). Audio: add \`--audio-rights\` only after the user confirms they may use it.
+- **An MP4 on disk:** \`npx clipoox export <project_id> --out film.mp4 [--quality review] [--sheet frames.jpg]\` — the project must be open in Clipoox (web or desktop app); otherwise it says so with the link to open.
+- **No MCP:** the connector is not loaded in this session, or a script / cron job / CI runs without an AI.
+
+## Commands
+- \`npx clipoox tools [--json]\` — every tool (★ = uses credits) and, with --json, its input schema.
+- \`npx clipoox call <tool> [json | @file.json | -] [--json]\` — one tool. Read \`get_timeline_guide\` for edit_timeline ops.
+- \`npx clipoox upload <file> [--timeline <id>] [--place] [--at <s>] [--track <n>] [--label <text>] [--audio-rights]\`
+- \`npx clipoox export <id> [--out <file.mp4>] [--quality final|review] [--start <s>] [--end <s>] [--sheet <file.jpg>]\`
+
+## Credits — always ask the user first
+A ★ tool (or a call with max_credits / confirmed) spends the user's credits. Get the price with \`'{"dry_run":true, …}'\` where the tool has it, tell the user, and only after they agree run it with \`--yes\` (without a keyboard the CLI refuses paid calls without --yes). Never add --yes on your own.
+
+## Exit codes
+0 ok · 1 the tool reported an error (read stderr) · 2 usage / a paid call not confirmed · 3 not signed in → ask the user to run \`npx clipoox login\`.
+`
+export function installSkill(env) {
+  const dir = skillDir(env)
+  fs.mkdirSync(dir, { recursive: true })
+  const file = path.join(dir, 'SKILL.md')
+  fs.writeFileSync(file, SKILL)
+  return file
+}

package/lib/mcp.mjs

@@ -0,0 +1,82 @@
+// A small MCP client over Streamable HTTP (JSON-RPC POSTs; the answer is JSON or a text/event-stream): initialize once,
+// then tools/list and tools/call. No SDK, no dependencies — the CLI installs nothing but itself.
+export const PROTOCOL_VERSION = '2025-06-18'
+
+/** The JSON-RPC messages in a text/event-stream body (`data:` lines of each event; comments / keep-alives skipped). */
+export function parseSse(text) {
+  const out = []
+  for (const block of text.replace(/\r\n/g, '\n').split('\n\n')) {
+    const data = block.split('\n').filter((l) => l.startsWith('data:')).map((l) => l.slice(5).replace(/^ /, '')).join('\n')
+    if (!data) continue
+    try { out.push(JSON.parse(data)) } catch { /* not JSON: ignore */ }
+  }
+  return out
+}
+
+export class AuthRequired extends Error { constructor() { super('sign-in required'); this.name = 'AuthRequired' } }
+
+/**
+ * `token()` gives the current access token; `onUnauthorized()` may return a new one (refresh) — a 401 is retried once
+ * with it, else AuthRequired is thrown.
+ */
+export function mcpClient(url, { fetch = globalThis.fetch, token, onUnauthorized, headers = {}, clientInfo = { name: 'clipoox-cli', version: '0' } } = {}) {
+  let session = null, nextId = 1, ready = null
+  async function post(body, { notify = false, retried = false } = {}) {
+    const res = await fetch(url, { method: 'POST', headers: { ...headers, 'content-type': 'application/json', accept: 'application/json, text/event-stream', authorization: `Bearer ${await token()}`, ...(session ? { 'mcp-session-id': session } : {}), 'mcp-protocol-version': PROTOCOL_VERSION }, body: JSON.stringify(body) })
+    if (res.status === 401) {
+      await res.text().catch(() => {})
+      if (!retried && onUnauthorized && await onUnauthorized()) return post(body, { notify, retried: true })
+      throw new AuthRequired()
+    }
+    const sid = res.headers.get('mcp-session-id'); if (sid) session = sid
+    if (notify) { await res.text().catch(() => {}); if (!res.ok && res.status !== 202) throw new Error(`MCP: HTTP ${res.status}`); return null }
+    const type = res.headers.get('content-type') || '', text = await res.text()
+    if (!res.ok) throw new Error(`MCP: HTTP ${res.status}${text ? ` — ${text.slice(0, 300)}` : ''}`)
+    const msgs = type.includes('text/event-stream') ? parseSse(text) : [JSON.parse(text)]
+    const reply = msgs.flat().find((m) => m && m.id === body.id && ('result' in m || 'error' in m))
+    if (!reply) throw new Error('MCP: no answer to the request')
+    if (reply.error) throw Object.assign(new Error(`MCP error ${reply.error.code}: ${reply.error.message}`), { rpc: reply.error })
+    return reply.result
+  }
+  const request = (method, params) => post({ jsonrpc: '2.0', id: nextId++, method, ...(params ? { params } : {}) })
+  async function init() {
+    const r = await request('initialize', { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo })
+    await post({ jsonrpc: '2.0', method: 'notifications/initialized' }, { notify: true })
+    return r
+  }
+  const start = () => (ready ??= init().catch((e) => { ready = null; throw e }))
+  return {
+    initialize: start,
+    async listTools() {
+      await start()
+      const tools = []; let cursor
+      do { const r = await request('tools/list', cursor ? { cursor } : {}); tools.push(...(r.tools || [])); cursor = r.nextCursor } while (cursor && tools.length < 2000)
+      return tools
+    },
+    async callTool(name, args = {}) { await start(); return request('tools/call', { name, arguments: args }) },
+  }
+}
+
+/**
+ * Does this tool spend credits? Clipoox marks it in the description ("Spends credits", "PAID (metered…)", "Tốn credit");
+ * free tools start "Free — no credits" (edit_timeline's paid ops are then priced with dry_run / max_credits, see
+ * willSpend). "does not … spend credits" is not a mark.
+ */
+export function spendsCredits(tool) {
+  const d = String(tool?.description || '').replace(/\b(does not|doesn'?t|without|never|not)\b[^.]{0,40}?\b(spend|charg|cost|use)\w*\s+credits?/gi, '')
+  if (/^\s*free\b/i.test(d)) return false
+  return /\b(spends?|uses?|deducts?|costs?|charges?)\s+(the user'?s\s+)?(clipoox\s+)?credits?\b|\bpaid\b|\bmetered\b|tốn credit|trừ credit/i.test(d)
+}
+/**
+ * Would this call spend credits? A paid tool unless it is only a price check (dry_run: true); a free tool when the call
+ * carries a price it agrees to (max_credits, or run_ai_editor's confirmed: true).
+ */
+export function willSpend(tool, args = {}) {
+  if (args.dry_run === true) return false
+  return spendsCredits(tool) || args.max_credits != null || args.confirmed === true
+}
+/** The tool can say its price first (it takes dry_run). */
+export const quotes = (tool) => !!tool?.inputSchema?.properties?.dry_run
+
+/** The text a tool result shows (its text parts), for printing. */
+export const resultText = (r) => (r?.content || []).filter((c) => c?.type === 'text').map((c) => c.text).join('\n')

package/lib/oauth.mjs

@@ -0,0 +1,94 @@
+// Sign-in as every MCP client does (Claude Code, Codex, Gemini CLI): OAuth 2.1 authorization code + PKCE (S256), the client
+// registered on the fly (RFC 7591), the browser sent to clipoox.com and back to a one-off listener on 127.0.0.1.
+// The CLI never sees a password — the user signs in on clipoox.com in their own browser.
+import crypto from 'node:crypto'
+import http from 'node:http'
+
+export const SCOPE = 'clipoox:use'
+const b64url = (buf) => Buffer.from(buf).toString('base64url')
+export function pkcePair() {
+  const verifier = b64url(crypto.randomBytes(32))
+  return { verifier, challenge: b64url(crypto.createHash('sha256').update(verifier).digest()) }
+}
+
+async function json(res, what) {
+  const text = await res.text()
+  let body; try { body = JSON.parse(text) } catch { body = null }
+  if (!res.ok) throw Object.assign(new Error(`${what}: HTTP ${res.status}${body?.error ? ` (${body.error}${body.error_description ? `: ${body.error_description}` : ''})` : ''}`), { status: res.status, body })
+  if (!body || typeof body !== 'object') throw new Error(`${what}: not JSON`)
+  return body
+}
+
+/** The authorization server of an MCP URL (protected resource metadata → authorization server metadata). */
+export async function discover(mcpUrl, { fetch = globalThis.fetch, headers = {} } = {}) {
+  const u = new URL(mcpUrl)
+  let prm
+  for (const p of [`/.well-known/oauth-protected-resource${u.pathname.replace(/\/$/, '')}`, '/.well-known/oauth-protected-resource']) {
+    const r = await fetch(new URL(p, u.origin), { headers })
+    if (r.ok) { prm = await json(r, 'protected resource metadata'); break }
+  }
+  if (!prm?.authorization_servers?.length) throw new Error('no authorization server for this MCP URL')
+  const issuer = new URL(prm.authorization_servers[0])
+  const as = await json(await fetch(new URL(`/.well-known/oauth-authorization-server${issuer.pathname.replace(/\/$/, '')}`, issuer.origin), { headers }), 'authorization server metadata')
+  for (const k of ['authorization_endpoint', 'token_endpoint', 'registration_endpoint']) if (typeof as[k] !== 'string') throw new Error(`authorization server: no ${k}`)
+  if (!(as.code_challenge_methods_supported || ['S256']).includes('S256')) throw new Error('authorization server: no PKCE S256')
+  return { resource: prm.resource || mcpUrl, metadata: as }
+}
+
+/** A one-off listener on 127.0.0.1 (random port) that waits for /callback?code&state. */
+export function callbackServer({ page = 'Done — you can close this tab.' } = {}) {
+  let resolve, reject
+  const result = new Promise((a, b) => { resolve = a; reject = b })
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url, 'http://127.0.0.1')
+    if (url.pathname !== '/callback') { res.writeHead(404).end(); return }
+    res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' })
+    res.end(`<!doctype html><meta charset="utf-8"><title>Clipoox CLI</title><body style="font:16px system-ui;padding:40px">${page}</body>`)
+    resolve(Object.fromEntries(url.searchParams))
+  })
+  const ready = new Promise((ok, bad) => { server.once('error', bad); server.listen(0, '127.0.0.1', () => ok(server.address().port)) })
+  return { ready, result, close: () => server.close(), fail: (e) => reject(e) }
+}
+
+/**
+ * Full sign-in. `open(url)` shows the authorize page to the user (their browser); resolves with the tokens to save.
+ * `timeoutMs` bounds the wait for the browser.
+ */
+export async function login(mcpUrl, { fetch = globalThis.fetch, open, headers = {}, clientName = 'Clipoox CLI', page, timeoutMs = 300_000 } = {}) {
+  const { resource, metadata } = await discover(mcpUrl, { fetch, headers })
+  const cb = callbackServer({ page })
+  try {
+    const port = await cb.ready, redirectUri = `http://127.0.0.1:${port}/callback`
+    const reg = await json(await fetch(metadata.registration_endpoint, { method: 'POST', headers: { ...headers, 'content-type': 'application/json' }, body: JSON.stringify({ client_name: clientName, redirect_uris: [redirectUri], grant_types: ['authorization_code', 'refresh_token'], response_types: ['code'], token_endpoint_auth_method: 'none', scope: SCOPE }) }), 'client registration')
+    if (typeof reg.client_id !== 'string') throw new Error('client registration: no client_id')
+    const { verifier, challenge } = pkcePair(), state = b64url(crypto.randomBytes(16))
+    const auth = new URL(metadata.authorization_endpoint)
+    for (const [k, v] of Object.entries({ response_type: 'code', client_id: reg.client_id, redirect_uri: redirectUri, scope: SCOPE, state, code_challenge: challenge, code_challenge_method: 'S256', resource })) auth.searchParams.set(k, v)
+    await open(auth.toString())
+    const timer = setTimeout(() => cb.fail(new Error('sign-in timed out')), timeoutMs)
+    let q; try { q = await cb.result } finally { clearTimeout(timer) }
+    if (q.state !== state) throw new Error('sign-in answer does not match this request (state)')
+    if (q.error) throw new Error(`sign-in refused: ${q.error}${q.error_description ? ` (${q.error_description})` : ''}`)
+    if (!q.code) throw new Error('sign-in returned no code')
+    const tok = await tokenRequest(metadata.token_endpoint, { grant_type: 'authorization_code', code: q.code, redirect_uri: redirectUri, client_id: reg.client_id, code_verifier: verifier, resource }, { fetch, headers })
+    return withMeta(tok, { client_id: reg.client_id, token_endpoint: metadata.token_endpoint, resource })
+  } finally { cb.close() }
+}
+
+async function tokenRequest(endpoint, form, { fetch, headers }) {
+  const tok = await json(await fetch(endpoint, { method: 'POST', headers: { ...headers, 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' }, body: new URLSearchParams(form).toString() }), 'token')
+  if (typeof tok.access_token !== 'string') throw new Error('token: no access_token')
+  return tok
+}
+const withMeta = (tok, meta) => ({ access_token: tok.access_token, refresh_token: tok.refresh_token, expires_at: Number.isFinite(tok.expires_in) ? Date.now() + tok.expires_in * 1000 : undefined, ...meta })
+
+/** A fresh access token from the saved refresh token (null when there is none or the server refuses it). */
+export async function refresh(creds, { fetch = globalThis.fetch, headers = {} } = {}) {
+  if (!creds?.refresh_token || !creds.token_endpoint) return null
+  try {
+    const tok = await tokenRequest(creds.token_endpoint, { grant_type: 'refresh_token', refresh_token: creds.refresh_token, client_id: creds.client_id, ...(creds.resource ? { resource: creds.resource } : {}) }, { fetch, headers })
+    return withMeta({ refresh_token: creds.refresh_token, ...tok }, { client_id: creds.client_id, token_endpoint: creds.token_endpoint, resource: creds.resource })
+  } catch (e) { if (e.status >= 400 && e.status < 500) return null; throw e }
+}
+/** True when the access token is expired or within a minute of it. */
+export const expiring = (creds, now = Date.now()) => Number.isFinite(creds?.expires_at) && creds.expires_at - now < 60_000

package/lib/store.mjs

@@ -0,0 +1,32 @@
+// Where the CLI keeps its sign-in: one JSON file readable only by the user (0600 in a 0700 folder).
+//   macOS / Linux: $XDG_CONFIG_HOME/clipoox or ~/.config/clipoox · Windows: %APPDATA%\clipoox · CLIPOOX_CONFIG_DIR overrides.
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+export function configDir(env = process.env, platform = process.platform) {
+  if (env.CLIPOOX_CONFIG_DIR) return env.CLIPOOX_CONFIG_DIR
+  if (platform === 'win32' && env.APPDATA) return path.join(env.APPDATA, 'clipoox')
+  return path.join(env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'clipoox')
+}
+export const credentialsPath = (env) => path.join(configDir(env), 'credentials.json')
+
+/** The saved sign-in for `server` (the MCP URL), or null. */
+export function loadCredentials(server, env) {
+  try {
+    const all = JSON.parse(fs.readFileSync(credentialsPath(env), 'utf8'))
+    const c = all?.[server]
+    return c && typeof c.access_token === 'string' ? c : null
+  } catch { return null }
+}
+export function saveCredentials(server, creds, env) {
+  const file = credentialsPath(env)
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 })
+  let all = {}
+  try { all = JSON.parse(fs.readFileSync(file, 'utf8')) || {} } catch { /* first sign-in */ }
+  if (creds) all[server] = creds; else delete all[server]
+  const tmp = `${file}.${process.pid}.tmp`
+  fs.writeFileSync(tmp, JSON.stringify(all, null, 2), { mode: 0o600 })
+  fs.renameSync(tmp, file)
+  try { fs.chmodSync(file, 0o600) } catch { /* Windows: ACLs of the profile folder */ }
+}

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "clipoox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Clipoox from the terminal: sign in once, then call any Clipoox MCP tool (Timeline, media, AI generation, 3D Shot, SEO) from scripts.",
+  "type": "module",
+  "bin": {
+    "clipoox": "bin/clipoox.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "keywords": [
+    "clipoox",
+    "mcp",
+    "video",
+    "cli"
+  ],
+  "homepage": "https://platform.clipoox.com/connect",
+  "license": "MIT"
+}