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
28 changes: 28 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,11 @@ pixelvault keys list
KEY=$(pixelvault keys create --label ci) # raw key on stdout, shown once
pixelvault keys revoke key_abc123

# Attach a custom domain to the active project
pixelvault domains add media.example.com
pixelvault domains refresh dom_abc123
pixelvault upload photo.jpg --branded

# Export everything — manifest plus all project media and derived artifacts (no lock-in)
pixelvault export -o pixelvault-export.tar
```
Expand All @@ -103,6 +108,7 @@ pixelvault export -o pixelvault-export.tar
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
- Media JSON keeps the canonical `url` and includes optional `branded_url` when the active project has a ready custom domain. Add `--branded` to `upload`, `list`, `get`, or `audio upload|list|get|update|sign` to print it, with canonical fallback
- `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
Expand Down Expand Up @@ -154,6 +160,7 @@ npx pixelvault-cli upload build-output.png
| `export` | Export all project media and derived artifacts with a manifest |
| `usage` | Show plan, period, storage/upload/bandwidth usage and limits, and AI generation credits |
| `keys list\|create\|revoke` | List, create, and revoke the project's secret API keys |
| `domains list\|add\|refresh\|delete` | Manage the active project's custom domain and inspect account plan capacity |
| `upgrade <starter\|pro>` | Print a Stripe Checkout URL to subscribe (live key; you pay in the browser) |
| `billing` | Print a Stripe billing-portal URL to change plan, update payment details or cancel (live key) |
| `whoami` | Show current auth state |
Expand All @@ -165,6 +172,7 @@ npx pixelvault-cli upload build-output.png
pixelvault upload photo.jpg # Single file
pixelvault upload *.png --folder icons # Bulk with folder
pixelvault upload shot.png --json # Full JSON response
pixelvault upload shot.png --branded # Ready custom-domain URL; canonical fallback
pixelvault upload demo.mp4 --social # Upload + wait; prints the post-ready URL
pixelvault upload demo.mp4 --social --json # Includes original_url and social_ready_url
pixelvault upload "https://media.example.com/demo.mp4" --private --expires 12h --social --json
Expand Down Expand Up @@ -244,6 +252,7 @@ pixelvault audio enrich private.ogg --private --link-expires 12h --delete-after
pixelvault audio enrich aud_xyz --no-wait --json
pixelvault audio enrich aud_xyz --timeout 1200 --json
pixelvault audio list --folder podcasts --json
pixelvault audio get aud_xyz --branded
pixelvault audio get aud_xyz --json
pixelvault audio update aud_xyz --folder archive --meta episode=7 --json
pixelvault audio sign aud_xyz --expires 1h --json
Expand Down Expand Up @@ -349,6 +358,7 @@ progress to **stderr**.

```bash
pixelvault list # One URL per line
pixelvault list --branded # Ready custom-domain URLs; canonical fallback
pixelvault list --json # Full JSON with metadata
pixelvault list --page 2 --per-page 50 # Pagination
pixelvault list --meta env=prod # Only images tagged env=prod (repeatable; all must match)
Expand Down Expand Up @@ -417,6 +427,24 @@ pixelvault keys revoke key_abc123
`PIXELVAULT_API_KEY` to `$NEW`, then `pixelvault keys revoke <old-id>` using
the new key. If you get locked out, use the dashboard's Regenerate.

### Custom Domains

Custom domains attach to the active project; plan capacity is account-wide
(Starter 1, Pro 3). A verified email and live secret key are required.

```bash
pixelvault domains list
pixelvault domains add media.example.com
# Add the returned CNAME and optional TXT record, then:
pixelvault domains refresh dom_abc123
pixelvault domains delete dom_abc123
```

The hostname is ready only when both hostname and certificate status are active.
Once ready, API JSON includes `branded_url` while preserving canonical `url`.
`--branded` selects that API-provided URL and never reconstructs a signed link.
Deleting the domain does not invalidate canonical PixelVault URLs.

### Upgrade and billing

Both need a **live** secret key (`pv_live_...`); test and publishable keys get a 403. They print a Stripe URL for **you** to open — nothing is charged by the command, and the plan changes only after Stripe confirms payment.
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.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "pixelvault-cli",
"version": "0.25.0",
"version": "0.26.0",
"description": "CLI for PixelVault — agent-first media hosting for images, PDFs, video, and audio",
"type": "module",
"bin": {
Expand Down
17 changes: 11 additions & 6 deletions src/commands/audio.ts
Original file line number Diff line number Diff line change
Expand Up @@ -168,6 +168,7 @@ const upload = defineCommand({
args: {
source: { type: "positional", description: "MP3, WAV, M4A, or OGG path or public HTTP(S) URL", required: true },
...lifecycleOptions,
branded: { type: "boolean", description: "Print the active custom-domain URL when available", default: false },
},
async run({ args }) {
const audio = await uploadAudioSource(
Expand All @@ -178,7 +179,7 @@ const upload = defineCommand({

if (args.json) jsonOut(audio);
else {
stdout(audio.url);
stdout(args.branded ? (audio.branded_url ?? audio.url) : audio.url);
stderr(`${audio.replayed ? "Replayed" : "Hosted"} ${audio.id}: ${audio.codec}, ${audio.duration_seconds}s, ${audio.visibility}.`);
}
},
Expand All @@ -195,6 +196,7 @@ const list = defineCommand({
meta: { type: "string", description: "Filter metadata key=value (repeatable)" },
metadata: { type: "string", description: "Filter by metadata JSON containment" },
json: { type: "boolean", description: "Output complete JSON", default: false },
branded: { type: "boolean", description: "Print active custom-domain URLs when available", default: false },
},
async run({ args }) {
const params = new URLSearchParams({ page: args.page, per_page: args["per-page"] });
Expand All @@ -207,7 +209,7 @@ const list = defineCommand({
auth: requireApiKey(),
});
if (args.json) jsonOut(response);
else for (const audio of response.data) stdout(audio.url);
else for (const audio of response.data) stdout(args.branded ? (audio.branded_url ?? audio.url) : audio.url);
},
});

Expand All @@ -216,14 +218,15 @@ const get = defineCommand({
args: {
id: { type: "positional", description: "Stable aud_ asset ID", required: true },
json: { type: "boolean", description: "Output complete JSON", default: false },
branded: { type: "boolean", description: "Print the active custom-domain URL when available", default: false },
},
async run({ args }) {
const response = await apiRequest<DataResponse<AudioAsset>>({
path: `${AUDIO_PATH}/${encodeURIComponent(args.id)}`,
auth: requireApiKey(),
});
if (args.json) jsonOut(response.data);
else stdout(response.data.url);
else stdout(args.branded ? (response.data.branded_url ?? response.data.url) : response.data.url);
},
});

Expand All @@ -239,6 +242,7 @@ const update = defineCommand({
metadata: { type: "string", description: "Replacement metadata JSON object" },
"clear-metadata": { type: "boolean", description: "Replace metadata with an empty object", default: false },
json: { type: "boolean", description: "Output complete JSON", default: false },
branded: { type: "boolean", description: "Print the active custom-domain URL when available", default: false },
},
async run({ args }) {
if (args.folder && args["clear-folder"]) throw new CliError("Use --folder or --clear-folder, not both.");
Expand All @@ -264,7 +268,7 @@ const update = defineCommand({
body,
});
if (args.json) jsonOut(response.data);
else stdout(response.data.url);
else stdout(args.branded ? (response.data.branded_url ?? response.data.url) : response.data.url);
},
});

Expand All @@ -274,16 +278,17 @@ const sign = defineCommand({
id: { type: "positional", description: "Stable aud_ asset ID", required: true },
expires: { type: "string", description: "Signed-link lifetime, e.g. 1h or 7d", default: "1h" },
json: { type: "boolean", description: "Output complete JSON", default: false },
branded: { type: "boolean", description: "Print the active custom-domain signed URL when available", default: false },
},
async run({ args }) {
const response = await apiRequest<DataResponse<{ url: string; expires: number; visibility: string }>>({
const response = await apiRequest<DataResponse<{ url: string; branded_url?: string; expires: number; visibility: string }>>({
method: "POST",
path: `${AUDIO_PATH}/${encodeURIComponent(args.id)}/sign-url`,
auth: requireApiKey(),
body: { expires_in: parseExpires(args.expires) },
});
if (args.json) jsonOut(response.data);
else stdout(response.data.url);
else stdout(args.branded ? (response.data.branded_url ?? response.data.url) : response.data.url);
},
});

Expand Down
162 changes: 162 additions & 0 deletions src/commands/domains.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,162 @@
import { defineCommand } from "citty";
import { apiRequest, ApiRequestError } from "../lib/client.js";
import { requireApiKey } from "../lib/config.js";
import { CliError } from "../lib/errors.js";
import { jsonOut, stderr, stdout } from "../lib/output.js";

export interface CustomDomain {
id: string;
project_id: string;
hostname: string;
status: string;
hostname_status: string;
certificate_status: string;
ready: boolean;
cname_target: string;
ownership_verification: { type: "TXT"; name: string; value: string } | null;
created_at: string;
updated_at: string;
}

type DomainListResponse = {
data: CustomDomain[];
meta: { limit: number; total: number; project_total: number; cname_target: string };
};

function explainDomainError(error: unknown): never {
if (error instanceof ApiRequestError) {
switch (error.code) {
case "custom_domains_require_paid_plan":
throw new CliError(
"Custom domains require a Starter or Pro plan. Run `pixelvault upgrade starter` to get a checkout URL.",
1,
);
case "custom_domain_limit_reached":
throw new CliError(`${error.message} Remove an unused hostname with \`pixelvault domains delete <id>\`.`, 1);
case "custom_domain_exists":
case "custom_domain_conflict":
throw new CliError(`${error.message} List configured hostnames with \`pixelvault domains list\`.`, 1);
case "email_verification_required":
throw new CliError("Verify the account email before adding a custom domain.", 1);
case "custom_domain_not_found":
throw new CliError("Custom domain not found. Run `pixelvault domains list` to get its id.", 1);
case "custom_domains_unavailable":
case "custom_domain_provisioning_failed":
throw new CliError(`Custom-domain provisioning is unavailable: ${error.message}`, 1);
case "validation_error":
throw new CliError(`Invalid hostname: ${error.message}`, 1);
}
}
throw error;
}

function printDomain(domain: CustomDomain): void {
stdout([
domain.id,
domain.ready ? "active" : domain.status,
domain.hostname,
`CNAME ${domain.cname_target}`,
].join(" "));
if (domain.ownership_verification) {
stderr(
`Add ${domain.ownership_verification.type} ${domain.ownership_verification.name} = ${domain.ownership_verification.value}`,
);
}
}

const list = defineCommand({
meta: { name: "list", description: "List custom domains for the active project" },
args: { json: { type: "boolean", description: "Output as JSON", default: false } },
async run({ args }) {
let response: DomainListResponse;
try {
response = await apiRequest<DomainListResponse>({
path: "/v1/custom-domains",
auth: requireApiKey(),
});
} catch (error) {
explainDomainError(error);
}
if (args.json) {
jsonOut(response);
return;
}
stderr(`${response.meta.total}/${response.meta.limit} account custom domains used; ${response.meta.project_total} on this project.`);
for (const domain of response.data) printDomain(domain);
},
});

const add = defineCommand({
meta: { name: "add", description: "Attach a hostname to the active project" },
args: {
hostname: { type: "positional", description: "Customer hostname, e.g. media.example.com", required: true },
json: { type: "boolean", description: "Output as JSON", default: false },
},
async run({ args }) {
let response: { data: CustomDomain; meta: { limit: number } };
try {
response = await apiRequest({
method: "POST",
path: "/v1/custom-domains",
auth: requireApiKey(),
body: { hostname: args.hostname },
});
} catch (error) {
explainDomainError(error);
}
if (args.json) jsonOut(response);
else {
printDomain(response.data);
stderr(`Point ${response.data.hostname} to ${response.data.cname_target}, then run pixelvault domains refresh ${response.data.id}.`);
}
},
});

const refresh = defineCommand({
meta: { name: "refresh", description: "Refresh DNS and certificate status" },
args: {
id: { type: "positional", description: "Custom-domain id", required: true },
json: { type: "boolean", description: "Output as JSON", default: false },
},
async run({ args }) {
let response: { data: CustomDomain };
try {
response = await apiRequest({
method: "POST",
path: `/v1/custom-domains/${encodeURIComponent(args.id)}/refresh`,
auth: requireApiKey(),
});
} catch (error) {
explainDomainError(error);
}
if (args.json) jsonOut(response.data);
else printDomain(response.data);
},
});

const remove = defineCommand({
meta: { name: "delete", description: "Remove a custom domain" },
args: {
id: { type: "positional", description: "Custom-domain id", required: true },
json: { type: "boolean", description: "Output as JSON", default: false },
},
async run({ args }) {
let response: { data: { deleted: boolean; id: string } };
try {
response = await apiRequest({
method: "DELETE",
path: `/v1/custom-domains/${encodeURIComponent(args.id)}`,
auth: requireApiKey(),
});
} catch (error) {
explainDomainError(error);
}
if (args.json) jsonOut(response.data);
else stderr(`Deleted custom domain ${response.data.id}.`);
},
});

export default defineCommand({
meta: { name: "domains", description: "Manage project custom domains" },
subCommands: { list, add, refresh, delete: remove },
});
9 changes: 8 additions & 1 deletion src/commands/get.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ interface GetResponse {
data: {
id: string;
url: string;
branded_url?: string;
mime_type: string;
size: number;
filename: string;
Expand Down Expand Up @@ -60,6 +61,11 @@ export default defineCommand({
'Transform params to apply, e.g. "w=400&fmt=webp", "segment=foreground", "tile=img_logo.png"',
alias: "t",
},
branded: {
type: "boolean",
description: "Use the active custom-domain URL when available",
default: false,
},
json: {
type: "boolean",
description: "Output full JSON metadata",
Expand All @@ -74,7 +80,8 @@ export default defineCommand({
auth: apiKey,
});

const url = applyTransform(res.data.url, args.transform as string | undefined);
const baseUrl = args.branded ? (res.data.branded_url ?? res.data.url) : res.data.url;
const url = applyTransform(baseUrl, args.transform as string | undefined);

// Download mode: fetch the (possibly transformed) bytes to disk.
if (args.output) {
Expand Down
Loading
Loading