@bytevion/cli 0.2.0 → 0.3.0

package/dist/base.js

@@ -6,6 +6,7 @@ const api_1 = require("./lib/api");
 const config_1 = require("./lib/config");
 const credentials_1 = require("./lib/credentials");
 const errors_1 = require("./lib/errors");
+const friendly_1 = require("./lib/friendly");
 class BaseCommand extends core_1.Command {
     static enableJsonFlag = true;
     static baseFlags = {
@@ -41,7 +42,13 @@ class BaseCommand extends core_1.Command {
     }
     async catch(err) {
         if (err instanceof errors_1.ByteError) {
-            return this.error(err.message, { code: err.code, exit: err.exit });
+            // --json callers want the machine-readable oclif error; humans get a panel that
+            // says what broke, why, and the exact next command — then we exit with the code.
+            if (this.jsonEnabled()) {
+                return this.error(err.message, { code: err.code, exit: err.exit });
+            }
+            this.logToStderr((0, friendly_1.renderErrorPanel)((0, friendly_1.friendlyError)(err)));
+            return this.exit(err.exit);
         }
         return super.catch(err);
     }

package/dist/commands/opt/preset.js

@@ -2,21 +2,24 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@oclif/core");
 const base_1 = require("../../base");
+const presets_1 = require("../../lib/presets");
 class OptPreset extends base_1.BaseCommand {
-    static description = 'Apply an optimization preset for the whole org.';
+    static description = 'Apply an optimization mode for the whole org (maximum, balanced, max_savings, lowest_latency, reliability_first).';
     static args = {
         preset: core_1.Args.string({
-            description: 'Preset to apply',
+            description: 'Mode to apply',
             required: true,
-            options: ['balanced', 'max_savings', 'lowest_latency', 'reliability_first'],
+            options: presets_1.PRESET_VALUES,
         }),
     };
     async run() {
         const { args, flags } = await this.parse(OptPreset);
         this.requireToken(flags);
         const res = await this.api(flags).optPatch({ default_mode: args.preset });
-        if (!this.jsonEnabled())
-            this.log(`Optimization preset set to "${args.preset}".`);
+        if (!this.jsonEnabled()) {
+            const card = (0, presets_1.presetCard)(args.preset);
+            this.log(`Optimization mode set to "${args.preset}".${card ? ` ${card.blurb}` : ''}`);
+        }
         return res;
     }
 }

package/dist/commands/opt/show.js

@@ -1,8 +1,13 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+const picocolors_1 = __importDefault(require("picocolors"));
 const base_1 = require("../../base");
+const presets_1 = require("../../lib/presets");
 class OptShow extends base_1.BaseCommand {
-    static description = 'Show the current optimization preset and layer states for the org.';
+    static description = 'Show the current optimization mode and every layer running on your requests.';
     async run() {
         const { flags } = await this.parse(OptShow);
         this.requireToken(flags);
@@ -10,14 +15,23 @@ class OptShow extends base_1.BaseCommand {
         if (this.jsonEnabled())
             return res;
         const settings = res.settings ?? res;
-        this.log(`Preset (default_mode): ${settings.default_mode ?? '-'}`);
-        this.log(`Cache mode:            ${settings.cache_mode ?? '-'}`);
+        const mode = settings.default_mode ?? '-';
+        const card = (0, presets_1.presetCard)(mode);
+        this.log('');
+        this.log(`  ${picocolors_1.default.bold('Optimization mode')}  ${picocolors_1.default.cyan(mode)}${card ? picocolors_1.default.dim(`  ${card.hint}`) : ''}`);
+        this.log(`  ${picocolors_1.default.bold('Cache mode')}         ${picocolors_1.default.cyan(settings.cache_mode ?? '-')}`);
         const layers = Array.isArray(res.layers) ? res.layers : [];
         if (layers.length) {
-            const enabled = layers.filter((l) => l.enabled).length;
-            this.log(`Layers enabled:        ${enabled}/${layers.length}`);
+            const on = layers.filter((l) => l.enabled).length;
+            this.log(`  ${picocolors_1.default.bold('Active layers')}      ${picocolors_1.default.green(String(on))}${picocolors_1.default.dim(`/${layers.length}`)} running on every request`);
+            this.log('');
+            for (const l of layers) {
+                const name = String(l.title ?? l.plain_label ?? l.key ?? 'layer');
+                this.log(l.enabled ? `  ${picocolors_1.default.green('●')} ${name}` : `  ${picocolors_1.default.dim('○')} ${picocolors_1.default.dim(name)}`);
+            }
         }
-        this.log('Run with --json for the full settings object.');
+        this.log('');
+        this.log(picocolors_1.default.dim('  Run with --json for the full settings object.'));
         return res;
     }
 }

package/dist/commands/setup.js

@@ -37,6 +37,7 @@ const core_1 = require("@oclif/core");
 const base_1 = require("../base");
 const auth_1 = require("../lib/auth");
 const credentials_1 = require("../lib/credentials");
+const presets_1 = require("../lib/presets");
 const providers_1 = require("../lib/providers");
 const tty_1 = require("../lib/tty");
 const ui = __importStar(require("../lib/ui"));
@@ -50,9 +51,9 @@ class Setup extends base_1.BaseCommand {
         'provider-base-url': core_1.Flags.string({ description: 'Custom provider base URL (for --provider custom)' }),
         mode: core_1.Flags.string({ description: 'Gateway mode override (byte_compatible/byte_messages/byte_generative)' }),
         preset: core_1.Flags.string({
-            description: 'Optimization preset',
-            options: ['balanced', 'max_savings', 'lowest_latency', 'reliability_first'],
-            default: 'balanced',
+            description: 'Optimization mode',
+            options: ['maximum', 'balanced', 'max_savings', 'lowest_latency', 'reliability_first'],
+            default: 'maximum',
         }),
         'key-name': core_1.Flags.string({ description: 'Name for the Byte key', default: 'cli' }),
         'skip-provider': core_1.Flags.boolean({ description: 'Skip connecting a provider' }),
@@ -82,37 +83,46 @@ class Setup extends base_1.BaseCommand {
             await (0, auth_1.deviceLogin)({ baseUrl: base, profile });
         }
         // 2) Connect a provider
-        let chosenAlias;
+        let provider = { status: 'skipped' };
         if (!flags['skip-provider']) {
             const existing = await api.providersList().catch(() => ({ connections: [] }));
             const conns = existing.connections ?? (Array.isArray(existing) ? existing : []);
             let addNew = true;
             if (conns.length) {
-                addNew = (await ui.select({
-                    message: 'Provider',
-                    options: [
-                        { value: 'existing', label: `Use existing connection (${conns.length})` },
-                        { value: 'new', label: 'Connect a new provider' },
-                    ],
-                })) === 'new';
+                addNew =
+                    (await ui.select({
+                        message: 'Provider',
+                        options: [
+                            { value: 'existing', label: `Use existing connection (${conns.length})` },
+                            { value: 'new', label: 'Connect a new provider' },
+                        ],
+                    })) === 'new';
+                if (!addNew)
+                    provider = { status: 'connected' };
             }
             if (addNew) {
-                chosenAlias = await this.connectProvider(api, flags);
+                provider = await this.connectProvider(api, flags);
             }
         }
-        // 3) Create a Byte key
+        // 3) Choose the optimization mode
+        const preset = await ui.select({
+            message: 'Optimization mode',
+            options: presets_1.PRESET_CARDS.map((c) => ({ value: c.value, label: c.label, hint: c.hint })),
+            initialValue: presets_1.PRESET_CARDS.some((c) => c.value === flags.preset) ? flags.preset : 'maximum',
+        });
+        // 4) Create a Byte key
         let byteKey = (0, credentials_1.getByteKey)(profile);
         if (!byteKey) {
             const name = await ui.text({ message: 'Name this Byte key', defaultValue: flags['key-name'] || 'cli' });
-            const res = await api.keysCreate({ name: name || 'cli', preset: flags.preset });
-            const created = String(res.key);
-            (0, credentials_1.setByteKey)(profile, created);
-            await ui.revealSecret('Your Byte API key', created);
+            const res = await api.keysCreate({ name: name || 'cli', preset });
+            byteKey = String(res.key);
+            (0, credentials_1.setByteKey)(profile, byteKey);
+            await ui.revealSecret('Your Byte API key', byteKey);
         }
-        // 4) Optimization preset
-        await api.optPatch({ default_mode: flags.preset }).catch(() => undefined);
-        await ui.log.success(`Optimizations: ${flags.preset} preset applied`);
-        // 5) Connect a tool
+        // 5) Apply the optimization mode to the org
+        await api.optPatch({ default_mode: preset }).catch(() => undefined);
+        await ui.log.success(`Optimizations: ${preset} mode applied — every layer this mode enables now runs on each request.`);
+        // 6) Connect a tool
         const connect = await ui.select({
             message: 'Connect a coding tool now?',
             options: [
@@ -126,11 +136,19 @@ class Setup extends base_1.BaseCommand {
             ],
         });
         if (connect !== 'skip') {
-            const argv = [connect, '--write', '--yes', ...(chosenAlias ? ['--model', chosenAlias] : [])];
+            const argv = [connect, '--write', '--yes', ...(provider.alias ? ['--model', provider.alias] : [])];
             await this.config.runCommand('integrate', argv);
         }
-        await ui.outro(`${ui.theme.ok('Setup complete.')}  Next: ${ui.theme.accent('byte run "hello from byte"')} · ${ui.theme.accent('byte usage')}`);
-        return { status: 'setup_complete', profile, model: chosenAlias };
+        // Accurate close-out — never claim a provider is wired when it is not.
+        const tips = [`${ui.theme.accent('byte run "hello from byte"')}`, `${ui.theme.accent('byte usage')}`];
+        if (provider.status === 'saved') {
+            await ui.note(`Your provider is saved but no model loaded yet. Fix the key/URL, then run ${ui.theme.accent('byte providers test')}.`, 'One thing left');
+        }
+        else if (provider.status === 'skipped' && !flags['skip-provider']) {
+            tips.unshift(`${ui.theme.accent('byte providers add')}`);
+        }
+        await ui.outro(`${ui.theme.ok('Setup complete.')}  Next: ${tips.join(' · ')}`);
+        return { status: 'setup_complete', profile, model: provider.alias, provider: provider.status, preset };
     }
     async connectProvider(api, flags) {
         const providerId = await ui.select({
@@ -151,27 +169,67 @@ class Setup extends base_1.BaseCommand {
         const key = await ui.password({ message: `${preset.label} API key`, validate: (v) => (v.trim() ? undefined : 'Required') });
         const spin = await ui.spinner();
         spin.start(`Connecting ${preset.label}…`);
+        let res;
         try {
-            const res = await api.providersAdd({ api_key: key, gateway_mode: flags.mode || preset.gateway_mode, base_url: baseUrl, auto_fetch: true });
-            const models = res.fetch_result?.models ?? res.models ?? [];
-            spin.stop(`Connected ${preset.label} — ${models.length} model(s) imported.`);
-            if (models.length) {
-                return ui.select({
-                    message: 'Default model',
-                    options: models.slice(0, 50).map((m) => ({ value: m.byte_alias, label: m.byte_alias, hint: m.model_id })),
-                });
-            }
+            res = await api.providersAdd({ api_key: key, gateway_mode: flags.mode || preset.gateway_mode, base_url: baseUrl, auto_fetch: true });
         }
         catch (err) {
-            spin.stop('Provider connection failed.');
+            spin.stop('Could not save the provider connection.');
             await ui.log.error(err?.message ?? String(err));
+            return { status: 'failed' };
+        }
+        const connId = res.id ?? res.connection?.id;
+        let fetchResult = res.fetch_result ?? {};
+        let models = res.models ?? fetchResult.models ?? [];
+        // Retry / keep / skip loop — a failed model import never silently passes as success.
+        for (;;) {
+            const failed = fetchResult.status === 'error' || Boolean(res.fetch_error) || Boolean(fetchResult.last_error);
+            if (!failed || models.length) {
+                spin.stop(`Connected ${preset.label} — ${models.length} model(s) imported.`);
+                break;
+            }
+            spin.stop(`Saved ${preset.label}, but its models could not be loaded.`);
+            await ui.log.warn(String(fetchResult.last_error || res.fetch_error || 'The provider URL or key looks unreachable right now.'));
+            const choice = await ui.select({
+                message: 'What would you like to do?',
+                options: [
+                    { value: 'retry', label: 'Re-enter the key and retry' },
+                    { value: 'keep', label: 'Keep it — I will pick a model later' },
+                    { value: 'skip', label: 'Skip the provider for now' },
+                ],
+            });
+            if (choice !== 'retry' || !connId)
+                return { status: choice === 'skip' ? 'skipped' : 'saved' };
+            const retryKey = await ui.password({ message: `${preset.label} API key`, validate: (v) => (v.trim() ? undefined : 'Required') });
+            spin.start('Retrying…');
+            try {
+                await api.providersRotate(connId, retryKey);
+                const test = await api.providersTest(connId);
+                models = test.models ?? [];
+                fetchResult = { status: models.length ? 'ok' : 'error', last_error: models.length ? null : 'No models returned.' };
+                res = { ...res, fetch_error: undefined };
+            }
+            catch (err) {
+                models = [];
+                fetchResult = { status: 'error', last_error: err?.message ?? String(err) };
+                res = { ...res, fetch_error: undefined };
+            }
+        }
+        if (models.length) {
+            const alias = await ui.select({
+                message: 'Default model',
+                options: models.slice(0, 50).map((m) => ({ value: m.byte_alias, label: m.byte_alias, hint: m.model_id })),
+            });
+            return { alias, status: 'connected' };
         }
-        return undefined;
+        return { status: 'saved' };
     }
     async runNonInteractive(flags, profile, base) {
         this.requireToken(flags);
         const api = this.api(flags);
         let imported = 0;
+        let providerStatus = flags['skip-provider'] ? 'skipped' : 'skipped';
+        let providerError;
         let chosenAlias;
         const key = flags['provider-key'];
         if (key && !flags['skip-provider']) {
@@ -182,20 +240,38 @@ class Setup extends base_1.BaseCommand {
                 return this.error('Provide --provider <preset> or --provider-base-url for the upstream provider.', { exit: 2 });
             }
             const res = await api.providersAdd({ api_key: key, gateway_mode: mode, base_url: baseUrl, auto_fetch: true });
-            imported = res.fetch_result?.imported ?? res.imported ?? 0;
-            chosenAlias = res.fetch_result?.models?.[0]?.byte_alias;
+            const fetchResult = res.fetch_result ?? {};
+            imported = fetchResult.imported ?? res.imported ?? 0;
+            chosenAlias = res.models?.[0]?.byte_alias;
+            if (fetchResult.status === 'error' || res.fetch_error) {
+                providerStatus = 'saved';
+                providerError = String(fetchResult.last_error || res.fetch_error);
+            }
+            else {
+                providerStatus = 'connected';
+            }
         }
         await api.optPatch({ default_mode: flags.preset }).catch(() => undefined);
         const keyRes = await api.keysCreate({ name: flags['key-name'] || 'cli', preset: flags.preset });
         (0, credentials_1.setByteKey)(profile, keyRes.key);
         if (flags.connect) {
-            await this.config.runCommand('integrate', [flags.connect, '--write', '--yes', ...(chosenAlias ? ['--model', chosenAlias] : [])]);
+            const argv = [flags.connect, '--write', '--yes', ...(chosenAlias ? ['--model', chosenAlias] : [])];
+            await this.config.runCommand('integrate', argv);
         }
         if (!this.jsonEnabled()) {
             this.log(`Byte key: ${keyRes.key}`);
             this.log(`Provider models imported: ${imported}`);
+            if (providerStatus === 'saved')
+                this.log(`Provider saved but models not loaded: ${providerError ?? 'unreachable'}. Run \`byte providers test\`.`);
         }
-        return { byte_key: keyRes.key, provider_models_imported: imported, preset: flags.preset, model: chosenAlias };
+        return {
+            byte_key: keyRes.key,
+            provider_models_imported: imported,
+            provider: providerStatus,
+            provider_error: providerError,
+            preset: flags.preset,
+            model: chosenAlias,
+        };
     }
 }
 exports.default = Setup;

package/dist/commands/usage.js

@@ -16,16 +16,40 @@ class Usage extends base_1.BaseCommand {
             return res;
         const points = res.series ?? res.points ?? (Array.isArray(res) ? res : []);
         if (!points.length) {
-            this.log('No usage recorded yet.');
+            this.log('No usage recorded yet. Send a request through your Byte key, then check back.');
             return res;
         }
-        this.log((0, output_1.renderTable)(['Bucket', 'Requests', 'Tokens', 'Cost', 'Savings'], points.map((p) => [
-            p.bucket ?? p.date ?? p.t ?? '-',
-            p.requests ?? p.total_requests ?? '-',
-            p.tokens ?? p.total_tokens ?? '-',
-            (0, output_1.fmtUsd)(p.cost_usd ?? p.cost_byte_usd),
-            (0, output_1.fmtUsd)(p.savings_usd),
-        ])));
+        const num = (v) => {
+            const n = typeof v === 'number' ? v : Number(v);
+            return Number.isFinite(n) ? n : 0;
+        };
+        const tokensOf = (p) => num(p.tokens_in) + num(p.tokens_out);
+        const rows = points.map((p) => [
+            (0, output_1.fmtBucket)(p.timestamp ?? p.bucket ?? p.date),
+            (0, output_1.fmtNum)(num(p.requests)),
+            (0, output_1.fmtNum)(num(p.cached)),
+            (0, output_1.fmtNum)(tokensOf(p)),
+            (0, output_1.fmtUsd)(num(p.cost_byte_usd ?? p.cost_usd)),
+            (0, output_1.fmtUsd)(num(p.savings_usd)),
+        ]);
+        const totals = {
+            requests: points.reduce((a, p) => a + num(p.requests), 0),
+            cached: points.reduce((a, p) => a + num(p.cached), 0),
+            tokens: points.reduce((a, p) => a + tokensOf(p), 0),
+            cost: points.reduce((a, p) => a + num(p.cost_byte_usd ?? p.cost_usd), 0),
+            savings: points.reduce((a, p) => a + num(p.savings_usd), 0),
+            raw: points.reduce((a, p) => a + num(p.cost_raw_usd), 0),
+        };
+        rows.push(['Total', (0, output_1.fmtNum)(totals.requests), (0, output_1.fmtNum)(totals.cached), (0, output_1.fmtNum)(totals.tokens), (0, output_1.fmtUsd)(totals.cost), (0, output_1.fmtUsd)(totals.savings)]);
+        this.log((0, output_1.renderTable)(['Bucket', 'Requests', 'Cached', 'Tokens', 'Cost', 'Savings'], rows));
+        const plain = Boolean(process.env.NO_COLOR) || process.env.BYTE_PLAIN === '1';
+        const spark = (0, output_1.sparkline)(points.map((p) => num(p.savings_usd)), plain);
+        if (spark)
+            this.log(`\nSavings trend  ${spark}`);
+        const savedPct = totals.raw > 0 ? (0, output_1.pct)(totals.savings / totals.raw) : null;
+        const hitRate = totals.requests > 0 ? (0, output_1.pct)(totals.cached / totals.requests) : null;
+        this.log(`Saved ${(0, output_1.fmtUsd)(totals.savings)}${savedPct ? ` (${savedPct})` : ''} across ${(0, output_1.fmtNum)(totals.requests)} requests` +
+            `${hitRate ? `, cache hit rate ${hitRate}` : ''}.`);
         return res;
     }
 }

package/dist/hooks/init/home.js

@@ -33,13 +33,15 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+const api_1 = require("../../lib/api");
 const config_1 = require("../../lib/config");
 const credentials_1 = require("../../lib/credentials");
+const home_1 = require("../../lib/home");
 const tty_1 = require("../../lib/tty");
 const ui = __importStar(require("../../lib/ui"));
 // oclif runs init hooks before it would print help. Bare `byte` (no command) in a real
-// terminal opens an interactive home menu; anything else (a command, a pipe, CI, --help)
-// returns and lets oclif behave normally.
+// terminal opens the live home dashboard + an interactive menu; anything else (a command,
+// a pipe, CI, --help) returns and lets oclif behave normally.
 const hook = async function (opts) {
     if (opts.id !== undefined)
         return;
@@ -50,9 +52,19 @@ const hook = async function (opts) {
         return;
     const profile = (0, config_1.profileName)();
     const prof = (0, config_1.getProfile)(profile);
-    const signedIn = Boolean((0, credentials_1.getToken)(profile));
-    const status = signedIn ? ui.theme.muted(`signed in · ${prof.email ?? prof.org_name ?? profile}`) : ui.theme.muted('not signed in');
-    await ui.intro(`${ui.banner()}   ${status}`);
+    const token = (0, credentials_1.getToken)(profile);
+    const signedIn = Boolean(token);
+    const byteKey = (0, credentials_1.getByteKey)(profile);
+    // Live, branded home dashboard. Every cell is best-effort: an unreachable service or a
+    // signed-out profile degrades to a dim placeholder rather than blocking the screen.
+    let data = { savingsSeries: [], savedTotal: 0, tokensTotal: 0, byteKey, gateway: 'unknown' };
+    if (signedIn) {
+        const api = new api_1.ByteApi(prof.base_url || config_1.DEFAULT_BASE_URL, token);
+        const loaded = await (0, home_1.loadHomeData)(api, byteKey, profile).catch(() => undefined);
+        if (loaded)
+            data = { ...data, ...loaded };
+    }
+    this.log(`\n${(0, home_1.renderHome)(data, signedIn)}\n`);
     const choice = await ui.select({
         message: 'What would you like to do?',
         initialValue: signedIn ? 'setup' : 'login',

package/dist/lib/friendly.d.ts

@@ -0,0 +1,8 @@
+import { ByteError } from './errors';
+export interface Friendly {
+    issue: string;
+    why: string;
+    next: string;
+}
+export declare function friendlyError(err: ByteError): Friendly;
+export declare function renderErrorPanel(f: Friendly): string;

package/dist/lib/friendly.js

@@ -0,0 +1,86 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.friendlyError = friendlyError;
+exports.renderErrorPanel = renderErrorPanel;
+const picocolors_1 = __importDefault(require("picocolors"));
+// Translates a ByteError (HTTP status + BYTE_* / provider detail code) into plain
+// language a first-time user can act on: what happened, why, and the exact next
+// command. The goal is that no error ever leaves someone stuck.
+function friendlyError(err) {
+    const code = (err.code || '').toUpperCase();
+    const status = err.status;
+    const byCode = {
+        BYTE_AUTH_REQUIRED: {
+            issue: 'You are not signed in yet.',
+            why: 'This command needs your Byte account.',
+            next: 'byte login',
+        },
+        BYTE_KEY_REQUIRED: {
+            issue: 'This profile has no Byte API key.',
+            why: 'Requests run through a Byte key so every optimization applies automatically.',
+            next: 'byte keys create',
+        },
+        BYTE_API_OFFLINE: {
+            issue: 'Could not reach the Byte service.',
+            why: 'You may be offline, or the base URL is pointed somewhere unexpected.',
+            next: 'byte doctor',
+        },
+        BYTE_MODEL_FETCH_FAILED: {
+            issue: 'Your provider was saved, but its model list could not be loaded.',
+            why: 'The provider URL or key looks unreachable right now — your connection is still saved.',
+            next: 'byte providers test',
+        },
+        BYTE_DEVICE_DENIED: {
+            issue: 'Sign-in was declined in the browser.',
+            why: 'The device approval was rejected or closed.',
+            next: 'byte login',
+        },
+        BYTE_DEVICE_EXPIRED: {
+            issue: 'The sign-in code expired.',
+            why: 'It was not approved in time.',
+            next: 'byte login',
+        },
+    };
+    if (byCode[code])
+        return byCode[code];
+    if (status === 0) {
+        return { issue: 'Could not reach the Byte service.', why: 'You may be offline.', next: 'byte doctor' };
+    }
+    if (status === 401 || status === 403) {
+        return { issue: 'Your session or key was rejected.', why: 'It may have expired, been revoked, or be missing a scope.', next: 'byte login' };
+    }
+    if (status === 404) {
+        return {
+            issue: 'That route or model was not found.',
+            why: 'The model may not be wired to your key, or the surface (e.g. /v1/messages) is not enabled for it.',
+            next: 'byte doctor',
+        };
+    }
+    if (status === 429) {
+        return { issue: 'Rate limit reached.', why: 'Too many requests landed in a short window.', next: 'wait a few seconds, then retry' };
+    }
+    if (status && status >= 500) {
+        return {
+            issue: 'The service hit an error finishing your request.',
+            why: 'This is on the Byte side, not your input — your key and provider are fine.',
+            next: 'byte doctor   (then retry shortly)',
+        };
+    }
+    return { issue: err.message || 'Something went wrong.', why: `Error code: ${err.code}`, next: 'byte doctor' };
+}
+// A compact, left-accent error panel. picocolors auto-disables under NO_COLOR, so this
+// degrades to clean monochrome text in plain terminals.
+function renderErrorPanel(f) {
+    const bar = picocolors_1.default.red('▌');
+    const lines = [
+        `${bar} ${picocolors_1.default.bold(picocolors_1.default.red('Byte hit a problem'))}`,
+        `${bar} ${f.issue}`,
+        `${bar}`,
+        `${bar} ${picocolors_1.default.dim('Why ')}  ${f.why}`,
+        `${bar} ${picocolors_1.default.dim('Next')}  ${picocolors_1.default.cyan(f.next)}`,
+    ];
+    return `\n${lines.join('\n')}\n`;
+}

package/dist/lib/home.d.ts

@@ -0,0 +1,16 @@
+import { ByteApi } from './api';
+export declare function wordmark(): string;
+export interface HomeData {
+    email?: string;
+    org?: string;
+    providers?: number;
+    models?: number;
+    byteKey?: string;
+    gateway?: 'healthy' | 'down' | 'unknown';
+    savingsSeries: number[];
+    savedTotal: number;
+    tokensTotal: number;
+    hitRate?: number;
+}
+export declare function loadHomeData(api: ByteApi, byteKey: string | undefined, fallbackId: string): Promise<HomeData>;
+export declare function renderHome(data: HomeData, signedIn: boolean): string;

package/dist/lib/home.js

@@ -0,0 +1,97 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wordmark = wordmark;
+exports.loadHomeData = loadHomeData;
+exports.renderHome = renderHome;
+const picocolors_1 = __importDefault(require("picocolors"));
+const output_1 = require("./output");
+const ANSI = /\x1b\[[0-9;]*m/g;
+const visLen = (s) => s.replace(ANSI, '').length;
+const plainMode = () => Boolean(process.env.NO_COLOR) || process.env.BYTE_PLAIN === '1';
+// Cyan→blue gradient wordmark. picocolors has no true gradient, so we step the letters
+// across a cyan→blue ramp — a recognizable Byte signature that degrades to plain text.
+function wordmark() {
+    const mark = `${picocolors_1.default.dim('›')}${picocolors_1.default.bold(picocolors_1.default.cyanBright('b'))}${picocolors_1.default.dim('_')}`;
+    if (plainMode())
+        return `${mark} BYTE`;
+    const ramp = [picocolors_1.default.cyanBright, picocolors_1.default.cyan, picocolors_1.default.blue, picocolors_1.default.blueBright];
+    const name = 'BYTE'
+        .split('')
+        .map((ch, i) => picocolors_1.default.bold(ramp[i % ramp.length](ch)))
+        .join('');
+    return `${mark}  ${name}`;
+}
+function box(lines, pad = 2) {
+    const inner = Math.max(...lines.map(visLen));
+    const horiz = '─'.repeat(inner + pad * 2);
+    const body = lines.map((l) => `${picocolors_1.default.dim('│')}${' '.repeat(pad)}${l}${' '.repeat(inner - visLen(l) + pad)}${picocolors_1.default.dim('│')}`);
+    return [picocolors_1.default.dim(`╭${horiz}╮`), ...body, picocolors_1.default.dim(`╰${horiz}╯`)].join('\n');
+}
+function withTimeout(p, ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(undefined), ms);
+        if (typeof timer.unref === 'function')
+            timer.unref();
+        p.then((v) => {
+            clearTimeout(timer);
+            resolve(v);
+        }, () => {
+            clearTimeout(timer);
+            resolve(undefined);
+        });
+    });
+}
+// Fetches everything bare `byte` shows, in parallel, each guarded by a short timeout so a
+// slow or unreachable service never blocks the home screen — missing cells just render dim.
+async function loadHomeData(api, byteKey, fallbackId) {
+    const [me, provs, usage, health] = await Promise.all([
+        withTimeout(api.me(), 4000),
+        withTimeout(api.providersList(), 4000),
+        withTimeout(api.usage('day'), 4000),
+        withTimeout(api.health(), 3000),
+    ]);
+    const conns = provs?.connections ?? (Array.isArray(provs) ? provs : []);
+    const models = conns.reduce((a, c) => a + (Number(c.models ?? c.model_count ?? 0) || 0), 0);
+    const series = usage?.series ?? [];
+    const num = (v) => {
+        const n = typeof v === 'number' ? v : Number(v);
+        return Number.isFinite(n) ? n : 0;
+    };
+    const requests = series.reduce((a, p) => a + num(p.requests), 0);
+    const cached = series.reduce((a, p) => a + num(p.cached), 0);
+    return {
+        email: me?.user?.email,
+        org: me?.org?.name ?? me?.user?.org_name,
+        providers: conns.length || undefined,
+        models: models || undefined,
+        byteKey,
+        gateway: health ? (health.status === 'ok' || health.ok ? 'healthy' : 'down') : 'unknown',
+        savingsSeries: series.map((p) => num(p.savings_usd)),
+        savedTotal: series.reduce((a, p) => a + num(p.savings_usd), 0),
+        tokensTotal: series.reduce((a, p) => a + num(p.tokens_in) + num(p.tokens_out), 0),
+        hitRate: requests > 0 ? cached / requests : undefined,
+    };
+}
+function renderHome(data, signedIn) {
+    const dim = picocolors_1.default.dim;
+    const label = (s) => dim(s.padEnd(10));
+    const dash = dim('—');
+    const gatewayDot = data.gateway === 'healthy' ? `${picocolors_1.default.green('●')} healthy` : data.gateway === 'down' ? `${picocolors_1.default.red('●')} unreachable` : dim('● unknown');
+    const lines = [
+        `${wordmark()}${' '.repeat(6)}${dim('optimization gateway')}`,
+        '',
+        `${label('Account')}${signedIn ? `${data.email ?? 'you'}${data.org ? `  ${dim('·')}  ${data.org}` : ''}` : picocolors_1.default.yellow('not signed in')}`,
+        `${label('Providers')}${data.providers ? `${data.providers} connected${data.models ? `  ${dim('·')}  ${data.models} models` : ''}` : dash}`,
+        `${label('Byte key')}${data.byteKey ? picocolors_1.default.cyan((0, output_1.maskKey)(data.byteKey)) : dash}`,
+        `${label('Gateway')}${gatewayDot}`,
+    ];
+    if (data.savingsSeries.some((v) => v > 0) || data.savedTotal > 0) {
+        const spark = (0, output_1.sparkline)(data.savingsSeries, plainMode());
+        const summary = `${picocolors_1.default.green((0, output_1.fmtUsd)(data.savedTotal))} saved  ${dim('·')}  ${(0, output_1.fmtNum)(data.tokensTotal)} tokens${data.hitRate !== undefined ? `  ${dim('·')}  ${(0, output_1.pct)(data.hitRate)} cache hits` : ''}`;
+        lines.push('', `${label('7-day')}${picocolors_1.default.cyan(spark)}  ${summary}`);
+    }
+    return box(lines);
+}

package/dist/lib/output.d.ts

@@ -2,3 +2,6 @@ export declare function renderTable(head: string[], rows: Array<Array<string | n
 export declare function maskKey(value: string | undefined): string;
 export declare function fmtUsd(value: unknown): string;
 export declare function pct(value: unknown): string;
+export declare function fmtNum(value: unknown): string;
+export declare function fmtBucket(value: unknown): string;
+export declare function sparkline(values: number[], plain?: boolean): string;

package/dist/lib/output.js

@@ -7,6 +7,9 @@ exports.renderTable = renderTable;
 exports.maskKey = maskKey;
 exports.fmtUsd = fmtUsd;
 exports.pct = pct;
+exports.fmtNum = fmtNum;
+exports.fmtBucket = fmtBucket;
+exports.sparkline = sparkline;
 const cli_table3_1 = __importDefault(require("cli-table3"));
 function renderTable(head, rows) {
     const table = new cli_table3_1.default({ head });
@@ -35,3 +38,43 @@ function pct(value) {
     const scaled = n <= 1 ? n * 100 : n;
     return `${scaled.toFixed(1)}%`;
 }
+// 1234 -> "1.2K", 1_500_000 -> "1.5M". Keeps small counts exact.
+function fmtNum(value) {
+    const n = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(n))
+        return '-';
+    const abs = Math.abs(n);
+    if (abs >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (abs >= 1_000)
+        return `${(n / 1_000).toFixed(1)}K`;
+    return String(Math.round(n));
+}
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+// "2026-05-30" -> "May 30"; "2026-05-30T14:00:00Z" -> "May 30 14:00".
+function fmtBucket(value) {
+    if (typeof value !== 'string' || !value)
+        return '-';
+    const m = value.match(/^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):)?/);
+    if (!m)
+        return value;
+    const mon = MONTHS[Number(m[2]) - 1] ?? m[2];
+    const day = String(Number(m[3]));
+    return m[4] ? `${mon} ${day} ${m[4]}:00` : `${mon} ${day}`;
+}
+// Unicode block sparkline with an ASCII fallback for legacy terminals (NO_COLOR/conhost).
+function sparkline(values, plain = false) {
+    const nums = values.map((v) => (Number.isFinite(v) ? v : 0));
+    if (!nums.length)
+        return '';
+    const ramp = plain ? '.:-=+*#'.split('') : '▁▂▃▄▅▆▇█'.split('');
+    const max = Math.max(...nums);
+    const min = Math.min(...nums);
+    const span = max - min || 1;
+    return nums
+        .map((v) => {
+        const idx = Math.round(((v - min) / span) * (ramp.length - 1));
+        return ramp[Math.max(0, Math.min(ramp.length - 1, idx))];
+    })
+        .join('');
+}

package/dist/lib/presets.d.ts

@@ -0,0 +1,9 @@
+export interface PresetCard {
+    value: string;
+    label: string;
+    hint: string;
+    blurb: string;
+}
+export declare const PRESET_CARDS: PresetCard[];
+export declare const PRESET_VALUES: string[];
+export declare function presetCard(value: string): PresetCard | undefined;

package/dist/lib/presets.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRESET_VALUES = exports.PRESET_CARDS = void 0;
+exports.presetCard = presetCard;
+exports.PRESET_CARDS = [
+    {
+        value: 'maximum',
+        label: 'Maximum — everything on (recommended)',
+        hint: 'best savings + quality',
+        blurb: 'Every production-safe optimization runs on every request: full caching, compression, routing, and quality guards.',
+    },
+    {
+        value: 'max_savings',
+        label: 'Maximum savings',
+        hint: 'cheapest',
+        blurb: 'Leans hardest on caching, compression, and cheaper routing to cut spend the most.',
+    },
+    {
+        value: 'balanced',
+        label: 'Balanced',
+        hint: 'savings + speed',
+        blurb: 'A middle ground: strong savings without the deepest latency-adding passes.',
+    },
+    {
+        value: 'lowest_latency',
+        label: 'Lowest latency',
+        hint: 'fastest',
+        blurb: 'Skips the heavier passes so responses come back as fast as possible.',
+    },
+    {
+        value: 'reliability_first',
+        label: 'Reliability first',
+        hint: 'most robust',
+        blurb: 'Prioritizes verification, repair, and fallbacks over maximum savings.',
+    },
+];
+exports.PRESET_VALUES = exports.PRESET_CARDS.map((c) => c.value);
+function presetCard(value) {
+    return exports.PRESET_CARDS.find((c) => c.value === value);
+}

package/dist/lib/ui.js

@@ -32,8 +32,20 @@ exports.theme = {
     muted: (s) => picocolors_1.default.dim(s),
     bold: (s) => picocolors_1.default.bold(s),
 };
+// The Byte signature: a `›b_` prompt glyph and a cyan→blue gradient wordmark. picocolors
+// has no true gradient, so the letters step across a cyan→blue ramp; degrades to plain
+// text under NO_COLOR/BYTE_PLAIN. Kept in sync with the home dashboard wordmark.
 function banner() {
-    return `${picocolors_1.default.dim('>')}${picocolors_1.default.bold(picocolors_1.default.cyan('b'))}${picocolors_1.default.dim('_')}  ${picocolors_1.default.bold('Byte')}`;
+    const plain = Boolean(process.env.NO_COLOR) || process.env.BYTE_PLAIN === '1';
+    const mark = `${picocolors_1.default.dim('›')}${picocolors_1.default.bold(picocolors_1.default.cyanBright('b'))}${picocolors_1.default.dim('_')}`;
+    if (plain)
+        return `${mark} BYTE`;
+    const ramp = [picocolors_1.default.cyanBright, picocolors_1.default.cyan, picocolors_1.default.blue, picocolors_1.default.blueBright];
+    const name = 'BYTE'
+        .split('')
+        .map((ch, i) => picocolors_1.default.bold(ramp[i % ramp.length](ch)))
+        .join('');
+    return `${mark}  ${name}`;
 }
 function guard(value, c) {
     if (c.isCancel(value)) {

package/oclif.manifest.json

@@ -609,12 +609,13 @@
           "type": "option"
         },
         "preset": {
-          "description": "Optimization preset",
+          "description": "Optimization mode",
           "name": "preset",
-          "default": "balanced",
+          "default": "maximum",
           "hasDynamicHelp": false,
           "multiple": false,
           "options": [
+            "maximum",
             "balanced",
             "max_savings",
             "lowest_latency",
@@ -1198,118 +1199,23 @@
         "rotate.js"
       ]
     },
-    "sessions": {
-      "aliases": [],
-      "args": {},
-      "description": "List active terminal sessions (CLI tokens) for the org.",
-      "flags": {
-        "json": {
-          "description": "Format output as json.",
-          "helpGroup": "GLOBAL",
-          "name": "json",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "profile": {
-          "description": "Configuration profile to use",
-          "env": "BYTE_PROFILE",
-          "name": "profile",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "base-url": {
-          "description": "Override the API base URL",
-          "env": "BYTE_BASE_URL",
-          "name": "base-url",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        }
-      },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "sessions",
-      "pluginAlias": "@bytevion/cli",
-      "pluginName": "@bytevion/cli",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": true,
-      "isESM": false,
-      "relativePath": [
-        "dist",
-        "commands",
-        "sessions",
-        "index.js"
-      ]
-    },
-    "sessions:revoke": {
-      "aliases": [],
-      "args": {
-        "id": {
-          "description": "Session id (see `byte sessions`)",
-          "name": "id",
-          "required": true
-        }
-      },
-      "description": "Revoke a terminal session (CLI token) by id.",
-      "flags": {
-        "json": {
-          "description": "Format output as json.",
-          "helpGroup": "GLOBAL",
-          "name": "json",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "profile": {
-          "description": "Configuration profile to use",
-          "env": "BYTE_PROFILE",
-          "name": "profile",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "base-url": {
-          "description": "Override the API base URL",
-          "env": "BYTE_BASE_URL",
-          "name": "base-url",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        }
-      },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "sessions:revoke",
-      "pluginAlias": "@bytevion/cli",
-      "pluginName": "@bytevion/cli",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": true,
-      "isESM": false,
-      "relativePath": [
-        "dist",
-        "commands",
-        "sessions",
-        "revoke.js"
-      ]
-    },
     "opt:preset": {
       "aliases": [],
       "args": {
         "preset": {
-          "description": "Preset to apply",
+          "description": "Mode to apply",
           "name": "preset",
           "options": [
-            "balanced",
+            "maximum",
             "max_savings",
+            "balanced",
             "lowest_latency",
             "reliability_first"
           ],
           "required": true
         }
       },
-      "description": "Apply an optimization preset for the whole org.",
+      "description": "Apply an optimization mode for the whole org (maximum, balanced, max_savings, lowest_latency, reliability_first).",
       "flags": {
         "json": {
           "description": "Format output as json.",
@@ -1420,7 +1326,7 @@
     "opt:show": {
       "aliases": [],
       "args": {},
-      "description": "Show the current optimization preset and layer states for the org.",
+      "description": "Show the current optimization mode and every layer running on your requests.",
       "flags": {
         "json": {
           "description": "Format output as json.",
@@ -1707,7 +1613,103 @@
         "providers",
         "test.js"
       ]
+    },
+    "sessions": {
+      "aliases": [],
+      "args": {},
+      "description": "List active terminal sessions (CLI tokens) for the org.",
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "profile": {
+          "description": "Configuration profile to use",
+          "env": "BYTE_PROFILE",
+          "name": "profile",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "base-url": {
+          "description": "Override the API base URL",
+          "env": "BYTE_BASE_URL",
+          "name": "base-url",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "sessions",
+      "pluginAlias": "@bytevion/cli",
+      "pluginName": "@bytevion/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": false,
+      "relativePath": [
+        "dist",
+        "commands",
+        "sessions",
+        "index.js"
+      ]
+    },
+    "sessions:revoke": {
+      "aliases": [],
+      "args": {
+        "id": {
+          "description": "Session id (see `byte sessions`)",
+          "name": "id",
+          "required": true
+        }
+      },
+      "description": "Revoke a terminal session (CLI token) by id.",
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "profile": {
+          "description": "Configuration profile to use",
+          "env": "BYTE_PROFILE",
+          "name": "profile",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "base-url": {
+          "description": "Override the API base URL",
+          "env": "BYTE_BASE_URL",
+          "name": "base-url",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "sessions:revoke",
+      "pluginAlias": "@bytevion/cli",
+      "pluginName": "@bytevion/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": false,
+      "relativePath": [
+        "dist",
+        "commands",
+        "sessions",
+        "revoke.js"
+      ]
     }
   },
-  "version": "0.2.0"
+  "version": "0.3.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytevion/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Byte — control your LLM optimization gateway from the terminal.",
   "author": "Byte",
   "license": "UNLICENSED",