@hintoai/cli 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hinto AI
+
+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

@@ -0,0 +1,429 @@
+# @hintoai/cli
+
+[![npm version](https://img.shields.io/npm/v/@hintoai/cli.svg)](https://www.npmjs.com/package/@hintoai/cli)
+[![CI](https://github.com/hintoai/hinto-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/hintoai/hinto-cli/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+Command-line interface for the [Hinto AI](https://hinto.ai) API. Manage videos, articles, folders, templates, and publishing from your terminal or from AI agents and scripts.
+
+## Installation
+
+```bash
+npm install -g @hintoai/cli
+```
+
+Requires Node.js 18+.
+
+### Use it from an AI agent (Claude Code, Cursor, …)
+
+Install the bundled skill into any supported agent with the universal [skills CLI](https://github.com/vercel-labs/skills):
+
+```bash
+npx skills add hintoai/hinto-cli
+# target specific agents:
+npx skills add hintoai/hinto-cli -a claude-code -a cursor
+```
+
+The skill bootstraps the CLI itself (`npm install -g @hintoai/cli`) on first use, so this one command is enough to go from zero to a working agent integration.
+
+## Authentication
+
+Run `init` once with your API key to store credentials locally:
+
+```bash
+hinto init --key <your-api-key>
+```
+
+Credentials are stored in `~/.hinto/config.json` with `0600` permissions (owner-read only). You can override the stored key at any time with the `HINTO_API_KEY` environment variable — the env var always takes precedence.
+
+## Quickstart
+
+```bash
+npm install -g @hintoai/cli
+hinto init --key <your-api-key>
+hinto videos upload --file ./demo.mp4 --json
+hinto templates article --json
+hinto generate start --video <videoId> --template <templateId> --wait --json
+hinto publish now --json
+```
+
+## Shell completions
+
+```bash
+# bash (add to ~/.bashrc)
+eval "$(hinto completion bash)"
+
+# zsh (add to ~/.zshrc)
+eval "$(hinto completion zsh)"
+
+# fish
+hinto completion fish | source
+```
+
+## Global flags
+
+| Flag | Description |
+|------|-------------|
+| `--api-url <url>` | Override the Hinto base URL (useful for local dev or self-hosted) |
+| `--json` | Output raw JSON instead of human-readable tables / key-value pairs |
+| `--version` | Print CLI version |
+| `--help` | Print help for any command |
+
+## Commands
+
+### `hinto project`
+
+```bash
+hinto project get
+hinto project get --json
+hinto project structure --json
+hinto project update --name "New Name"
+hinto project languages
+hinto project retranslate --lang fr             # fire-and-forget
+hinto project retranslate --lang fr --wait      # block until done
+```
+
+`project get --json` — the response is wrapped in a `project` key:
+
+```json
+{
+  "project": {
+    "id": "cc63bccf-4b76-4672-b46f-92a9c0a01567",
+    "name": "My Docs",
+    "url_slug": "my-docs",
+    "description": null,
+    "language": "en",
+    "is_published": true,
+    "logo_url": null,
+    "project_type": "docs",
+    "is_archived": false,
+    "created_at": "2026-01-10T09:00:00Z",
+    "custom_domain": null,
+    "custom_domain_verified": false
+  }
+}
+```
+
+### `hinto templates`
+
+```bash
+hinto templates article              # article templates for this project type
+hinto templates article --json
+hinto templates structure            # structure templates for this project type
+hinto templates structure --json
+```
+
+Templates are automatically scoped to your project type.
+
+`templates article --json` — `requires_video` tells you whether a template needs a video to generate from:
+
+```json
+{
+  "templates": [
+    {
+      "id": 1,
+      "name": "Tutorial",
+      "description": "Step-by-step guide format",
+      "requires_video": true,
+      "image_url": "https://cdn.hinto.ai/templates/tutorial.png",
+      "sort_order": 1
+    }
+  ]
+}
+```
+
+### `hinto folders`
+
+```bash
+hinto folders list
+hinto folders list --json
+hinto folders get <id>
+hinto folders get <id> --json
+hinto folders create --name "Release Notes"
+hinto folders create --name "Q2" --parent <parentId>
+hinto folders update <id> --name "Q3"
+hinto folders move <id> --parent <newParentId>  # move into another folder
+hinto folders move <id>                         # move to root
+hinto folders delete <id>
+```
+
+`folders create --json`:
+
+```json
+{ "id": 7, "name": "Release Notes", "parent_id": null }
+```
+
+> **Note:** `folders move` does **not** return the updated folder — it returns a confirmation object:
+>
+> ```json
+> { "message": "Folder moved", "parentId": null }
+> ```
+
+### `hinto articles`
+
+```bash
+hinto articles list
+hinto articles list --folder <folderId>
+hinto articles list --json
+
+hinto articles get <id>
+hinto articles get <id> --json
+
+# --content is required; pass a Markdown string or a @filepath
+hinto articles create --title "Getting Started" --content "# Hello\n\nWorld."
+hinto articles create --title "From file" --content @path/to/article.md
+hinto articles create --title "In a folder" --content "..." --folder <folderId>
+
+hinto articles update <id> --title "New Title"
+hinto articles update <id> --slug "new-slug"
+
+hinto articles duplicate <id>
+hinto articles move <id> --folder <folderId>
+hinto articles regenerate <id>
+
+hinto articles versions <id>
+hinto articles restore <id> --vid <vId>
+
+hinto articles translations <id>
+hinto articles translate <id> --lang fr
+
+hinto articles delete <id>
+```
+
+`articles list --json` — includes a `pagination` object:
+
+```json
+{
+  "articles": [
+    {
+      "id": 42,
+      "title": "Getting Started",
+      "slug": "getting-started",
+      "folder_id": null,
+      "inserted_at": "2026-01-15T10:00:00Z",
+      "updated_at": "2026-05-01T14:32:00Z"
+    }
+  ],
+  "pagination": { "limit": 50, "offset": 0, "count": 1 }
+}
+```
+
+`articles get <id> --json` — note the `metadata` wrapper for SEO fields, and that `content` is the full rendered output in the requested format:
+
+```json
+{
+  "id": 42,
+  "title": "Getting Started",
+  "slug": "getting-started",
+  "format": "markdown",
+  "content": "# Getting Started\n\nWelcome to Hinto.",
+  "metadata": {
+    "metaDescription": null,
+    "metaKeywords": null,
+    "jsonLd": null,
+    "createdAt": "2026-01-15T10:00:00Z",
+    "updatedAt": "2026-05-01T14:32:00Z"
+  }
+}
+```
+
+`articles create --json` — returns only the essentials (`slug` may be `null` immediately after creation); fetch with `articles get` if you need the full article:
+
+```json
+{ "id": 42, "title": "Getting Started", "slug": null }
+```
+
+> **Note:** `articles move` does **not** return the updated article — it returns a confirmation object:
+>
+> ```json
+> { "message": "Article moved", "folderId": 7 }
+> ```
+
+### `hinto videos`
+
+```bash
+hinto videos list
+hinto videos list --json
+hinto videos get <videoId>
+hinto videos status <videoId>
+hinto videos import --url https://example.com/video.mp4
+hinto videos delete <videoId>
+```
+
+### `hinto generate`
+
+```bash
+# fire-and-forget with explicit template
+hinto generate start --video <videoId> --template <templateId>
+
+# fire-and-forget with auto-selected template (optional --template)
+hinto generate start --video <videoId>
+
+# block until the job completes
+hinto generate start --video <videoId> --template <templateId> --wait --json
+
+# without --template, server picks the default
+hinto generate start --video <videoId> --wait --json
+
+# check an existing job
+hinto generate status <jobId> --json
+
+# generate / refresh project structure
+hinto generate structure --video <videoId>
+hinto generate structure --video <videoId> --wait
+```
+
+`generate start --json` (fire-and-forget) — use `jobId` to poll status:
+
+```json
+{
+  "jobId": "job_a1b2c3d4",
+  "articleId": 42,
+  "status": "pending",
+  "message": "Article generation started. Poll the job status endpoint for updates."
+}
+```
+
+`generate status <jobId> --json` once complete:
+
+```json
+{
+  "jobId": "job_a1b2c3d4",
+  "type": "generate_article",
+  "status": "completed",
+  "output": { "articleId": 42 },
+  "error": null,
+  "createdAt": "2026-05-16T10:00:00Z",
+  "completedAt": "2026-05-16T10:02:34Z"
+}
+```
+
+Possible `status` values: `pending` · `processing` · `completed` · `failed`.
+
+### `hinto export`
+
+```bash
+hinto export article <id> --format md           # print Markdown to stdout
+hinto export article <id> --format html         # print HTML to stdout
+hinto export article <id> --format md --out article.md   # write to file
+
+hinto export folder <id> --out folder.zip
+hinto export project --out project.zip
+```
+
+### `hinto publish`
+
+```bash
+hinto publish status
+hinto publish status --json
+hinto publish now                               # fire-and-forget
+hinto publish now --wait                        # block until live
+hinto publish now --wait --json
+hinto publish republish
+hinto publish republish --wait
+```
+
+`publish status --json` — the `status` field is a convenience alias derived from `isPublished`:
+
+```json
+{
+  "isPublished": true,
+  "slug": "my-docs",
+  "url": "https://my-docs.hintoai.com",
+  "publicationId": "pub_xyz789",
+  "publishedAt": "2026-04-20T09:00:00Z",
+  "articlesCount": 12,
+  "foldersCount": 3,
+  "status": "published"
+}
+```
+
+When not yet published, `status` is `"unpublished"` and `url`, `publicationId`, `publishedAt`, `articlesCount`, `foldersCount` are all `null`.
+
+## Machine-readable output (`--json`)
+
+Every command that returns data supports `--json`. Output is newline-terminated JSON suitable for piping into `jq` or consuming from scripts and AI agents:
+
+```bash
+hinto articles list --json | jq '.articles[] | .title'
+hinto project get --json | jq '.project.id'
+hinto publish status --json | jq '.status'
+hinto templates list --json | jq '[.templates[] | select(.requires_video) | .id]'
+```
+
+When an error occurs with `--json`, stdout is always empty and the error message goes to stderr — so it is safe to parse stdout without guarding for error objects.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | Error (invalid API key, not found, network error, etc.) |
+
+## Async jobs (`--wait`)
+
+Commands that start background jobs — `generate start`, `publish now`, `publish republish`, `project retranslate` — default to fire-and-forget: they print the job metadata and return exit 0 immediately. Pass `--wait` to poll until the job completes (or fails) and print its output.
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `HINTO_API_KEY` | Override the API key stored in `~/.hinto/config.json` |
+
+## Development
+
+### Setup
+
+```bash
+git clone <repo-url>
+cd hinto-cli
+npm install
+npm run build      # compile TypeScript → dist/
+npm test           # run unit tests (nock-based, no network required)
+```
+
+### Running locally without installing globally
+
+Use `node dist/index.js` directly — no `npm link` or global install needed:
+
+```bash
+npm run build
+node dist/index.js --api-url http://localhost:3000 project get
+```
+
+Or set a shell alias for the session:
+
+```bash
+alias hinto="node $(pwd)/dist/index.js"
+hinto --api-url http://localhost:3000 videos list
+```
+
+Set `HINTO_API_KEY` in your environment to avoid passing the key on every command:
+
+```bash
+export HINTO_API_KEY=hinto_...
+```
+
+### Testing against a local server
+
+Point the CLI at the Next.js dev server running on port 3000 (or the e2e port 3099):
+
+```bash
+node dist/index.js --api-url http://localhost:3000 videos list --json
+```
+
+Grab an API key from the local Supabase DB or from the e2e test setup.
+
+### Skill development
+
+The Claude Code skill lives in `skills/hinto-cli/`. After editing any file there, copy it to Claude's global skills directory so it takes effect immediately:
+
+```bash
+cp -r skills/hinto-cli/. ~/.claude/skills/hinto-cli/
+```
+
+**Rule:** whenever you change a CLI flag or command behaviour, update **both**:
+1. The relevant `skills/hinto-cli/references/*.md` file
+2. The usage examples in this `README.md`
+
+Then copy and commit together so the repo and the local skill stay in sync.

package/dist/api/articles.d.ts

@@ -0,0 +1,101 @@
+import type { AxiosInstance } from 'axios';
+export interface Article {
+    id: number;
+    title: string;
+    slug: string | null;
+    folderId: number | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ArticleDetail {
+    id: number;
+    title: string;
+    slug: string | null;
+    folderId: number | null;
+    format: string;
+    content: string;
+    createdAt: string | null;
+    updatedAt: string | null;
+    metadata: {
+        metaDescription: string | null;
+        metaKeywords: string[] | null;
+        jsonLd: string | null;
+    };
+}
+export interface ArticleVersion {
+    id: string;
+    versionNumber: number;
+    createdAt: string;
+    createdBy: string;
+    changeDescription: string | null;
+    isAutoSave: boolean;
+}
+export interface ArticleTranslation {
+    languageCode: string;
+    status: string;
+    title: string | null;
+    slug: string | null;
+    metaDescription: string | null;
+    metaKeywords: string[] | null;
+    hasContent: boolean;
+    updatedAt: string;
+}
+export declare const articlesApi: (client: AxiosInstance) => {
+    list: (params?: {
+        folderId?: string;
+        offset?: number;
+        limit?: number;
+    }) => Promise<{
+        articles: Article[];
+        pagination: {
+            limit: number;
+            offset: number;
+            count: number;
+        };
+    }>;
+    get: (id: string, format?: "markdown" | "html") => Promise<ArticleDetail>;
+    create: (body: {
+        title: string;
+        content?: string;
+        folderId?: string;
+    }) => Promise<ArticleDetail>;
+    update: (id: string, body: {
+        title?: string;
+        slug?: string;
+        metaDescription?: string;
+        metaKeywords?: string[];
+    }) => Promise<ArticleDetail>;
+    delete: (id: string) => Promise<any>;
+    duplicate: (id: string) => Promise<ArticleDetail>;
+    move: (id: string, folderId: string | null) => Promise<ArticleDetail>;
+    regenerate: (id: string, callbackUrl?: string, callbackSecret?: string) => Promise<import("./generate").Job>;
+    createEmpty: (body: {
+        title?: string;
+        folderId?: number;
+    }) => Promise<ArticleDetail>;
+    listVersions: (id: string) => Promise<{
+        versions: ArticleVersion[];
+    }>;
+    restoreVersion: (id: string, versionId: string) => Promise<{
+        message: string;
+        articleId: number;
+        versionId: string;
+    }>;
+    listTranslations: (id: string) => Promise<{
+        translations: ArticleTranslation[];
+    }>;
+    getTranslation: (id: string, lang: string, format?: "markdown" | "html") => Promise<{
+        languageCode: string;
+        status: string;
+        title: string | null;
+        slug: string | null;
+        format: string;
+        content: string | null;
+        metadata: {
+            metaDescription: string | null;
+            metaKeywords: string[] | null;
+            updatedAt: string | null;
+        };
+    }>;
+    triggerTranslate: (id: string, lang: string, callbackUrl?: string, callbackSecret?: string) => Promise<import("./generate").Job>;
+};

package/dist/api/articles.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.articlesApi = void 0;
+const articlesApi = (client) => ({
+    list: (params) => client
+        .get('/articles', { params })
+        .then((r) => r.data),
+    get: (id, format) => client
+        .get(`/articles/${id}`, { params: format ? { format } : undefined })
+        .then((r) => r.data),
+    create: (body) => client.post('/articles', body).then((r) => r.data),
+    update: (id, body) => client.put(`/articles/${id}`, body).then((r) => r.data),
+    delete: (id) => client.delete(`/articles/${id}`).then((r) => r.data),
+    duplicate: (id) => client.post(`/articles/${id}/duplicate`).then((r) => r.data),
+    move: (id, folderId) => client.patch(`/articles/${id}/move`, { folderId }).then((r) => r.data),
+    regenerate: (id, callbackUrl, callbackSecret) => client
+        .post(`/articles/${id}/regenerate`, {
+        ...(callbackUrl ? { callbackUrl } : {}),
+        ...(callbackSecret ? { callbackSecret } : {}),
+    })
+        .then((r) => r.data),
+    createEmpty: (body) => client.post('/articles/empty', body).then((r) => r.data),
+    listVersions: (id) => client.get(`/articles/${id}/versions`).then((r) => r.data),
+    restoreVersion: (id, versionId) => client
+        .post(`/articles/${id}/versions/${versionId}/restore`)
+        .then((r) => r.data),
+    listTranslations: (id) => client
+        .get(`/articles/${id}/translations`)
+        .then((r) => r.data),
+    getTranslation: (id, lang, format) => client
+        .get(`/articles/${id}/translations/${lang}`, { params: format ? { format } : undefined })
+        .then((r) => r.data),
+    triggerTranslate: (id, lang, callbackUrl, callbackSecret) => client
+        .post(`/articles/${id}/translations/${lang}`, {
+        ...(callbackUrl ? { callbackUrl } : {}),
+        ...(callbackSecret ? { callbackSecret } : {}),
+    })
+        .then((r) => r.data),
+});
+exports.articlesApi = articlesApi;

package/dist/api/client.d.ts

@@ -0,0 +1,2 @@
+import { type AxiosInstance } from 'axios';
+export declare function createClient(apiKey: string, baseUrl: string): AxiosInstance;

package/dist/api/client.js

@@ -0,0 +1,48 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createClient = createClient;
+const axios_1 = __importDefault(require("axios"));
+const errors_1 = require("../errors");
+function createClient(apiKey, baseUrl) {
+    const instance = axios_1.default.create({
+        baseURL: `${baseUrl}/api/external/v2`,
+        headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
+        timeout: 30000,
+    });
+    instance.interceptors.response.use((res) => res, (err) => {
+        const apiError = err.response?.data?.error;
+        if (apiError) {
+            if (apiError.code === 'UNAUTHORIZED') {
+                throw new errors_1.CliError('UNAUTHORIZED', 'Invalid API key. Run `hinto init --key <your-api-key>` to authenticate.');
+            }
+            throw new errors_1.CliError(apiError.code, apiError.message);
+        }
+        if (!apiError && err.response?.data) {
+            try {
+                const raw = typeof err.response.data === 'string'
+                    ? err.response.data
+                    : Buffer.from(err.response.data).toString('utf-8');
+                const parsed = JSON.parse(raw);
+                if (parsed?.error) {
+                    if (parsed.error.code === 'UNAUTHORIZED') {
+                        throw new errors_1.CliError('UNAUTHORIZED', 'Invalid API key. Run `hinto init --key <your-api-key>` to authenticate.');
+                    }
+                    throw new errors_1.CliError(parsed.error.code, parsed.error.message ?? 'Unknown error');
+                }
+            }
+            catch (parseErr) {
+                if (parseErr instanceof errors_1.CliError)
+                    throw parseErr;
+                // ignore parse failures — fall through to generic message
+            }
+        }
+        if (err.code === 'ECONNREFUSED' || err.code === 'ENOTFOUND') {
+            throw new errors_1.CliError('NETWORK_ERROR', 'Could not reach Hinto API — check your connection');
+        }
+        throw new errors_1.CliError('UNKNOWN_ERROR', err.message ?? 'An unexpected error occurred');
+    });
+    return instance;
+}

package/dist/api/export.d.ts

@@ -0,0 +1,6 @@
+import type { AxiosInstance } from 'axios';
+export declare const exportApi: (client: AxiosInstance) => {
+    article: (id: string, format?: "markdown" | "html" | "pdf", lang?: string) => Promise<string | Buffer>;
+    folder: (id: string) => Promise<Buffer<ArrayBufferLike>>;
+    project: (format?: "markdown" | "html" | "pdf" | "llm-text") => Promise<Buffer<ArrayBufferLike>>;
+};

package/dist/api/export.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exportApi = void 0;
+const exportApi = (client) => ({
+    article: (id, format, lang) => {
+        const isPdf = format === 'pdf';
+        return client
+            .get(`/export/articles/${id}`, {
+            params: { ...(format ? { format } : {}), ...(lang ? { lang } : {}) },
+            responseType: isPdf ? 'arraybuffer' : 'text',
+        })
+            .then((r) => (isPdf ? Buffer.from(r.data) : r.data));
+    },
+    folder: (id) => client
+        .get(`/export/folders/${id}`, { responseType: 'arraybuffer' })
+        .then((r) => r.data),
+    project: (format) => client
+        .get('/export/project', {
+        params: format ? { format } : undefined,
+        responseType: 'arraybuffer',
+    })
+        .then((r) => r.data),
+});
+exports.exportApi = exportApi;

package/dist/api/folders.d.ts

@@ -0,0 +1,18 @@
+import type { AxiosInstance } from 'axios';
+export interface Folder {
+    id: number;
+    name: string;
+    parentId: number | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare const foldersApi: (client: AxiosInstance) => {
+    list: () => Promise<{
+        folders: Folder[];
+    }>;
+    get: (id: string) => Promise<Folder>;
+    create: (name: string, parentId?: string) => Promise<Folder>;
+    update: (id: string, name: string) => Promise<Folder>;
+    delete: (id: string) => Promise<any>;
+    move: (id: string, parentId: string | null) => Promise<Folder>;
+};