@prave/cli 0.4.8 → 0.5.0

package/dist/commands/conflicts.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
 import ora from 'ora';
 import { api, ApiError } from '../lib/api.js';
+import { requireAuth } from '../lib/credentials.js';
 import { log } from '../utils/logger.js';
 function describe(c) {
     const a = c.skill_a_name ?? c.skill_a_id;
@@ -17,6 +18,9 @@ function describe(c) {
     }
 }
 export async function conflictsCommand(opts = {}) {
+    const _session = await requireAuth("prave conflicts");
+    if (!_session)
+        return;
     const spinner = ora('Detecting conflicts…').start();
     try {
         const { data: conflicts } = await api.get('/api/v1/intelligence/conflicts?refresh=true', true);

package/dist/commands/deploy.js

@@ -5,6 +5,7 @@ import chalk from 'chalk';
 import ora from 'ora';
 import { AGENT_REGISTRY } from '@prave/shared';
 import { api, ApiError } from '../lib/api.js';
+import { requireAuth } from '../lib/credentials.js';
 import { CONFIG } from '../lib/config.js';
 import { log } from '../utils/logger.js';
 function detectOsKey(detected) {
@@ -68,6 +69,9 @@ function buildDestPath(agent, basePath, os, slug) {
     };
 }
 export async function deployCommand(skillName, opts = {}) {
+    const session = await requireAuth('prave deploy');
+    if (!session)
+        return;
     const start = Date.now();
     let settings;
     try {

package/dist/commands/import.js

@@ -4,14 +4,27 @@ import chalk from 'chalk';
 import ora from 'ora';
 import { api } from '../lib/api.js';
 import { CONFIG } from '../lib/config.js';
-import { loadCredentials } from '../lib/credentials.js';
+import { loadCredentials, requireAuth } from '../lib/credentials.js';
 import { fetchMyPlan, formatUpgradeHint } from '../lib/plan.js';
 import { log } from '../utils/logger.js';
 /**
  * Scans CONFIG.skillsDir for SKILL.md files. Without --upload, only prints
  * the overview — no network call, no consent required.
  */
+/**
+ * Visibility is mandatory on uploads — no silent defaults. Users must pass
+ * either `--public` or `--private`. This avoids the embarrassment of
+ * accidentally publishing private notes to the registry.
+ */
 export async function importCommand(opts) {
+    // `prave import` (without --upload) only inspects local files and posts
+    // to /intelligence/analyze if logged in — uploads, however, must always
+    // be tracked, so we gate on auth whenever --upload is set.
+    if (opts.upload) {
+        const session = await requireAuth('prave import --upload');
+        if (!session)
+            return;
+    }
     const spinner = ora(`Scanning ${CONFIG.skillsDir}…`).start();
     let entries = [];
     try {
@@ -56,10 +69,19 @@ export async function importCommand(opts) {
         }
         return;
     }
+    // Visibility is required on every upload — no silent default.
+    if (opts.public === opts.private) {
+        log.warn('Specify visibility: --public or --private (one is required on upload).');
+        log.dim('Examples:');
+        log.dim('  prave import --upload --private    # only you can see them');
+        log.dim('  prave import --upload --public     # listed in the public registry');
+        process.exitCode = 1;
+        return;
+    }
+    const visibility = opts.private ? 'private' : 'public';
     // Plan gate: clamp the queue to the caller's import / private quota so
     // we don't waste 70 round-trips against a Free account that maxes at 10.
     const me = await fetchMyPlan();
-    const visibility = opts.private ? 'private' : 'public';
     if (visibility === 'private' && !me.limits.can_private_skills) {
         log.warn('Private imports require the Explorer plan.');
         log.dim(formatUpgradeHint('explorer'));

package/dist/commands/install.js

@@ -5,7 +5,7 @@ import chalk from 'chalk';
 import ora from 'ora';
 import { api, ApiError } from '../lib/api.js';
 import { CONFIG } from '../lib/config.js';
-import { loadCredentials } from '../lib/credentials.js';
+import { loadCredentials, requireAuth } from '../lib/credentials.js';
 import { log } from '../utils/logger.js';
 /**
  * `prave install <slug>` — pulls SKILL.md to ~/.claude/skills/<slug>/.
@@ -18,15 +18,21 @@ import { log } from '../utils/logger.js';
  *     instead of letting the API error bubble.
  */
 export async function installCommand(slug, opts = {}) {
+    // Auth gate — installs MUST be tracked, otherwise we can't bump counts,
+    // serve recommendations, or surface "updates available" later. Block here
+    // before any registry hit so the user gets a clear hint instead of a
+    // silently-untracked install.
+    const session = await requireAuth('prave install');
+    if (!session)
+        return;
     const spinner = ora(`Resolving ${slug}…`).start();
     let installedSlugs = [];
     try {
         const slugs = opts.noDeps ? [slug] : await resolveOrder(slug);
         spinner.text = `Installing ${slugs.length} skill${slugs.length === 1 ? '' : 's'}…`;
-        const session = await loadCredentials();
         for (const s of slugs) {
             spinner.text = `↓ ${s}`;
-            await pullOne(s, { hasSession: Boolean(session), force: Boolean(opts.force) });
+            await pullOne(s, { hasSession: true, force: Boolean(opts.force) });
         }
         installedSlugs = slugs;
         spinner.succeed(`Installed ${slugs.length} skill${slugs.length === 1 ? '' : 's'} → ${CONFIG.skillsDir}`);
@@ -39,9 +45,6 @@ export async function installCommand(slug, opts = {}) {
         process.exitCode = 1;
         return;
     }
-    const session = await loadCredentials();
-    if (!session)
-        return;
     // Best-effort analyze pass on the freshly written files.
     for (const s of installedSlugs) {
         const path = join(CONFIG.skillsDir, s, 'SKILL.md');
@@ -55,7 +58,11 @@ export async function installCommand(slug, opts = {}) {
             /* file unreadable — skip */
         }
     }
-    // Offer to deploy to all configured agents.
+    // Offer to deploy to all configured agents — unless the caller already
+    // answered the question (e.g. `prave sync` collects the answer once for
+    // the whole batch and threads it through `skipDeployPrompt`).
+    if (opts.skipDeployPrompt)
+        return;
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {
         const ans = (await rl.question('\nDeploy to all configured agents? [y/N] ')).trim().toLowerCase();

package/dist/commands/optimize.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
 import ora from 'ora';
 import { api, ApiError } from '../lib/api.js';
+import { requireAuth } from '../lib/credentials.js';
 import { log } from '../utils/logger.js';
 function formatTokens(n) {
     if (n < 1000)
@@ -11,6 +12,9 @@ function nameOf(s) {
     return s.name ?? s.file_path;
 }
 export async function optimizeCommand(opts = {}) {
+    const _session = await requireAuth("prave optimize");
+    if (!_session)
+        return;
     const spinner = ora('Analyzing your skill set…').start();
     try {
         const { data } = await api.get('/api/v1/intelligence/optimize', true);

package/dist/commands/overview.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
 import ora from 'ora';
 import { api, ApiError } from '../lib/api.js';
+import { requireAuth } from '../lib/credentials.js';
 import { log } from '../utils/logger.js';
 function formatThousands(n) {
     if (n < 1000)
@@ -13,6 +14,9 @@ function pad(s, width) {
     return s + ' '.repeat(width - s.length);
 }
 export async function overviewCommand(opts = {}) {
+    const _session = await requireAuth("prave overview");
+    if (!_session)
+        return;
     if (opts.json) {
         try {
             const { data } = await api.get('/api/v1/intelligence/overview', true);

package/dist/commands/settings.js

@@ -3,6 +3,7 @@ import { createInterface } from 'node:readline/promises';
 import chalk from 'chalk';
 import { AGENT_REGISTRY, AGENT_TYPES } from '@prave/shared';
 import { api, ApiError } from '../lib/api.js';
+import { requireAuth } from '../lib/credentials.js';
 import { CONFIG } from '../lib/config.js';
 import { log } from '../utils/logger.js';
 function detectOs() {
@@ -130,6 +131,9 @@ async function showAccount() {
     log.dim('Run `prave whoami` for full identity, or `prave logout` to sign out.');
 }
 export async function settingsCommand() {
+    const _session = await requireAuth("prave settings");
+    if (!_session)
+        return;
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {
         let current;

package/dist/commands/sync.js

@@ -1,28 +1,35 @@
 import { readdir, stat } from 'node:fs/promises';
 import { join } from 'node:path';
+import { createInterface } from 'node:readline/promises';
 import chalk from 'chalk';
 import ora from 'ora';
 import { CONFIG } from '../lib/config.js';
-import { loadCredentials } from '../lib/credentials.js';
+import { requireAuth } from '../lib/credentials.js';
 import { fetchMyPlan, formatUpgradeHint } from '../lib/plan.js';
 import { log } from '../utils/logger.js';
 import { installCommand } from './install.js';
 /**
  * `prave sync` — re-pulls every locally installed Skill from the
  * registry. Picks up SKILL.md edits without the user having to remember
- * each slug. Skips deps (each top-level Skill already has its tree
- * resolved on the original install).
+ * each slug.
+ *
+ * The deploy-to-all-agents question is asked ONCE up-front for the entire
+ * queue (regression fix: it used to fire per Skill, forcing the user to
+ * mash `y` 30 times). The answer is then threaded into every
+ * `installCommand` invocation via `skipDeployPrompt: true` and we run a
+ * single batched deploy at the end.
  */
 export async function syncCommand() {
+    // Auth gate — sync mutates the install ledger and intelligence cache.
+    const session = await requireAuth('prave sync');
+    if (!session)
+        return;
     // Plan gate: sync requires Explorer or higher.
-    const session = await loadCredentials();
-    if (session) {
-        const me = await fetchMyPlan();
-        if (!me.limits.can_cli_sync) {
-            log.warn('Sync requires the Explorer plan or higher.');
-            log.dim(formatUpgradeHint('explorer'));
-            return;
-        }
+    const me = await fetchMyPlan();
+    if (!me.limits.can_cli_sync) {
+        log.warn('Sync requires the Explorer plan or higher.');
+        log.dim(formatUpgradeHint('explorer'));
+        return;
     }
     const spinner = ora('Scanning local Skills…').start();
     let entries = [];
@@ -44,11 +51,23 @@ export async function syncCommand() {
         return;
     }
     spinner.succeed(`Found ${slugs.length} installed Skill${slugs.length === 1 ? '' : 's'}.`);
+    // Ask the deploy question ONCE for the whole batch.
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    let deployAfter = false;
+    try {
+        const ans = (await rl.question(`\nAfter syncing, deploy all ${slugs.length} Skills to your configured agents? [y/N] `))
+            .trim()
+            .toLowerCase();
+        deployAfter = ans === 'y' || ans === 'yes';
+    }
+    finally {
+        rl.close();
+    }
     let updated = 0;
     let failed = 0;
     for (const slug of slugs) {
         try {
-            await installCommand(slug, { noDeps: true });
+            await installCommand(slug, { noDeps: true, skipDeployPrompt: true });
             updated++;
         }
         catch {
@@ -57,4 +76,16 @@ export async function syncCommand() {
         }
     }
     log.dim(`\nSynced ${updated} · failed ${failed}`);
+    if (deployAfter && updated > 0) {
+        const { deployCommand } = await import('./deploy.js');
+        log.info(`\nDeploying ${updated} Skills to configured agents…`);
+        for (const slug of slugs) {
+            try {
+                await deployCommand(slug, {});
+            }
+            catch (err) {
+                log.warn(`  ✗ deploy ${slug} — ${err.message}`);
+            }
+        }
+    }
 }

package/dist/commands/update.js

@@ -0,0 +1,165 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import chalk from 'chalk';
+import ora from 'ora';
+import { api } from '../lib/api.js';
+import { CONFIG } from '../lib/config.js';
+import { requireAuth } from '../lib/credentials.js';
+import { log } from '../utils/logger.js';
+/**
+ * `prave update [<slug>]` — diff every CLI-installed Skill against its
+ * current Prave version and pull the ones that are outdated.
+ *
+ *   • No slug → walks the install ledger, compares each install's
+ *     `installed_at` vs the Skill's `updated_at`, and updates the stale
+ *     ones in-place under ~/.claude/skills/<slug>/SKILL.md.
+ *   • Slug given → updates exactly that Skill (force-pulls latest, even if
+ *     not stale — useful when the local file was edited and needs reset).
+ *
+ * Prints a short "audit-trail" line per Skill so the operator can see what
+ * changed: `markdown-pro  v3 → v5  (last pulled 12 Apr · published 21 Apr)`.
+ */
+export async function updateCommand(slug, opts = {}) {
+    const session = await requireAuth('prave update');
+    if (!session)
+        return;
+    const spinner = ora(slug ? `Resolving ${slug}…` : 'Checking your installed skills…').start();
+    let installs;
+    try {
+        const { data } = await api.get('/api/v1/me/installs', true);
+        installs = data;
+    }
+    catch (err) {
+        spinner.fail(`Couldn't fetch installs — ${err.message}`);
+        process.exitCode = 1;
+        return;
+    }
+    const targets = slug ? installs.filter((r) => r.skill?.slug === slug) : installs;
+    if (targets.length === 0) {
+        spinner.info(slug ? `${slug} is not in your install ledger.` : 'No installs on this account yet.');
+        return;
+    }
+    // Fetch the current Skill for each target in parallel.
+    spinner.text = `Comparing ${targets.length} skill${targets.length === 1 ? '' : 's'}…`;
+    const candidates = [];
+    const upToDate = [];
+    const errors = [];
+    await Promise.all(targets.map(async (row) => {
+        const targetSlug = row.skill?.slug;
+        if (!targetSlug)
+            return;
+        try {
+            const { data: skill } = await api.get(`/api/v1/skills/${targetSlug}`, true);
+            const isStale = isOutdated(row, skill, Boolean(slug));
+            if (!isStale) {
+                upToDate.push(targetSlug);
+                return;
+            }
+            candidates.push({
+                slug: targetSlug,
+                installedAt: row.installed_at,
+                serverUpdatedAt: skill.updated_at,
+                installedVersion: row.version ?? null,
+                latestVersion: typeof skill.current_version === 'number'
+                    ? skill.current_version ?? null
+                    : null,
+                remoteContent: skill.content ?? '',
+                localPath: join(CONFIG.skillsDir, targetSlug, 'SKILL.md'),
+            });
+        }
+        catch (err) {
+            errors.push(`${targetSlug}: ${err.message}`);
+        }
+    }));
+    if (candidates.length === 0) {
+        if (errors.length > 0) {
+            spinner.warn(`No updates available. ${errors.length} skill(s) couldn't be checked:`);
+            for (const e of errors)
+                log.dim(`  ✗ ${e}`);
+        }
+        else {
+            spinner.succeed(upToDate.length === 1
+                ? `${upToDate[0]} is up to date.`
+                : `All ${upToDate.length} installed skills are up to date.`);
+        }
+        return;
+    }
+    spinner.succeed(`${candidates.length} skill${candidates.length === 1 ? '' : 's'} can be updated.`);
+    // Audit-trail print — same format as a tiny commit log.
+    for (const c of candidates) {
+        const versionLine = c.installedVersion !== null && c.latestVersion !== null
+            ? `${chalk.dim('v')}${c.installedVersion} → ${chalk.bold('v' + c.latestVersion)}`
+            : chalk.dim('content-hash diff');
+        console.log(`  ${chalk.cyan('•')} ${chalk.bold(c.slug)}  ${versionLine}  ${chalk.dim(`(local ${formatDate(c.installedAt)} → registry ${formatDate(c.serverUpdatedAt)})`)}`);
+    }
+    if (opts.dryRun) {
+        log.dim(`\nDry run — nothing written. Re-run without --dry-run to apply.`);
+        return;
+    }
+    if (!opts.yes) {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        try {
+            const ans = (await rl.question(`\nPull ${candidates.length} update${candidates.length === 1 ? '' : 's'}? [Y/n] `))
+                .trim()
+                .toLowerCase();
+            if (ans && ans !== 'y' && ans !== 'yes') {
+                log.dim('Aborted.');
+                return;
+            }
+        }
+        finally {
+            rl.close();
+        }
+    }
+    const writeSpinner = ora(`Writing ${candidates.length} update${candidates.length === 1 ? '' : 's'}…`).start();
+    let written = 0;
+    for (const c of candidates) {
+        try {
+            await mkdir(join(CONFIG.skillsDir, c.slug), { recursive: true });
+            await writeFile(c.localPath, c.remoteContent, 'utf8');
+            // Re-record the install row so installed_at/version reflect the pull.
+            await api
+                .post(`/api/v1/skills/${encodeURIComponent(c.slug)}/install`, { version: c.latestVersion ?? null }, true)
+                .catch(() => { });
+            written += 1;
+        }
+        catch (err) {
+            writeSpinner.warn(`${c.slug}: ${err.message}`);
+        }
+    }
+    writeSpinner.succeed(`Updated ${written}/${candidates.length}${written === candidates.length ? '' : ` (${candidates.length - written} failed)`}.`);
+    if (errors.length > 0) {
+        log.dim(`\n${errors.length} skill(s) couldn't be checked earlier:`);
+        for (const e of errors)
+            log.dim(`  ✗ ${e}`);
+    }
+}
+/**
+ * "Stale" = the registry's `updated_at` is strictly newer than the
+ * install ledger's `installed_at`. For an explicit `prave update <slug>`
+ * we always treat the row as stale — the user is asking for a forced pull,
+ * which is also the right behaviour after a local edit gone wrong.
+ */
+function isOutdated(row, skill, force) {
+    if (force)
+        return true;
+    const installedTs = new Date(row.installed_at).getTime();
+    const updatedTs = new Date(skill.updated_at).getTime();
+    return Number.isFinite(installedTs) && Number.isFinite(updatedTs) && updatedTs > installedTs;
+}
+function formatDate(iso) {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return iso;
+    return d.toLocaleDateString(undefined, { month: 'short', day: 'numeric' });
+}
+/** Read the local SKILL.md content if it exists — for the `--from-disk` flag (Phase 2). */
+export async function readLocalSkillContent(slug) {
+    try {
+        return await readFile(join(CONFIG.skillsDir, slug, 'SKILL.md'), 'utf8');
+    }
+    catch {
+        return null;
+    }
+}

package/dist/commands/whoami.js

@@ -1,5 +1,15 @@
+import { ApiError, api } from '../lib/api.js';
 import { loadCredentials } from '../lib/credentials.js';
 import { log } from '../utils/logger.js';
+/**
+ * `prave whoami` — quick check that the local credentials still authenticate
+ * against the API. Hits `GET /api/v1/me` so the displayed name is always the
+ * server-side truth (and any stale local data gets refreshed implicitly via
+ * the auto-refresh path on api.get).
+ *
+ * If we can't reach the API (offline, server down) we fall back to the
+ * locally cached email so the command stays useful in airplane mode.
+ */
 export async function whoamiCommand() {
     const creds = await loadCredentials();
     if (!creds) {
@@ -7,7 +17,25 @@ export async function whoamiCommand() {
         process.exitCode = 1;
         return;
     }
-    log.kv('user_id', creds.user_id);
-    if (creds.email)
-        log.kv('email', creds.email);
+    try {
+        const { data } = await api.get('/api/v1/me', true);
+        const handle = data.username || data.display_name || data.email || creds.email || 'unknown';
+        log.kv('user', handle);
+        if (data.email)
+            log.kv('email', data.email);
+        log.kv('plan', data.plan);
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 401) {
+            log.warn('Session expired. Run `prave login` again.');
+            process.exitCode = 1;
+            return;
+        }
+        // Offline or transient API error — fall back to local creds so the
+        // command still does *something* useful instead of crashing.
+        if (creds.email)
+            log.kv('user', creds.email);
+        else
+            log.kv('user', creds.user_id);
+    }
 }

package/dist/index.js

@@ -19,6 +19,7 @@ import { searchCommand } from './commands/search.js';
 import { settingsCommand } from './commands/settings.js';
 import { syncCommand } from './commands/sync.js';
 import { uninstallCommand } from './commands/uninstall.js';
+import { updateCommand } from './commands/update.js';
 import { whatdoesCommand } from './commands/whatdoes.js';
 import { whoamiCommand } from './commands/whoami.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -33,8 +34,9 @@ program.command('whoami').description('Show the signed-in user').action(whoamiCo
 program
     .command('import')
     .description('Scan ~/.claude/skills/ — optionally upload to Prave')
-    .option('--upload', 'upload scanned skills')
-    .option('--private', 'upload as private (requires --upload)')
+    .option('--upload', 'upload scanned skills (requires --public or --private)')
+    .option('--public', 'upload as public (listed in the registry)')
+    .option('--private', 'upload as private (only you can see them)')
     .action(importCommand);
 program
     .command('install <slug>')
@@ -50,6 +52,12 @@ program
     .command('sync')
     .description('Pull updates for every locally installed Skill')
     .action(syncCommand);
+program
+    .command('update [slug]')
+    .description('Diff installed Skills against the registry and pull anything outdated')
+    .option('--dry-run', "preview what would change, don't write")
+    .option('--yes', 'skip confirmation prompt')
+    .action((slug, opts) => updateCommand(slug, opts));
 program
     .command('list')
     .description('List installed Skills (default) or remote ones')

package/dist/lib/api.js

@@ -1,6 +1,6 @@
 import { request } from 'undici';
 import { CONFIG } from './config.js';
-import { loadCredentials } from './credentials.js';
+import { loadCredentials, saveCredentials } from './credentials.js';
 export class ApiError extends Error {
     status;
     constructor(message, status) {
@@ -9,7 +9,52 @@ export class ApiError extends Error {
         this.name = 'ApiError';
     }
 }
-async function call(method, path, body, withAuth = false) {
+/**
+ * Single-flight refresh — multiple parallel requests all hitting 401 share
+ * one refresh round-trip instead of stampeding the API and burning the
+ * Supabase rate limiter.
+ */
+let refreshing = null;
+async function refreshTokens() {
+    if (refreshing)
+        return refreshing;
+    refreshing = (async () => {
+        const creds = await loadCredentials();
+        if (!creds?.refresh_token)
+            return null;
+        try {
+            const { statusCode, body } = await request(`${CONFIG.apiUrl}/api/v1/cli/refresh`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ refresh_token: creds.refresh_token }),
+            });
+            const text = await body.text();
+            if (statusCode !== 200)
+                return null;
+            const payload = JSON.parse(text);
+            if (!payload.success || !payload.data)
+                return null;
+            const next = {
+                ...creds,
+                access_token: payload.data.access_token,
+                refresh_token: payload.data.refresh_token ?? creds.refresh_token,
+                user_id: payload.data.user_id,
+            };
+            await saveCredentials(next);
+            return next;
+        }
+        catch {
+            return null;
+        }
+    })();
+    try {
+        return await refreshing;
+    }
+    finally {
+        refreshing = null;
+    }
+}
+async function call(method, path, body, withAuth = false, attempt = 0) {
     const headers = { 'Content-Type': 'application/json' };
     if (withAuth) {
         const creds = await loadCredentials();
@@ -26,6 +71,13 @@ async function call(method, path, body, withAuth = false) {
     if (statusCode === 204)
         return { data: undefined, status: statusCode };
     const payload = text ? JSON.parse(text) : { success: true, data: null, error: null };
+    // 401 with a refresh token on file → swap the access token and retry once.
+    // Any other status, or a second 401, falls through to the normal error path.
+    if (statusCode === 401 && withAuth && attempt === 0) {
+        const refreshed = await refreshTokens();
+        if (refreshed)
+            return call(method, path, body, withAuth, attempt + 1);
+    }
     if (statusCode >= 400 || payload.success === false) {
         throw new ApiError(payload.error ?? `HTTP ${statusCode}`, statusCode);
     }

package/dist/lib/credentials.js

@@ -23,3 +23,24 @@ export async function clearCredentials() {
         /* already gone */
     }
 }
+/**
+ * Gate for CLI commands that mutate Prave-side state or whose effect we
+ * need to track (installs, deploys, settings, intelligence). Search and
+ * read-only Discover paths are intentionally NOT gated — anyone can
+ * browse the public registry from the terminal.
+ *
+ * Prints a friendly hint and sets a non-zero exit code when the caller
+ * isn't logged in.
+ */
+export async function requireAuth(commandName) {
+    const creds = await loadCredentials();
+    if (creds)
+        return creds;
+    // Lazy-import the chalk/log utilities here to avoid a circular dep on
+    // the credentials module.
+    const { log } = await import('../utils/logger.js');
+    log.warn(`\`${commandName}\` requires sign-in.`);
+    log.dim('Run `prave login` first — installs are tracked against your account so we can keep counts honest.');
+    process.exitCode = 1;
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prave/cli",
-  "version": "0.4.8",
+  "version": "0.5.0",
   "description": "Prave CLI — import, export, install, sync Claude Skills.",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
     "open": "^10.1.0",
     "ora": "^8.0.1",
     "undici": "^6.18.0",
-    "@prave/shared": "0.3.1"
+    "@prave/shared": "0.4.0"
   },
   "devDependencies": {
     "@types/node": "^20.12.7",