argus-media-cli 0.1.2 → 0.4.1

package/README.md

@@ -35,6 +35,45 @@ argus-media-cli upload photo.jpg
 argus-media-cli upload hero.png --project campaign-q2 --tags hero,banner
 ```
 
+### Sync
+
+Onboard an entire folder of assets in one shot — ideal for migrating a legacy
+brand folder. `sync` walks the folder recursively, filters out junk and
+unsupported files, dedupes, uploads what's left sequentially, and prints a
+manifest of what was synced, skipped, and failed.
+
+```bash
+argus-media-cli sync ./legacy-brand-folder --dry-run          # preview the plan
+argus-media-cli sync ./legacy-brand-folder                    # upload for real
+argus-media-cli sync ./assets --project brand-2019 --tags legacy,imported
+argus-media-cli sync ./assets --json                          # structured manifest
+```
+
+**What it uploads:** JPEG, PNG, GIF, WebP, and SVG files up to 20 MB.
+
+**What it skips (with a stated reason):**
+
+- Junk files (`.DS_Store`, `Thumbs.db`, `desktop.ini`) and hidden dotfiles
+- Unsupported file types
+- Files larger than the 20 MB server cap
+- Duplicates — identical file contents (hashed), and any asset already in the
+  target project with the same filename + size
+
+**Project:** defaults to the kebab-cased folder name (e.g. `Legacy Brand
+Folder` → `legacy-brand-folder`). Override with `--project`.
+
+**Credits:** each analyzable upload costs 1 credit. If the plan exceeds your
+remaining credits, `sync` warns and asks for confirmation; pass `--yes` to skip
+the prompt (uploads past the limit are stored without AI analysis).
+
+| Flag | Description |
+|---|---|
+| `--project NAME` | Target project (default: kebab-cased folder name) |
+| `--tags a,b,c` | Tags applied to every synced asset |
+| `--dry-run` | Print the plan without uploading |
+| `--json` | Emit the manifest as structured JSON |
+| `--yes` | Skip the credit-shortfall confirmation prompt |
+
 ### Search
 
 ```bash
@@ -64,6 +103,18 @@ argus-media-cli login --key ak_xxx       # Non-interactive
 argus-media-cli login --url http://localhost:8787  # Custom API URL
 ```
 
+### API Keys
+
+Manage API keys for the current workspace. Works with either a session (from
+`login`) or an existing API key. Use this to rotate a dead or expired key:
+
+```bash
+argus-media-cli login                       # Magic-link session (no key needed)
+argus-media-cli keys list                   # List active keys
+argus-media-cli keys create --name "MCP"    # Mint a new key (shown once)
+argus-media-cli keys revoke <id>            # Revoke a key (admin only)
+```
+
 ## Options
 
 All commands support `--json` for structured JSON output.

package/dist/index.js

@@ -2,7 +2,9 @@
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { basename, extname, join } from "node:path";
 import { homedir } from "node:os";
+import { createHash } from "node:crypto";
 import * as readline from "node:readline";
+import { basicSkipReason, buildPlan, deriveProject, formatManifestText, toJsonManifest, walk, } from "./sync.js";
 // ─── Config ────────────────────────────────────────────────────────────────
 const CONFIG_DIR = join(homedir(), ".argus");
 const CONFIG_FILE = join(CONFIG_DIR, "config.json");
@@ -23,22 +25,27 @@ async function saveConfig(config) {
 function getBaseUrl(config) {
     return process.env.ARGUS_BASE_URL || config.baseUrl || "https://argus.build";
 }
-function getApiKey(config) {
-    const key = process.env.ARGUS_API_KEY || config.apiKey;
-    if (!key) {
-        console.error("Error: No API key configured.");
-        console.error("Run `argus-media-cli login` to authenticate, or set ARGUS_API_KEY.");
-        process.exit(1);
+function getAuthHeaders(config) {
+    // API key takes precedence (CI / backward compat)
+    const apiKey = process.env.ARGUS_API_KEY || config.apiKey;
+    if (apiKey) {
+        return { Authorization: `Bearer ${apiKey}` };
+    }
+    // Session-based auth (interactive login)
+    const sessionId = config.sessionId;
+    if (sessionId) {
+        return { Cookie: `session=${sessionId}` };
     }
-    return key;
+    console.error("Error: Not authenticated.");
+    console.error("Run `argus-media-cli login` to sign in, or set ARGUS_API_KEY.");
+    process.exit(1);
 }
 async function apiRequest(config, method, path, body) {
     const url = `${getBaseUrl(config)}${path}`;
-    const apiKey = getApiKey(config);
     const opts = {
         method,
         headers: {
-            Authorization: `Bearer ${apiKey}`,
+            ...getAuthHeaders(config),
             ...(body ? { "Content-Type": "application/json" } : {}),
         },
         ...(body ? { body: JSON.stringify(body) } : {}),
@@ -92,6 +99,8 @@ function formatAssetDetail(a) {
         lines.push(`  Project:  ${a.project}`);
     if (a.url)
         lines.push(`  URL:      ${a.url}`);
+    if (a.displayUrl)
+        lines.push(`  Display:  ${a.displayUrl}`);
     if (a.tags?.length)
         lines.push(`  Tags:     ${a.tags.join(", ")}`);
     if (a.uploadedBy)
@@ -118,6 +127,7 @@ function formatAssetDetail(a) {
 // ─── Commands ──────────────────────────────────────────────────────────────
 async function cmdLogin(args, flags) {
     const config = await loadConfig();
+    // Backward-compat: --key sets API key directly (useful for CI)
     if (flags.key) {
         config.apiKey = flags.key;
         await saveConfig(config);
@@ -132,25 +142,62 @@ async function cmdLogin(args, flags) {
     }
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
-    console.log("Argus CLI Login");
-    console.log("Get your API key at https://argus.build/ui\n");
-    const key = await ask("API key: ");
+    const baseUrl = getBaseUrl(config);
+    console.log("\x1b[1mArgus CLI Login\x1b[0m\n");
+    const email = (await ask("Email: ")).trim().toLowerCase();
+    if (!email) {
+        rl.close();
+        console.error("No email provided.");
+        process.exit(1);
+    }
+    // Request magic code
+    console.log("Sending login code...");
+    const magicRes = await fetch(`${baseUrl}/auth/magic`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ email }),
+    });
+    if (!magicRes.ok) {
+        rl.close();
+        const err = await magicRes.json().catch(() => ({ error: "Request failed" }));
+        console.error(`Error: ${err.error || "Could not send login code."}`);
+        process.exit(1);
+    }
+    console.log(`\nCheck your email for a 6-digit code.\n`);
+    const code = (await ask("Code: ")).trim();
     rl.close();
-    if (!key.trim()) {
-        console.error("No key provided.");
+    if (!code) {
+        console.error("No code provided.");
+        process.exit(1);
+    }
+    // Verify code and get session
+    const verifyRes = await fetch(`${baseUrl}/auth/magic/verify`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ email, code, source: "cli" }),
+    });
+    if (!verifyRes.ok) {
+        const err = await verifyRes.json().catch(() => ({ error: "Verification failed" }));
+        console.error(`Error: ${err.error || "Invalid or expired code."}`);
+        process.exit(1);
+    }
+    const data = await verifyRes.json();
+    if (!data.session) {
+        console.error("Error: No session returned from server.");
         process.exit(1);
     }
-    config.apiKey = key.trim();
+    config.sessionId = data.session;
+    delete config.apiKey; // prefer session auth
     await saveConfig(config);
-    // Verify the key works
+    console.log("\nAuthenticated! Session saved to ~/.argus/config.json");
+    // Show usage summary
     try {
         const res = await apiRequest(config, "GET", "/usage");
-        console.log(`\nAuthenticated! Workspace tier: ${res.tier}`);
+        console.log(`Workspace tier: ${res.tier}`);
         console.log(`Assets: ${res.assets?.used ?? 0}/${res.assets?.limit ?? "unlimited"}`);
     }
-    catch (e) {
-        console.error(`\nWarning: Could not verify key — ${e.message}`);
-        console.log("Key saved anyway. Check it with `argus-media-cli list`.");
+    catch {
+        // non-fatal
     }
 }
 async function cmdUpload(args, flags) {
@@ -160,7 +207,6 @@ async function cmdUpload(args, flags) {
         process.exit(1);
     }
     const config = await loadConfig();
-    const apiKey = getApiKey(config);
     const baseUrl = getBaseUrl(config);
     // Read file
     const fileData = await readFile(filePath);
@@ -177,7 +223,7 @@ async function cmdUpload(args, flags) {
         form.append("tags", flags.tags);
     const res = await fetch(`${baseUrl}/assets/upload`, {
         method: "POST",
-        headers: { Authorization: `Bearer ${apiKey}` },
+        headers: { ...getAuthHeaders(config) },
         body: form,
     });
     if (!res.ok) {
@@ -194,6 +240,8 @@ async function cmdUpload(args, flags) {
         console.log(`Status: ${asset.status}`);
         if (asset.url)
             console.log(`URL: ${asset.url}`);
+        if (asset.displayUrl)
+            console.log(`Display: ${asset.displayUrl}`);
     }
 }
 async function cmdSearch(args, flags) {
@@ -261,6 +309,439 @@ async function cmdUsage(_args, flags) {
         console.log(`  Storage:  ${data.storage?.used != null ? formatBytes(data.storage.used) : "0 B"} / ${data.storage?.limit != null ? formatBytes(data.storage.limit) : "unlimited"}`);
     }
 }
+/** Upload a single file. Returns the created asset, or a duplicate marker on 409. */
+async function uploadFile(config, filePath, fileName, project, tags) {
+    const baseUrl = getBaseUrl(config);
+    const fileData = await readFile(filePath);
+    const ext = extname(fileName).toLowerCase();
+    const mimeType = MIME_TYPES[ext] || "application/octet-stream";
+    const blob = new Blob([fileData], { type: mimeType });
+    const form = new FormData();
+    form.append("file", blob, fileName);
+    if (project)
+        form.append("project", project);
+    if (tags)
+        form.append("tags", tags);
+    const res = await fetch(`${baseUrl}/assets/upload`, {
+        method: "POST",
+        headers: { ...getAuthHeaders(config) },
+        body: form,
+    });
+    // The server enforces workspace-wide exact-content dedup and returns 409 with
+    // the pre-existing asset. Surface that as a duplicate skip, not a failure.
+    if (res.status === 409) {
+        const body = (await res.json().catch(() => ({})));
+        const existing = body?.duplicate?.asset;
+        return {
+            duplicateOf: existing?.filename
+                ? `${existing.filename} (${existing.id})`
+                : "an existing asset",
+        };
+    }
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`upload failed (${res.status}): ${text}`);
+    }
+    const data = (await res.json());
+    return { asset: data.asset };
+}
+/** Poll an asset until it reaches a terminal status (ready/error) or times out. */
+async function pollUntilReady(config, id, timeoutMs = 60_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const data = (await apiRequest(config, "GET", `/assets/${id}`));
+        const status = data.asset?.status;
+        if (status === "ready" || status === "error")
+            return status;
+        await new Promise((r) => setTimeout(r, 2000));
+    }
+    return "pending"; // timed out — still queued, not a hard failure
+}
+/** Fetch every existing asset in a project (paginated) for filename+size dedup. */
+async function fetchExistingAssets(config, project) {
+    const existing = [];
+    const pageSize = 200;
+    let offset = 0;
+    for (;;) {
+        const params = new URLSearchParams({
+            project,
+            limit: String(pageSize),
+            offset: String(offset),
+        });
+        const data = (await apiRequest(config, "GET", `/assets?${params}`));
+        const assets = data.assets ?? [];
+        for (const a of assets) {
+            if (typeof a.size === "number")
+                existing.push({ filename: a.filename, size: a.size });
+        }
+        if (assets.length < pageSize)
+            break;
+        offset += pageSize;
+    }
+    return existing;
+}
+async function confirm(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => rl.question(question, resolve));
+    rl.close();
+    return /^y(es)?$/i.test(answer.trim());
+}
+async function cmdSync(args, flags) {
+    const folder = args[0];
+    if (!folder) {
+        console.error("Usage: argus-media-cli sync <folder> [--project NAME] [--tags a,b,c] [--dry-run] [--json] [--yes]");
+        process.exit(1);
+    }
+    const config = await loadConfig();
+    const project = flags.project || deriveProject(folder);
+    const tags = flags.tags;
+    const dryRun = !!flags["dry-run"];
+    const asJson = !!flags.json;
+    const assumeYes = !!flags.yes;
+    // 1. Walk the folder.
+    let files;
+    try {
+        files = await walk(folder);
+    }
+    catch (err) {
+        throw new Error(`could not read folder '${folder}': ${err.message}`);
+    }
+    // 2. Hash the files that pass the cheap filters, so content-dedup can run.
+    const hashed = [];
+    for (const f of files) {
+        if (basicSkipReason(f)) {
+            hashed.push(f); // no hash needed — will be skipped in buildPlan
+            continue;
+        }
+        const buf = await readFile(f.path);
+        hashed.push({ ...f, hash: createHash("sha256").update(buf).digest("hex") });
+    }
+    // 3. Dedup against what's already in the target project.
+    const existing = await fetchExistingAssets(config, project);
+    const plan = buildPlan(hashed, existing);
+    const result = {
+        synced: [],
+        skipped: plan.skip.map((s) => ({ filename: s.filename, reason: s.reason })),
+        failed: [],
+    };
+    // 4. Dry run: show the plan and stop.
+    if (dryRun) {
+        result.synced = plan.include.map((f) => ({ id: "", filename: f.name }));
+        if (asJson) {
+            console.log(JSON.stringify(toJsonManifest(result, { project, dryRun: true }), null, 2));
+        }
+        else {
+            console.log(formatManifestText(result, { project, dryRun: true }));
+        }
+        return;
+    }
+    if (plan.include.length === 0) {
+        if (asJson) {
+            console.log(JSON.stringify(toJsonManifest(result, { project, dryRun: false }), null, 2));
+        }
+        else {
+            console.log(formatManifestText(result, { project, dryRun: false }));
+        }
+        return;
+    }
+    // 5. Credit check — each analyzable upload costs 1 credit. The server draws
+    //    from monthly credits first, then one-time bonus credits, so the real
+    //    balance is remaining + bonus.
+    try {
+        const usage = (await apiRequest(config, "GET", "/usage"));
+        const available = (usage.credits?.remaining ?? 0) + (usage.credits?.bonus ?? 0);
+        if (plan.include.length > available) {
+            const msg = `Plan uploads ${plan.include.length} file(s) but only ${available} credit(s) remain; uploads past the limit will store without AI analysis.`;
+            if (assumeYes) {
+                console.error(`Warning: ${msg}`);
+            }
+            else if (!asJson) {
+                const ok = await confirm(`${msg}\nContinue? [y/N] `);
+                if (!ok) {
+                    console.log("Aborted.");
+                    return;
+                }
+            }
+            else {
+                throw new Error(`${msg} Re-run with --yes to proceed.`);
+            }
+        }
+    }
+    catch (err) {
+        // Only abort if this was our own credit-guard error; usage lookups are best-effort.
+        if (/Re-run with --yes/.test(err.message))
+            throw err;
+    }
+    // 6. Upload sequentially, then poll each to a terminal state.
+    for (const f of plan.include) {
+        if (!asJson)
+            process.stderr.write(`Uploading ${f.name}… `);
+        try {
+            const outcome = await uploadFile(config, f.path, f.name, project, tags);
+            if (outcome.duplicateOf) {
+                result.skipped.push({
+                    filename: f.name,
+                    reason: `duplicate of ${outcome.duplicateOf}`,
+                });
+                if (!asJson)
+                    process.stderr.write("duplicate\n");
+                continue;
+            }
+            const asset = outcome.asset;
+            const status = await pollUntilReady(config, asset.id);
+            if (status === "error") {
+                result.failed.push({ filename: f.name, error: `analysis failed (${asset.id})` });
+                if (!asJson)
+                    process.stderr.write("error\n");
+            }
+            else {
+                result.synced.push({ id: asset.id, filename: f.name });
+                if (!asJson)
+                    process.stderr.write(status === "ready" ? "ready\n" : "queued\n");
+            }
+        }
+        catch (err) {
+            result.failed.push({ filename: f.name, error: err.message });
+            if (!asJson)
+                process.stderr.write("failed\n");
+        }
+    }
+    // 7. Manifest.
+    if (asJson) {
+        console.log(JSON.stringify(toJsonManifest(result, { project, dryRun: false }), null, 2));
+    }
+    else {
+        console.log("\n" + formatManifestText(result, { project, dryRun: false }));
+    }
+}
+// ─── Phase 2: Generative Commands ─────────────────────────────────────────
+async function cmdCreativeDirection(args, flags) {
+    const id = args[0];
+    if (!id) {
+        console.error("Usage: argus-media-cli creative-direction <asset-id> [--purpose TEXT] [--audience TEXT] [--tone TEXT] [--style TEXT]");
+        process.exit(1);
+    }
+    const config = await loadConfig();
+    const body = {};
+    if (flags.purpose)
+        body.purpose = flags.purpose;
+    if (flags.audience)
+        body.audience = flags.audience;
+    if (flags.tone)
+        body.tone = flags.tone;
+    if (flags.style)
+        body.style = flags.style;
+    const data = (await apiRequest(config, "POST", `/assets/${id}/creative-direction`, body));
+    if (flags.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    const cd = data.creativeDirection;
+    console.log(`\x1b[1mCreative Direction\x1b[0m${data.cached ? " (cached)" : ""}\n`);
+    console.log(cd.rationale);
+    if (cd.googleFontsUrl)
+        console.log(`\nGoogle Fonts: ${cd.googleFontsUrl}`);
+    if (cd.typography?.length) {
+        console.log(`\n\x1b[1mTypography:\x1b[0m`);
+        for (const t of cd.typography) {
+            console.log(`  ${t.role}: ${t.css.fontFamily} (${t.css.fontWeight}) — ${t.semantic}`);
+        }
+    }
+    if (cd.colors?.length) {
+        console.log(`\n\x1b[1mColors:\x1b[0m`);
+        for (const c of cd.colors) {
+            console.log(`  ${c.role}: ${c.css.color} — ${c.semantic}`);
+        }
+    }
+    if (cd.layout?.length) {
+        console.log(`\n\x1b[1mLayout:\x1b[0m`);
+        for (const l of cd.layout) {
+            console.log(`  ${l.pattern} — ${l.semantic}`);
+        }
+    }
+}
+async function cmdTypography(args, flags) {
+    const id = args[0];
+    if (!id) {
+        console.error("Usage: argus-media-cli typography <asset-id> [--purpose TEXT]");
+        process.exit(1);
+    }
+    const config = await loadConfig();
+    const body = {};
+    if (flags.purpose)
+        body.purpose = flags.purpose;
+    const data = (await apiRequest(config, "POST", `/assets/${id}/typography`, body));
+    if (flags.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    const typo = data.typography;
+    console.log(`\x1b[1mTypography Suggestions\x1b[0m${data.cached ? " (cached)" : ""}\n`);
+    if (typo.pairings?.length) {
+        for (const t of typo.pairings) {
+            console.log(`  ${t.role}: ${t.css.fontFamily} (${t.css.fontWeight}) — ${t.semantic}`);
+            if (t.googleFontsUrl)
+                console.log(`    Font: ${t.googleFontsUrl}`);
+        }
+    }
+    if (typo.googleFontsUrl)
+        console.log(`\nGoogle Fonts: ${typo.googleFontsUrl}`);
+    if (typo.rationale)
+        console.log(`\n${typo.rationale}`);
+}
+async function cmdPalette(args, flags) {
+    const id = args[0];
+    if (!id) {
+        console.error("Usage: argus-media-cli palette <asset-id>");
+        process.exit(1);
+    }
+    const config = await loadConfig();
+    const data = (await apiRequest(config, "POST", `/assets/${id}/palette`));
+    if (flags.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    const palette = data.palette;
+    console.log(`\x1b[1mColor Palette\x1b[0m${data.cached ? " (cached)" : ""}\n`);
+    if (palette.colors?.length) {
+        for (const c of palette.colors) {
+            console.log(`  ${c.role}: ${c.css.color} — ${c.semantic}`);
+        }
+    }
+    if (palette.rationale)
+        console.log(`\n${palette.rationale}`);
+}
+async function cmdCohesion(args, flags) {
+    if (args.length < 2) {
+        console.error("Usage: argus-media-cli cohesion <asset-id> <asset-id> [<asset-id>...] [--purpose TEXT] [--brand TEXT]");
+        process.exit(1);
+    }
+    const config = await loadConfig();
+    const body = { assetIds: args };
+    if (flags.purpose || flags.brand) {
+        const context = {};
+        if (flags.purpose)
+            context.purpose = flags.purpose;
+        if (flags.brand)
+            context.brandName = flags.brand;
+        body.context = context;
+    }
+    const data = (await apiRequest(config, "POST", "/assets/compare-cohesion", body));
+    if (flags.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    const c = data.cohesion;
+    console.log(`\x1b[1mCohesion Report\x1b[0m${data.cached ? " (cached)" : ""}\n`);
+    console.log(`  Overall:    ${c.overallScore}/100`);
+    console.log(`  Typography: ${c.typography.score}/100 — ${c.typography.consistency}`);
+    console.log(`  Color:      ${c.color.score}/100 — ${c.color.harmony}`);
+    console.log(`  Mood:       ${c.mood.score}/100 — ${c.mood.alignment}`);
+    if (c.suggestions?.length) {
+        console.log(`\n\x1b[1mSuggestions:\x1b[0m`);
+        for (const s of c.suggestions) {
+            const sev = s.severity === "high" ? "\x1b[31m" : s.severity === "medium" ? "\x1b[33m" : "\x1b[32m";
+            console.log(`  ${sev}${s.severity}\x1b[0m ${s.asset.slice(0, 8)}: ${s.suggestion}`);
+        }
+    }
+    if (c.rationale)
+        console.log(`\n${c.rationale}`);
+}
+// ─── API Key Management ───────────────────────────────────────────────────
+async function cmdKeys(args, flags) {
+    const sub = args[0];
+    const rest = args.slice(1);
+    if (!sub || sub === "list" || sub === "ls") {
+        return cmdKeysList(rest, flags);
+    }
+    if (sub === "create" || sub === "new") {
+        return cmdKeysCreate(rest, flags);
+    }
+    if (sub === "revoke" || sub === "delete" || sub === "rm") {
+        return cmdKeysRevoke(rest, flags);
+    }
+    console.error(`Unknown keys subcommand: ${sub}`);
+    console.error("Usage: argus-media-cli keys <list|create|revoke>");
+    process.exit(1);
+}
+async function cmdKeysList(_args, flags) {
+    const config = await loadConfig();
+    const data = (await apiRequest(config, "GET", "/keys"));
+    if (flags.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    const keys = data.keys || [];
+    if (!keys.length) {
+        console.log("No API keys found.");
+        console.log("Create one with: argus-media-cli keys create --name 'My Key'");
+        return;
+    }
+    console.log(`\x1b[1m${keys.length} API key${keys.length === 1 ? "" : "s"}\x1b[0m\n`);
+    for (const k of keys) {
+        const status = k.revoked_at ? "\x1b[31mrevoked\x1b[0m" : "\x1b[32mactive\x1b[0m ";
+        const lastUsed = k.last_used_at ? `used ${k.last_used_at}` : "never used";
+        console.log(`  ${status}  ${k.key_prefix}…  ${k.name}`);
+        console.log(`    id: ${k.id}`);
+        console.log(`    created ${k.created_at}, ${lastUsed}`);
+    }
+}
+async function cmdKeysCreate(args, flags) {
+    const name = flags.name || args[0] || "API Key";
+    const config = await loadConfig();
+    const data = (await apiRequest(config, "POST", "/keys", { name }));
+    if (flags.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    console.log(`\x1b[1mAPI key created\x1b[0m\n`);
+    console.log(`  Name:   ${data.name}`);
+    console.log(`  ID:     ${data.id}`);
+    console.log(`  Prefix: ${data.key_prefix}`);
+    console.log(`\n\x1b[1m\x1b[33mKey (shown once — store it now):\x1b[0m`);
+    console.log(`  ${data.key}\n`);
+    console.log(`Use it by setting:`);
+    console.log(`  export ARGUS_API_KEY=${data.key}`);
+}
+async function cmdKeysRevoke(args, flags) {
+    const id = args[0];
+    if (!id) {
+        console.error("Usage: argus-media-cli keys revoke <id>");
+        process.exit(1);
+    }
+    const config = await loadConfig();
+    const data = (await apiRequest(config, "DELETE", `/keys/${id}`));
+    if (flags.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    console.log(`Key ${id} revoked.`);
+}
+async function cmdStyleGuide(args, flags) {
+    if (args.length < 1) {
+        console.error("Usage: argus-media-cli style-guide <asset-id> [<asset-id>...] [--name TEXT] [--guide-id ID]");
+        process.exit(1);
+    }
+    const config = await loadConfig();
+    const body = { assetIds: args };
+    if (flags.name)
+        body.name = flags.name;
+    if (flags["guide-id"])
+        body.guideId = flags["guide-id"];
+    const data = (await apiRequest(config, "POST", "/style-guides", body));
+    if (flags.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    const sg = data.styleGuide;
+    console.log(`\x1b[1mStyle Guide: ${sg.name || sg.id}\x1b[0m\n`);
+    console.log(`  ID:      ${sg.id}`);
+    console.log(`  Assets:  ${sg.sourceAssetIds?.length ?? 0}`);
+    if (data.googleFontsUrl)
+        console.log(`  Fonts:   ${data.googleFontsUrl}`);
+    if (data.rationale)
+        console.log(`\n${data.rationale}`);
+}
 function parseArgs(argv) {
     const command = argv[0] || "help";
     const flags = {};
@@ -296,10 +777,19 @@ function printHelp() {
 \x1b[1mCommands:\x1b[0m
   login                   Authenticate with Argus
   upload <file>           Upload a media file
+  sync <folder>           Onboard a folder of assets in one shot
   search <query>          Search assets by description, tags, mood
   list                    List all assets
   get <id>                Get asset details and analysis
   usage                   Show workspace usage and limits
+  creative-direction <id> Generate creative brief for an asset
+  typography <id>         Suggest typography pairings for an asset
+  palette <id>            Generate extended color palette from an asset
+  cohesion <id> <id> ...  Compare visual cohesion across assets
+  style-guide <id> ...    Generate a style guide from assets
+  keys list               List API keys in the current workspace
+  keys create [--name]    Create a new API key (shown once)
+  keys revoke <id>        Revoke an API key (admin only)
 
 \x1b[1mGlobal Options:\x1b[0m
   --json                  Output raw JSON
@@ -308,6 +798,12 @@ function printHelp() {
   --project NAME          Assign to a project
   --tags a,b,c            Comma-separated tags
 
+\x1b[1mSync Options:\x1b[0m
+  --project NAME          Target project (default: kebab-cased folder name)
+  --tags a,b,c            Tags applied to every synced asset
+  --dry-run               Print the plan without uploading
+  --yes                   Skip the credit-shortfall confirmation prompt
+
 \x1b[1mSearch/List Options:\x1b[0m
   --project NAME          Filter by project
   --status STATUS         Filter by status (pending, ready, error)
@@ -315,10 +811,30 @@ function printHelp() {
   --limit N               Max results (default 50)
   --offset N              Pagination offset
 
+\x1b[1mCreative Direction Options:\x1b[0m
+  --purpose TEXT          Intended use (e.g. 'hero banner')
+  --audience TEXT         Target audience
+  --tone TEXT             Desired tone (e.g. 'professional')
+  --style TEXT            Visual style (e.g. 'minimalist')
+
+\x1b[1mTypography Options:\x1b[0m
+  --purpose TEXT          Intended use context
+
+\x1b[1mCohesion Options:\x1b[0m
+  --purpose TEXT          Comparison context
+  --brand TEXT            Brand name for context
+
+\x1b[1mStyle Guide Options:\x1b[0m
+  --name TEXT             Name for the style guide
+  --guide-id ID           Existing guide ID to update
+
 \x1b[1mLogin Options:\x1b[0m
   --key KEY               Set API key non-interactively
   --url URL               Set custom API base URL
 
+\x1b[1mKeys Options:\x1b[0m
+  --name TEXT             Name for the new key (keys create)
+
 \x1b[1mEnvironment:\x1b[0m
   ARGUS_API_KEY           API key (overrides saved config)
   ARGUS_BASE_URL          API base URL (default: https://argus.build)
@@ -326,28 +842,76 @@ function printHelp() {
 \x1b[1mExamples:\x1b[0m
   argus-media-cli login
   argus-media-cli upload photo.jpg --project campaign-q2 --tags hero,banner
+  argus-media-cli sync ./legacy-brand-folder --dry-run
+  argus-media-cli sync ./legacy-brand-folder --project brand-2019 --tags legacy
   argus-media-cli search "sunset landscape" --json
   argus-media-cli list --project website --limit 20
   argus-media-cli get abc12345-def6-7890-abcd-ef1234567890
 `);
 }
+// ─── Onboarding ───────────────────────────────────────────────────────────
+function isAuthenticated(config) {
+    return !!(process.env.ARGUS_API_KEY || config.apiKey || config.sessionId);
+}
+async function cmdDashboard(_args, flags) {
+    const config = await loadConfig();
+    const res = await apiRequest(config, "GET", "/usage");
+    console.log(`\x1b[1mArgus Dashboard\x1b[0m\n`);
+    console.log(`  Tier:    ${res.tier}`);
+    console.log(`  Assets:  ${res.assets?.used ?? 0} / ${res.assets?.limit ?? "unlimited"}`);
+    if (res.storage != null) {
+        console.log(`  Storage: ${res.storage?.used != null ? formatBytes(res.storage.used) : "0 B"} / ${res.storage?.limit != null ? formatBytes(res.storage.limit) : "unlimited"}`);
+    }
+    console.log(`\nRun \x1b[1margus-media-cli help\x1b[0m for available commands.`);
+}
 // ─── Main ──────────────────────────────────────────────────────────────────
 const COMMANDS = {
+    dashboard: cmdDashboard,
     login: cmdLogin,
     upload: cmdUpload,
+    sync: cmdSync,
     search: cmdSearch,
     list: cmdList,
     get: cmdGet,
     usage: cmdUsage,
+    "creative-direction": cmdCreativeDirection,
+    typography: cmdTypography,
+    palette: cmdPalette,
+    cohesion: cmdCohesion,
+    "style-guide": cmdStyleGuide,
+    keys: cmdKeys,
 };
 async function main() {
-    const { command, args, flags } = parseArgs(process.argv.slice(2));
+    const rawArgs = process.argv.slice(2);
+    // No args: onboarding — show dashboard or prompt login
+    if (rawArgs.length === 0) {
+        const config = await loadConfig();
+        if (isAuthenticated(config)) {
+            try {
+                await cmdDashboard([], {});
+            }
+            catch {
+                console.log("\x1b[1mArgus Media CLI\x1b[0m\n");
+                console.log("Run \x1b[1margus-media-cli help\x1b[0m for available commands.");
+            }
+        }
+        else {
+            console.log("\x1b[1mWelcome to Argus!\x1b[0m\n");
+            console.log("Get started by signing in:\n");
+            console.log("  argus-media-cli login\n");
+            console.log("Or set an API key for CI use:\n");
+            console.log("  argus-media-cli login --key <your-key>\n");
+            console.log("Run \x1b[1margus-media-cli help\x1b[0m for all commands.");
+        }
+        return;
+    }
+    const { command, args, flags } = parseArgs(rawArgs);
     if (command === "help" || command === "--help" || command === "-h") {
         printHelp();
         return;
     }
     if (command === "version" || command === "--version" || command === "-v") {
-        console.log("argus-media-cli 0.1.2");
+        console.log("argus-media-cli 0.4.0");
         return;
     }
     const handler = COMMANDS[command];

package/dist/sync.d.ts

@@ -0,0 +1,76 @@
+/** Server-enforced upload cap. Files larger than this are skipped. */
+export declare const MAX_SYNC_SIZE: number;
+/**
+ * File types Argus can ingest and analyze. Mirrors the server's ANALYZABLE_TYPES
+ * (JPEG/PNG/GIF/WebP/SVG). Anything else is skipped with an "unsupported type" reason.
+ */
+export declare const SYNCABLE_EXTENSIONS: Record<string, string>;
+export interface FileEntry {
+    path: string;
+    name: string;
+    size: number;
+}
+export interface HashedFile extends FileEntry {
+    /** sha256 of file contents; undefined for files that never reach the dedup stage. */
+    hash?: string;
+}
+export interface ExistingAsset {
+    filename: string;
+    size: number;
+}
+export interface SyncPlan {
+    include: HashedFile[];
+    skip: {
+        filename: string;
+        path: string;
+        reason: string;
+    }[];
+}
+export interface SyncResult {
+    synced: {
+        id: string;
+        filename: string;
+    }[];
+    skipped: {
+        filename: string;
+        reason: string;
+    }[];
+    failed: {
+        filename: string;
+        error: string;
+    }[];
+}
+export declare function formatBytes(bytes: number): string;
+export declare function kebabCase(input: string): string;
+/** Default project name = kebab-cased basename of the folder. */
+export declare function deriveProject(folder: string): string;
+export declare function mimeForFile(name: string): string | null;
+/**
+ * Cheap, hash-free skip checks: junk, hidden, unsupported type, oversize.
+ * Returns a human-readable reason, or null if the file passes and should be hashed.
+ */
+export declare function basicSkipReason(f: FileEntry): string | null;
+/**
+ * Recursively collect files under `dir`. Hidden directories (`.git`, etc.) are
+ * skipped entirely; hidden *files* are still returned so they can be reported as
+ * skipped-with-reason. Output is sorted by path for deterministic manifests.
+ */
+export declare function walk(dir: string): Promise<FileEntry[]>;
+/**
+ * Decide which files to upload vs skip.
+ *
+ * Skip reasons, in priority order:
+ *   1. junk / hidden / unsupported / oversize (see basicSkipReason)
+ *   2. an existing asset in the target project with the same filename + size
+ *   3. an earlier file in this run with identical contents (hash)
+ *
+ * `files` should carry a `hash` for every entry that passes basicSkipReason;
+ * entries without a hash simply never match the content-dedup check.
+ */
+export declare function buildPlan(files: HashedFile[], existing: ExistingAsset[]): SyncPlan;
+export interface ManifestMeta {
+    project: string;
+    dryRun: boolean;
+}
+export declare function toJsonManifest(result: SyncResult, meta: ManifestMeta): object;
+export declare function formatManifestText(result: SyncResult, meta: ManifestMeta): string;

package/dist/sync.js

@@ -0,0 +1,189 @@
+// Pure, testable logic for the `sync <folder>` command.
+// Kept separate from index.ts so the walk/filter/dedup/manifest behaviour can be
+// unit-tested without spinning up the CLI or hitting the network.
+import { readdir, stat } from "node:fs/promises";
+import { basename, extname, join } from "node:path";
+/** Server-enforced upload cap. Files larger than this are skipped. */
+export const MAX_SYNC_SIZE = 20 * 1024 * 1024; // 20 MB
+/**
+ * File types Argus can ingest and analyze. Mirrors the server's ANALYZABLE_TYPES
+ * (JPEG/PNG/GIF/WebP/SVG). Anything else is skipped with an "unsupported type" reason.
+ */
+export const SYNCABLE_EXTENSIONS = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+};
+/** OS/editor cruft that should never be uploaded. */
+const JUNK_FILENAMES = new Set([".DS_Store", "Thumbs.db", "desktop.ini"]);
+// ─── Formatting ──────────────────────────────────────────────────────────────
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+// ─── Project derivation ────────────────────────────────────────────────────────
+export function kebabCase(input) {
+    return input
+        .trim()
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2") // camelCase → camel-Case
+        .replace(/[\s_]+/g, "-")
+        .replace(/[^a-zA-Z0-9-]/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .toLowerCase();
+}
+/** Default project name = kebab-cased basename of the folder. */
+export function deriveProject(folder) {
+    const trimmed = folder.replace(/[/\\]+$/, "");
+    const base = basename(trimmed);
+    return kebabCase(base) || "imports";
+}
+// ─── Classification ────────────────────────────────────────────────────────────
+export function mimeForFile(name) {
+    const ext = extname(name).toLowerCase();
+    return SYNCABLE_EXTENSIONS[ext] ?? null;
+}
+/**
+ * Cheap, hash-free skip checks: junk, hidden, unsupported type, oversize.
+ * Returns a human-readable reason, or null if the file passes and should be hashed.
+ */
+export function basicSkipReason(f) {
+    if (JUNK_FILENAMES.has(f.name))
+        return "junk file";
+    if (f.name.startsWith("."))
+        return "hidden file";
+    const mime = mimeForFile(f.name);
+    if (!mime) {
+        const ext = extname(f.name).toLowerCase();
+        return `unsupported type (${ext || "no extension"})`;
+    }
+    if (f.size > MAX_SYNC_SIZE) {
+        return `exceeds 20 MB limit (${formatBytes(f.size)})`;
+    }
+    return null;
+}
+// ─── Walk ──────────────────────────────────────────────────────────────────────
+/**
+ * Recursively collect files under `dir`. Hidden directories (`.git`, etc.) are
+ * skipped entirely; hidden *files* are still returned so they can be reported as
+ * skipped-with-reason. Output is sorted by path for deterministic manifests.
+ */
+export async function walk(dir) {
+    const out = [];
+    async function recurse(current) {
+        const entries = await readdir(current, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = join(current, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name.startsWith("."))
+                    continue; // skip .git, .cache, etc.
+                await recurse(full);
+            }
+            else if (entry.isFile()) {
+                const s = await stat(full);
+                out.push({ path: full, name: entry.name, size: s.size });
+            }
+        }
+    }
+    await recurse(dir);
+    out.sort((a, b) => a.path.localeCompare(b.path));
+    return out;
+}
+// ─── Plan ────────────────────────────────────────────────────────────────────
+/**
+ * Decide which files to upload vs skip.
+ *
+ * Skip reasons, in priority order:
+ *   1. junk / hidden / unsupported / oversize (see basicSkipReason)
+ *   2. an existing asset in the target project with the same filename + size
+ *   3. an earlier file in this run with identical contents (hash)
+ *
+ * `files` should carry a `hash` for every entry that passes basicSkipReason;
+ * entries without a hash simply never match the content-dedup check.
+ */
+export function buildPlan(files, existing) {
+    const include = [];
+    const skip = [];
+    const existingKeys = new Set(existing.map((a) => `${a.filename}:${a.size}`));
+    const seenHashes = new Map(); // hash → first filename seen
+    for (const f of files) {
+        const basic = basicSkipReason(f);
+        if (basic) {
+            skip.push({ filename: f.name, path: f.path, reason: basic });
+            continue;
+        }
+        // Content dedup within the run. The first file with a given hash claims it,
+        // even if that first file is then skipped for another reason (e.g. already
+        // in the project) — a later identical-content file is still a duplicate.
+        if (f.hash && seenHashes.has(f.hash)) {
+            skip.push({
+                filename: f.name,
+                path: f.path,
+                reason: `duplicate of ${seenHashes.get(f.hash)}`,
+            });
+            continue;
+        }
+        if (f.hash)
+            seenHashes.set(f.hash, f.name);
+        if (existingKeys.has(`${f.name}:${f.size}`)) {
+            skip.push({
+                filename: f.name,
+                path: f.path,
+                reason: "already in project (same name + size)",
+            });
+            continue;
+        }
+        include.push(f);
+    }
+    return { include, skip };
+}
+export function toJsonManifest(result, meta) {
+    return {
+        project: meta.project,
+        dryRun: meta.dryRun,
+        summary: {
+            synced: result.synced.length,
+            skipped: result.skipped.length,
+            failed: result.failed.length,
+        },
+        synced: result.synced,
+        skipped: result.skipped,
+        failed: result.failed,
+    };
+}
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const RED = "\x1b[31m";
+const RESET = "\x1b[0m";
+export function formatManifestText(result, meta) {
+    const lines = [];
+    const header = meta.dryRun ? "Sync plan (dry run)" : "Sync complete";
+    lines.push(`${BOLD}${header}${RESET} — project ${BOLD}${meta.project}${RESET}\n`);
+    const syncedLabel = meta.dryRun ? "Would sync" : "Synced";
+    lines.push(`${GREEN}${syncedLabel}: ${result.synced.length}${RESET}`);
+    for (const s of result.synced) {
+        const id = s.id ? `${DIM}${s.id}${RESET}  ` : "";
+        lines.push(`  ${id}${s.filename}`);
+    }
+    if (result.skipped.length) {
+        lines.push(`\n${YELLOW}Skipped: ${result.skipped.length}${RESET}`);
+        for (const s of result.skipped) {
+            lines.push(`  ${s.filename} ${DIM}— ${s.reason}${RESET}`);
+        }
+    }
+    if (result.failed.length) {
+        lines.push(`\n${RED}Failed: ${result.failed.length}${RESET}`);
+        for (const f of result.failed) {
+            lines.push(`  ${f.filename} ${DIM}— ${f.error}${RESET}`);
+        }
+    }
+    return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argus-media-cli",
-  "version": "0.1.2",
+  "version": "0.4.1",
   "description": "CLI for Argus — AI-native media asset management. Upload, search, analyze, and manage media assets from the terminal.",
   "keywords": [
     "argus",
@@ -29,12 +29,14 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
-    "typescript": "^5.4.0"
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.2"
   },
   "engines": {
     "node": ">=18"