Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 41 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
[![npm](https://img.shields.io/npm/v/pixelvault-cli)](https://www.npmjs.com/package/pixelvault-cli)
[![CI](https://github.com/pixelvault-dev/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/pixelvault-dev/cli/actions/workflows/ci.yml)

CLI for [PixelVault](https://pixelvault.dev) — agent-first image, PDF, and video hosting for developers and AI coding agents.
CLI for [PixelVault](https://pixelvault.dev) — agent-first media hosting for developers and AI coding agents.

## Install

Expand Down Expand Up @@ -54,6 +54,12 @@ pixelvault upload demo.mp4 --social
# Convert an existing hosted video
pixelvault optimize-video vid_xyz

# Upload a local MP4, enrich it, wait, and print original/transcript/storyboard URLs
pixelvault enrich-video demo.mp4

# Resume the same server job without uploading again
pixelvault enrich-video vid_xyz

# List your images
pixelvault list

Expand Down Expand Up @@ -84,6 +90,7 @@ The CLI is designed for AI coding agents. Output contract:
- `upload` prints **only the URL** to stdout for images, PDFs, and MP4 videos. PDFs are served as forced downloads and do not support image transforms. Add `--optimized` for the smaller WebP/AVIF image variant; it falls back to the original URL for SVG, GIF, PDF, and private images
- `upload` streams local MP4 files and automatically switches to multipart upload above 100 MB. It also accepts public MP4 URLs and has PixelVault import them directly. `--private [--expires 12h]` returns signed video and poster URLs. `--social` requests a separate H.264/AAC fast-start copy, waits for it, and prints the post-ready URL while preserving the original; `--json` returns both `original_url` and `social_ready_url`. Every video response includes duration, dimensions, codecs, fast-start status, and social-compatibility warnings. Video limits: Free 25 MB, Starter 100 MB, Pro 250 MB
- `optimize-video` converts an existing upload, waits for the derived social-ready URL, and prints only that URL; `--no-wait` enqueues and returns, while `--json` returns the full state
- `enrich-video` uploads a local MP4 or reuses an existing `vid_` asset, starts or resumes transcript + storyboard enrichment, and reports the stable asset/job IDs before bounded polling
- Image and PDF uploads support `--idempotency-key` and `--dedupe`; folder, image optimization, reuse, metadata, and AI-description options are rejected for MP4 files and URLs
- `list` outputs one URL per line
- `meta` prints the stored metadata as JSON
Expand Down Expand Up @@ -119,6 +126,7 @@ npx pixelvault-cli upload build-output.png
| `describe <id>` | Write an AI description (alt text, caption, OCR, tags) for an image you already uploaded |
| `optimize <files...>` | Compress images locally — no account needed (resize, convert, strip metadata; never writes a bigger file) |
| `optimize-video <id>` | Preserve a hosted MP4 and create a social-ready H.264/AAC fast-start copy |
| `enrich-video <file.mp4\|vid_id>` | Upload or resume transcript + storyboard enrichment, with bounded polling and structured artifact access data |
| `get <id>` | Get an image's URL/metadata, or download it (optionally transformed) |
| `meta <id>` | Replace an image's custom metadata (`--meta k=v`, `--metadata '<json>'`, or `--clear`) |
| `delete <id>` | Delete an image |
Expand Down Expand Up @@ -174,6 +182,37 @@ an already-compatible original is returned unchanged, a running job is reused,
and a completed derivative is returned without another conversion. Failed jobs
refund their reserved seconds.

### Video Enrichment Options

```bash
pixelvault enrich-video demo.mp4 # upload + enrich + wait
pixelvault enrich-video demo.mp4 --private # private original and signed artifacts
pixelvault enrich-video demo.mp4 --no-wait --json
pixelvault enrich-video vid_xyz # resume/reuse an existing job
pixelvault enrich-video vid_xyz --timeout 1200 --json
```

The command accepts a local MP4 or an existing PixelVault video asset ID. URL
sources are intentionally rejected: import one with `pixelvault upload <url>
--json`, then pass the returned `vid_` ID. Enrichment accepts sources from 1
second through 10 minutes and at most 100 MB. It is idempotent while queued,
running, or complete; retrying a failed job creates a new job ID.

Polling backs off from one to ten seconds and stops after 600 seconds by default
(`--timeout` changes the local bound). A timeout exits non-zero but does not
cancel the server job; rerun the printed resume command. `--no-wait` returns the
queued/running state immediately. Human output keeps URLs on stdout and progress,
asset/job IDs, artifact types, visibility, and signed-link expiry on stderr.
`--json` returns one object with `asset_id`, `job_id`, explicit state,
`resume_command`, and only the artifact URLs that currently exist. Private
artifacts inherit the video's privacy; the command never changes an existing
asset's visibility.

Videos without audio return a skipped transcript and still produce a storyboard.
Quota, duration, size, unavailable-metadata, failed-job, and local-timeout states
exit explicitly. Monthly source minutes are Free 2, Starter 30, and Pro 120;
check `pixelvault usage` for the current allowance and reset.

### Generate Options

```bash
Expand Down Expand Up @@ -352,7 +391,7 @@ pixelvault config get api_key # Get a value

## Learn more

- [PixelVault](https://pixelvault.dev) — agent-first image hosting
- [PixelVault](https://pixelvault.dev) — agent-first media hosting
- [API docs](https://pixelvault.dev/docs/) — full REST reference + OpenAPI 3.1
- [Guide: Image hosting for AI agents](https://pixelvault.dev/blog/image-hosting-for-ai-agents/)
- [The simplest image hosting API](https://pixelvault.dev/image-hosting-api/)
Expand Down
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "pixelvault-cli",
"version": "0.22.0",
"description": "CLI for PixelVault — agent-first image, PDF, and video hosting",
"version": "0.23.0",
"description": "CLI for PixelVault — agent-first media hosting for images, PDFs, and video",
"type": "module",
"bin": {
"pixelvault": "bin/pixelvault.mjs"
Expand Down
226 changes: 226 additions & 0 deletions src/commands/enrich-video.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,226 @@
import { existsSync } from "node:fs";
import { extname } from "node:path";
import { defineCommand } from "citty";
import { ApiRequestError, apiRequest } from "../lib/client.js";
import { requireApiKey } from "../lib/config.js";
import { parseExpires } from "../lib/duration.js";
import { CliError } from "../lib/errors.js";
import {
enrichmentState,
videoArtifacts,
waitForVideoEnrichment,
type VideoArtifact,
} from "../lib/video-enrichment.js";
import { jsonOut, stderr, stdout } from "../lib/output.js";
import {
isRemoteVideoUrl,
uploadVideoFile,
type VideoData,
type VideoEnrichmentStatus,
} from "../lib/video-upload.js";

const DEFAULT_TIMEOUT_SECONDS = 600;

function isVideoId(value: string): boolean {
return /^vid_[A-Za-z0-9_-]+$/.test(value);
}

function timeoutMilliseconds(value: unknown): number {
const seconds = Number(value ?? DEFAULT_TIMEOUT_SECONDS);
if (!Number.isFinite(seconds) || seconds <= 0) {
throw new CliError("--timeout must be a positive number of seconds.");
}
return Math.ceil(seconds * 1_000);
}

function startError(error: unknown, assetId: string): CliError {
const resume = `Re-run pixelvault enrich-video ${assetId}; active or completed jobs are reused.`;
if (!(error instanceof ApiRequestError)) {
const message = error instanceof Error ? error.message : String(error);
return new CliError(`${message} The uploaded asset is preserved. ${resume}`);
}

switch (error.code) {
case "enrichment_limit_reached":
return new CliError(`${error.message} Check pixelvault usage for the reset date or plan allowance.`);
case "enrichment_source_too_large":
return new CliError(`${error.message} The original video remains hosted as ${assetId}.`);
case "enrichment_duration_too_long":
case "video_duration_unavailable":
return new CliError(`${error.message} Enrichment supports MP4 sources from 1 second through 10 minutes.`);
case "video_metadata_unavailable":
return new CliError(`${error.message} The original video remains hosted as ${assetId}.`);
default:
return new CliError(`${error.message} The uploaded asset is preserved. ${resume}`);
}
}

function accessLabel(artifact: VideoArtifact): string {
if (artifact.signed_url_expiry.status === "known") {
return `private; signed URL expires ${artifact.signed_url_expiry.expires_at}`;
}
if (artifact.signed_url_expiry.status === "unknown") {
return "private; signed URL expiry was not reported";
}
return "public; no signed-URL expiry";
}

function printReadable(artifacts: VideoArtifact[]): void {
for (const artifact of artifacts) {
const sheet = artifact.sheet_index === undefined ? "" : `[${artifact.sheet_index}]`;
stderr(`${artifact.type}${sheet} (${accessLabel(artifact)}): ${artifact.url}`);
stdout(artifact.url);
}
}

function statusLabel(status: VideoEnrichmentStatus): string {
if (status === "pending") return "queued";
if (status === "processing") return "running";
return status;
}

export default defineCommand({
meta: {
name: "enrich-video",
description: "Upload or resume an MP4 transcript + storyboard job",
},
args: {
source: {
type: "positional",
description: "Local .mp4 path or existing PixelVault video ID (vid_...)",
required: true,
},
private: {
type: "boolean",
description: "Upload a local MP4 privately; generated artifacts inherit privacy",
default: false,
},
expires: {
type: "string",
description: "Signed-link lifetime for a new private upload (for example 12h or 7d)",
},
wait: {
type: "boolean",
description: "Wait for a terminal enrichment state",
default: true,
},
timeout: {
type: "string",
description: `Maximum seconds to wait locally (default: ${DEFAULT_TIMEOUT_SECONDS})`,
default: String(DEFAULT_TIMEOUT_SECONDS),
},
json: {
type: "boolean",
description: "Output structured asset, job, state, access, and artifact data as JSON",
default: false,
},
},
async run({ args }) {
const apiKey = requireApiKey();
const source = String(args.source);
const existingAsset = isVideoId(source);

if (isRemoteVideoUrl(source)) {
throw new CliError(
"enrich-video accepts a local MP4 or an existing vid_ asset ID, not a URL. "
+ "Import it first with pixelvault upload <url> --json, then pass the returned video ID.",
);
}
if (!existingAsset && extname(source).toLowerCase() !== ".mp4") {
throw new CliError("enrich-video accepts only a local .mp4 path or an existing vid_ asset ID.");
}
if (!existingAsset && !existsSync(source)) {
throw new CliError(`Video file not found: ${source}`);
}
if (existingAsset && (args.private || args.expires !== undefined)) {
throw new CliError(
"--private and --expires apply only when enrich-video uploads a local MP4. "
+ "An existing asset keeps its current visibility.",
);
}
if (args.expires !== undefined && !args.private) {
throw new CliError("--expires requires --private and controls signed-link expiry, not asset deletion.");
}

const timeoutMs = timeoutMilliseconds(args.timeout);
const signExpiresIn = args.private ? parseExpires(String(args.expires ?? "7d")) : null;
let assetId = source;

if (!existingAsset) {
const uploaded = await uploadVideoFile(source, apiKey, {
private: Boolean(args.private),
signExpiresIn,
});
if (args.private && uploaded.visibility !== "private") {
throw new CliError("The API did not confirm private visibility; refusing to continue.");
}
assetId = uploaded.id;
stderr(`Uploaded video asset ${assetId}. Original: ${uploaded.original_url}`);
} else {
stderr(`Using existing video asset ${assetId}.`);
}
stderr(`Resume safely with: pixelvault enrich-video ${assetId}`);

let video: VideoData;
try {
({ data: video } = await apiRequest<{ data: VideoData }>({
method: "POST",
path: `/v1/videos/${encodeURIComponent(assetId)}/enrich`,
auth: apiKey,
}));
} catch (error) {
throw startError(error, assetId);
}

const jobId = video.enrichment.job_id;
if (jobId) {
stderr(`Enrichment job ${jobId}: ${statusLabel(video.enrichment.status)}.`);
} else {
stderr(`Enrichment ${statusLabel(video.enrichment.status)}; resume with asset ID ${assetId}.`);
}

let timedOut = false;
if (args.wait && (video.enrichment.status === "pending" || video.enrichment.status === "processing")) {
const result = await waitForVideoEnrichment(video, apiKey, {
timeoutMs,
onStatus(status) {
stderr(`Enrichment ${statusLabel(status)} (${video.enrichment.job_id ?? assetId}).`);
},
});
video = result.video;
timedOut = result.timedOut;
}

const artifacts = videoArtifacts(video);
const output = {
asset_id: video.id,
...(video.enrichment.job_id ? { job_id: video.enrichment.job_id } : {}),
state: enrichmentState(video.enrichment.status, timedOut),
server_status: video.enrichment.status,
resume_command: `pixelvault enrich-video ${video.id}`,
visibility: video.visibility,
artifacts,
enrichment: video.enrichment,
};

if (args.json) jsonOut(output);
else printReadable(artifacts);

if (timedOut) {
throw new CliError(
`Timed out after ${Number(args.timeout)}s while job ${video.enrichment.job_id ?? "(ID unavailable)"} `
+ `was ${statusLabel(video.enrichment.status)}. The server job was not cancelled. `
+ `Resume with pixelvault enrich-video ${video.id}.`,
);
}
if (video.enrichment.status === "failed") {
throw new CliError(
`Enrichment job ${video.enrichment.job_id ?? "(ID unavailable)"} failed: `
+ (video.enrichment.error?.message ?? "The video could not be enriched."),
);
}
if (video.enrichment.status === "not_requested") {
throw new CliError(`The server did not start an enrichment job. Retry with pixelvault enrich-video ${video.id}.`);
}
},
});
3 changes: 2 additions & 1 deletion src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ const main = defineCommand({
meta: {
name: "pixelvault",
version: VERSION,
description: "CLI for PixelVault — agent-first image, PDF, and video hosting",
description: "CLI for PixelVault — agent-first media hosting",
},
subCommands: {
register: () => import("./commands/register.js").then((m) => m.default),
Expand All @@ -18,6 +18,7 @@ const main = defineCommand({
describe: () => import("./commands/describe.js").then((m) => m.default),
optimize: () => import("./commands/optimize.js").then((m) => m.default),
"optimize-video": () => import("./commands/optimize-video.js").then((m) => m.default),
"enrich-video": () => import("./commands/enrich-video.js").then((m) => m.default),
get: () => import("./commands/get.js").then((m) => m.default),
meta: () => import("./commands/meta.js").then((m) => m.default),
delete: () => import("./commands/delete.js").then((m) => m.default),
Expand Down
2 changes: 1 addition & 1 deletion src/lib/client.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ interface ApiError {
// this channel (server reads X-PixelVault-Client at register/device-login — see
// pixelvault docs/specs/lead-attribution.md). Keep the version in sync with
// package.json on release (tests/lib/version.test.ts fails if they drift).
export const VERSION = "0.22.0";
export const VERSION = "0.23.0";
const CLIENT_ID = `pixelvault-cli/${VERSION}`;

/** CliError carrying the API's machine-readable error details. */
Expand Down
Loading
Loading