@rankwrangler/cli 0.4.1 → 0.6.0

package/README.md

@@ -11,21 +11,33 @@ npm install -g @rankwrangler/cli
 ## Usage
 
 ```bash
-export RR_LICENSE_KEY=rrk_...
 rw --version
 rw changelog
+rw auth set rrk_...
+printf %s "$RR_LICENSE_KEY" | rw auth set --stdin
 rw config set storage-dir ~/.config/rankwrangler
+rw config get marketplace
+rw config unset marketplace
 rw products get B0DV53VS61
-rw products history B0DV53VS61 --metrics bsr,price
+rw products history B0DV53VS61 --metrics bsr,price --bucket week
+RR_LICENSE_KEY=rrk_... rw license status
 # `rankwrangler` is also supported as an alias
 ```
 
-`RR_LICENSE_KEY` is the API-key source. `rw config set storage-dir <path>` saves the
-active storage directory globally. After that, every CLI command reads and writes its non-secret
-config/data from that directory, while preserving existing config values when switching.
-`RR_STORAGE_DIR`, `RR_API_URL`, and `RR_MARKETPLACE_ID` override saved CLI config when set.
-`rw --version` prints the installed CLI version. `rw changelog` prints the latest bundled release
-notes shipped with the package.
+`rw auth set [licenseKey]` stores the license key in the platform secure store
+(`macOS Keychain` on macOS). `rw auth status` reports whether the CLI will use an env override,
+stored auth, or no auth. `rw auth set --stdin` reads the key from standard input for agents and
+scripts. `rw auth clear` removes the stored key.
+
+`rw config set storage-dir <path>` saves the active storage directory globally. After that, every
+CLI command reads and writes its non-secret config/data from that directory, while preserving
+existing config values when switching. `rw config get <key>`, `rw config unset <key>`, and
+`rw config reset` inspect or remove non-secret config without touching stored auth.
+`RR_LICENSE_KEY`, `RR_STORAGE_DIR`, `RR_API_URL`, and `RR_MARKETPLACE_ID` override saved CLI state
+when set for CI, automation, or agent runtimes.
+`rw products history` ensures product/history data before returning bucketed history (`auto`,
+`day`, `week`, or `month`), not raw point series. `rw --version` prints the installed CLI version.
+`rw changelog` prints the latest bundled release notes shipped with the package.
 
 ## Development
 
@@ -55,9 +67,9 @@ matching `@rankwrangler/http-client` version is already available on npm.
 
 ```bash
 cd packages/cli
-set -a
-source ../../.env
-set +a
-npm whoami --userconfig ../../.npmrc
-npm publish --access public --userconfig ../../.npmrc
+node ../../scripts/release/with-npm-token.mjs npm whoami --userconfig ../../.npmrc
+node ../../scripts/release/with-npm-token.mjs npm publish --access public --userconfig ../../.npmrc
 ```
+
+On macOS, the helper reads `NPM_TOKEN` from the environment first and otherwise falls back to the
+Keychain item `rankwrangler-npm-token` for account `$USER`.

package/dist/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to this project will be documented in this file.
 
+## v0.6.0 - 2026-06-15
+
+### Added
+
+- Add `rw auth set --stdin` and hidden local auth entry so agents can pipe license keys and humans
+  can avoid shell history.
+- Add `rw config get`, `rw config unset`, and `rw config reset` for explicit non-secret config
+  inspection and cleanup.
+
+### Changed
+
+- Show auth source/status in `rw config show` without printing secrets.
+- Update CLI help, README, CLI spec, and e2e coverage for the clearer auth/config surface.
+
+### Removed
+
+- Remove `rw config clear` in favor of `rw config unset <key>` and `rw config reset`.
+
+## v0.5.0 - 2026-03-18
+
+### Added
+
+- Add CLI secure-store auth with `rw auth set`, `rw auth status`, and `rw auth clear`, storing
+  license keys in the platform secure store while keeping `RR_LICENSE_KEY` as an override for
+  CI, automation, and agent runtimes.
+
+### Changed
+
+- Change local development defaults so the app server no longer starts the job runner unless you
+  use the explicit jobs-enabled dev commands.
+
+### Fixed
+
+- Fix top search terms scheduler timestamp handling so due datasets are selected and refreshed
+  reliably.
+
 ## v0.4.1 - 2026-03-09
 
 ### Added

package/dist/cli-auth.d.ts

@@ -0,0 +1,112 @@
+export declare const LICENSE_KEY_ENV_VAR = "RR_LICENSE_KEY";
+export declare const AUTH_SERVICE_NAME = "RankWrangler CLI";
+export declare const AUTH_ACCOUNT_NAME = "license-key";
+type CliFail = (code: string, message: string, details?: unknown) => never;
+type AuthCommand = {
+    verb: string;
+    args: string[];
+};
+type AuthCommandOptions = {
+    stdin?: boolean;
+};
+export declare class CliAuthError extends Error {
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(code: string, message: string, details?: unknown);
+}
+export declare const resolveApiKey: () => Promise<string | undefined>;
+export declare const runAuthCommand: (command: AuthCommand, fail: CliFail, options?: AuthCommandOptions) => Promise<{
+    source: string;
+    envOverride: boolean;
+    secureStore: {
+        backend: string;
+        serviceName: string;
+        accountName: string;
+        available: boolean;
+        hasStoredLicenseKey: boolean;
+        error?: undefined;
+    };
+} | {
+    source: string;
+    envOverride: boolean;
+    secureStore: {
+        backend: string;
+        serviceName: string;
+        accountName: string;
+        available: boolean;
+        hasStoredLicenseKey: null;
+        error: string;
+    };
+} | {
+    saved: boolean;
+    source: string;
+    envOverride: boolean;
+    secureStore: {
+        backend: string;
+        serviceName: string;
+        accountName: string;
+        available: boolean;
+        hasStoredLicenseKey: boolean;
+        error?: undefined;
+    };
+} | {
+    saved: boolean;
+    source: string;
+    envOverride: boolean;
+    secureStore: {
+        backend: string;
+        serviceName: string;
+        accountName: string;
+        available: boolean;
+        hasStoredLicenseKey: null;
+        error: string;
+    };
+} | {
+    cleared: boolean;
+    source: string;
+    envOverride: boolean;
+    secureStore: {
+        backend: string;
+        serviceName: string;
+        accountName: string;
+        available: boolean;
+        hasStoredLicenseKey: boolean;
+        error?: undefined;
+    };
+} | {
+    cleared: boolean;
+    source: string;
+    envOverride: boolean;
+    secureStore: {
+        backend: string;
+        serviceName: string;
+        accountName: string;
+        available: boolean;
+        hasStoredLicenseKey: null;
+        error: string;
+    };
+}>;
+export declare const buildAuthStatus: () => Promise<{
+    source: string;
+    envOverride: boolean;
+    secureStore: {
+        backend: string;
+        serviceName: string;
+        accountName: string;
+        available: boolean;
+        hasStoredLicenseKey: boolean;
+        error?: undefined;
+    };
+} | {
+    source: string;
+    envOverride: boolean;
+    secureStore: {
+        backend: string;
+        serviceName: string;
+        accountName: string;
+        available: boolean;
+        hasStoredLicenseKey: null;
+        error: string;
+    };
+}>;
+export {};

package/dist/cli-auth.js

@@ -0,0 +1,222 @@
+import { spawnSync } from 'node:child_process';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import readline from 'node:readline';
+export const LICENSE_KEY_ENV_VAR = 'RR_LICENSE_KEY';
+export const AUTH_SERVICE_NAME = 'RankWrangler CLI';
+export const AUTH_ACCOUNT_NAME = 'license-key';
+const INTERNAL_SECRET_STORE_DIR_ENV_VAR = 'RW_INTERNAL_CLI_SECRET_STORE_DIR';
+export class CliAuthError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = 'CliAuthError';
+        this.code = code;
+        this.details = details;
+    }
+}
+export const resolveApiKey = async () => {
+    const envLicenseKey = resolveEnvLicenseKey();
+    if (envLicenseKey) {
+        return envLicenseKey;
+    }
+    const secureStore = await createSecureStore();
+    return (await secureStore.get()) ?? undefined;
+};
+export const runAuthCommand = async (command, fail, options = {}) => {
+    if (command.verb === 'status') {
+        return buildAuthStatus();
+    }
+    if (command.verb === 'set') {
+        const value = await resolveAuthSetValue(command.args, fail, options);
+        const secureStore = await createSecureStore();
+        await secureStore.set(value);
+        return {
+            ...(await buildAuthStatus()),
+            saved: true,
+        };
+    }
+    if (command.verb === 'clear') {
+        const secureStore = await createSecureStore();
+        const cleared = await secureStore.clear();
+        return {
+            ...(await buildAuthStatus()),
+            cleared,
+        };
+    }
+    fail('UNKNOWN_COMMAND', 'Unknown auth command', { verb: command.verb });
+};
+export const buildAuthStatus = async () => {
+    const envLicenseKey = resolveEnvLicenseKey();
+    try {
+        const secureStore = await createSecureStore();
+        const storedLicenseKey = await secureStore.get();
+        return {
+            source: envLicenseKey ? 'env' : storedLicenseKey ? 'secure-store' : 'none',
+            envOverride: Boolean(envLicenseKey),
+            secureStore: {
+                backend: secureStore.backend,
+                serviceName: secureStore.serviceName,
+                accountName: secureStore.accountName,
+                available: true,
+                hasStoredLicenseKey: Boolean(storedLicenseKey),
+            },
+        };
+    }
+    catch (error) {
+        return {
+            source: envLicenseKey ? 'env' : 'none',
+            envOverride: Boolean(envLicenseKey),
+            secureStore: {
+                backend: getSecureStoreBackendLabel(),
+                serviceName: AUTH_SERVICE_NAME,
+                accountName: AUTH_ACCOUNT_NAME,
+                available: false,
+                hasStoredLicenseKey: null,
+                error: error instanceof Error ? error.message : 'Unknown secure-store error',
+            },
+        };
+    }
+};
+const resolveAuthSetValue = async (args, fail, options) => {
+    const positionalValue = args.join(' ').trim();
+    if (positionalValue) {
+        return positionalValue;
+    }
+    if (options.stdin) {
+        const stdinValue = await readSecretFromStdin();
+        if (stdinValue) {
+            return stdinValue;
+        }
+        fail('INVALID_INPUT', 'auth set --stdin received an empty license key');
+    }
+    const envLicenseKey = resolveEnvLicenseKey();
+    if (envLicenseKey) {
+        return envLicenseKey;
+    }
+    if (process.stdin.isTTY && process.stderr.isTTY) {
+        const promptValue = await readSecretFromPrompt('RankWrangler license key: ');
+        if (promptValue) {
+            return promptValue;
+        }
+        fail('INVALID_INPUT', 'auth set received an empty license key');
+    }
+    fail('INVALID_INPUT', `auth set requires <licenseKey>, --stdin, or ${LICENSE_KEY_ENV_VAR}`);
+};
+const readSecretFromStdin = async () => {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString('utf8').trim();
+};
+const readSecretFromPrompt = async (prompt) => {
+    process.stderr.write(prompt);
+    setTerminalEcho(false);
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+        terminal: true,
+    });
+    try {
+        const value = await new Promise(resolve => {
+            rl.question('', resolve);
+        });
+        process.stderr.write('\n');
+        return value.trim();
+    }
+    finally {
+        rl.close();
+        setTerminalEcho(true);
+    }
+};
+const setTerminalEcho = (enabled) => {
+    if (process.platform === 'win32' || !process.stdin.isTTY) {
+        return;
+    }
+    spawnSync('stty', [enabled ? 'echo' : '-echo'], {
+        stdio: ['inherit', 'ignore', 'ignore'],
+    });
+};
+const resolveEnvLicenseKey = () => {
+    const value = process.env[LICENSE_KEY_ENV_VAR]?.trim();
+    return value ? value : undefined;
+};
+const createSecureStore = async () => {
+    const internalSecretStoreDir = process.env[INTERNAL_SECRET_STORE_DIR_ENV_VAR]?.trim();
+    if (internalSecretStoreDir) {
+        return createFileSecretStore(path.resolve(internalSecretStoreDir));
+    }
+    const keytar = await loadKeytar();
+    return {
+        backend: getSecureStoreBackendLabel(),
+        serviceName: AUTH_SERVICE_NAME,
+        accountName: AUTH_ACCOUNT_NAME,
+        get: () => keytar.getPassword(AUTH_SERVICE_NAME, AUTH_ACCOUNT_NAME),
+        set: value => keytar.setPassword(AUTH_SERVICE_NAME, AUTH_ACCOUNT_NAME, value),
+        clear: () => keytar.deletePassword(AUTH_SERVICE_NAME, AUTH_ACCOUNT_NAME),
+    };
+};
+const loadKeytar = async () => {
+    try {
+        const imported = (await import('keytar'));
+        return imported.default ?? imported;
+    }
+    catch (error) {
+        throw new CliAuthError('SECURE_STORE_UNAVAILABLE', 'platform secure store is unavailable', error instanceof Error ? { cause: error.message } : undefined);
+    }
+};
+const getSecureStoreBackendLabel = () => {
+    switch (process.platform) {
+        case 'darwin':
+            return 'macos-keychain';
+        case 'win32':
+            return 'windows-credential-manager';
+        default:
+            return 'platform-secure-store';
+    }
+};
+const createFileSecretStore = (secretStoreDir) => {
+    const secretPath = path.join(secretStoreDir, 'license-key.json');
+    return {
+        backend: 'test-file-store',
+        serviceName: AUTH_SERVICE_NAME,
+        accountName: AUTH_ACCOUNT_NAME,
+        get: async () => {
+            try {
+                const raw = await readFile(secretPath, 'utf8');
+                const parsed = JSON.parse(raw);
+                return typeof parsed.licenseKey === 'string' ? parsed.licenseKey : null;
+            }
+            catch (error) {
+                if (error &&
+                    typeof error === 'object' &&
+                    'code' in error &&
+                    error.code === 'ENOENT') {
+                    return null;
+                }
+                throw new CliAuthError('INVALID_CONFIG', 'failed to read secure-store test data');
+            }
+        },
+        set: async (value) => {
+            await mkdir(secretStoreDir, { recursive: true });
+            await writeFile(secretPath, `${JSON.stringify({ licenseKey: value }, null, 2)}\n`, 'utf8');
+        },
+        clear: async () => {
+            try {
+                await rm(secretPath);
+                return true;
+            }
+            catch (error) {
+                if (error &&
+                    typeof error === 'object' &&
+                    'code' in error &&
+                    error.code === 'ENOENT') {
+                    return false;
+                }
+                throw error;
+            }
+        },
+    };
+};

package/dist/cli-config-command.d.ts

@@ -0,0 +1,101 @@
+import { type CliConfig, type CliPaths } from './cli-config';
+type CliFail = (code: string, message: string, details?: unknown) => never;
+type ConfigCommand = {
+    verb: string;
+    args: string[];
+};
+export declare const runConfigCommand: (command: ConfigCommand, config: CliConfig, paths: CliPaths, fail: CliFail) => Promise<{
+    storageDir: string;
+    path: string;
+    globalPath: string;
+    config: CliConfig;
+    auth: {
+        source: string;
+        envOverride: boolean;
+        secureStore: {
+            backend: string;
+            serviceName: string;
+            accountName: string;
+            available: boolean;
+            hasStoredLicenseKey: boolean;
+            error?: undefined;
+        };
+    } | {
+        source: string;
+        envOverride: boolean;
+        secureStore: {
+            backend: string;
+            serviceName: string;
+            accountName: string;
+            available: boolean;
+            hasStoredLicenseKey: null;
+            error: string;
+        };
+    };
+} | {
+    key: "base-url" | "marketplace" | "storage-dir";
+    value: string | null;
+} | {
+    unset: "base-url" | "marketplace" | "storage-dir";
+    storageDir: string;
+    path: string;
+    globalPath: string;
+    config: CliConfig;
+    auth: {
+        source: string;
+        envOverride: boolean;
+        secureStore: {
+            backend: string;
+            serviceName: string;
+            accountName: string;
+            available: boolean;
+            hasStoredLicenseKey: boolean;
+            error?: undefined;
+        };
+    } | {
+        source: string;
+        envOverride: boolean;
+        secureStore: {
+            backend: string;
+            serviceName: string;
+            accountName: string;
+            available: boolean;
+            hasStoredLicenseKey: null;
+            error: string;
+        };
+    };
+    key?: undefined;
+    value?: undefined;
+} | {
+    reset: boolean;
+    storageDir: string;
+    path: string;
+    globalPath: string;
+    config: CliConfig;
+    auth: {
+        source: string;
+        envOverride: boolean;
+        secureStore: {
+            backend: string;
+            serviceName: string;
+            accountName: string;
+            available: boolean;
+            hasStoredLicenseKey: boolean;
+            error?: undefined;
+        };
+    } | {
+        source: string;
+        envOverride: boolean;
+        secureStore: {
+            backend: string;
+            serviceName: string;
+            accountName: string;
+            available: boolean;
+            hasStoredLicenseKey: null;
+            error: string;
+        };
+    };
+    key?: undefined;
+    value?: undefined;
+}>;
+export {};

package/dist/cli-config-command.js

@@ -0,0 +1,118 @@
+import { buildAuthStatus } from './cli-auth.js';
+import { resetConfig, saveConfig, switchStorageDir, unsetStorageDir, } from './cli-config.js';
+import { normalizeBaseUrl } from './cli-options.js';
+const CONFIG_KEYS = ['base-url', 'marketplace', 'storage-dir'];
+export const runConfigCommand = async (command, config, paths, fail) => {
+    if (command.verb === 'show') {
+        return buildConfigResponse(paths, config);
+    }
+    if (command.verb === 'get') {
+        const key = requireConfigKey(command.args[0], 'config get', fail);
+        return {
+            key,
+            value: getConfigValue(key, paths, config),
+        };
+    }
+    if (command.verb === 'unset') {
+        const key = requireConfigKey(command.args[0], 'config unset', fail);
+        const nextState = await unsetConfigValue(key, paths, config);
+        return {
+            ...(await buildConfigResponse(nextState.paths, nextState.config)),
+            unset: key,
+        };
+    }
+    if (command.verb === 'reset') {
+        const nextState = await resetConfig(paths);
+        return {
+            ...(await buildConfigResponse(nextState.paths, nextState.config)),
+            reset: true,
+        };
+    }
+    if (command.verb !== 'set') {
+        fail('UNKNOWN_COMMAND', 'Unknown config command', { verb: command.verb });
+    }
+    const [key, ...valueParts] = command.args;
+    if (!key || valueParts.length === 0) {
+        fail('INVALID_INPUT', 'config set requires <key> <value>');
+    }
+    const value = valueParts.join(' ').trim();
+    if (!value) {
+        fail('INVALID_INPUT', 'config set value cannot be empty');
+    }
+    if (key === 'storage-dir') {
+        const nextState = await switchStorageDir({
+            currentConfig: config,
+            currentPaths: paths,
+            requestedStorageDir: value,
+        });
+        return buildConfigResponse(nextState.paths, nextState.config);
+    }
+    const nextConfig = { ...config };
+    if (key === 'base-url') {
+        nextConfig.baseUrl = normalizeBaseUrl(value, fail);
+    }
+    else if (key === 'marketplace') {
+        nextConfig.marketplaceId = value;
+    }
+    else {
+        failUnsupportedConfigKey(key, fail);
+    }
+    await saveConfig(paths, nextConfig);
+    return buildConfigResponse(paths, nextConfig);
+};
+const buildConfigResponse = async (paths, config) => {
+    return {
+        storageDir: paths.storageDir,
+        path: paths.configPath,
+        globalPath: paths.globalConfigPath,
+        config,
+        auth: await buildAuthStatus(),
+    };
+};
+const requireConfigKey = (key, commandName, fail) => {
+    if (!key) {
+        fail('INVALID_INPUT', `${commandName} requires <key>`, {
+            supportedKeys: CONFIG_KEYS,
+        });
+    }
+    if (isConfigKey(key)) {
+        return key;
+    }
+    return failUnsupportedConfigKey(key, fail);
+};
+const isConfigKey = (key) => {
+    return CONFIG_KEYS.includes(key);
+};
+const getConfigValue = (key, paths, config) => {
+    switch (key) {
+        case 'base-url':
+            return config.baseUrl ?? null;
+        case 'marketplace':
+            return config.marketplaceId ?? null;
+        case 'storage-dir':
+            return paths.storageDir;
+    }
+};
+const unsetConfigValue = async (key, paths, config) => {
+    if (key === 'storage-dir') {
+        return unsetStorageDir(paths);
+    }
+    const nextConfig = { ...config };
+    if (key === 'base-url') {
+        nextConfig.baseUrl = undefined;
+    }
+    else {
+        nextConfig.marketplaceId = undefined;
+    }
+    await saveConfig(paths, nextConfig);
+    return {
+        paths,
+        config: nextConfig,
+    };
+};
+const failUnsupportedConfigKey = (key, fail) => {
+    fail('INVALID_INPUT', 'unsupported config key', {
+        key,
+        supportedKeys: CONFIG_KEYS,
+    });
+};

package/dist/cli-config.d.ts

@@ -19,8 +19,15 @@ export declare const loadCliContext: () => Promise<{
     config: CliConfig;
 }>;
 export declare const loadCliPathsOrDefault: () => Promise<CliPaths>;
-export declare const clearConfig: (paths: CliPaths) => Promise<void>;
+export declare const resetConfig: (paths: CliPaths) => Promise<{
+    paths: CliPaths;
+    config: {};
+}>;
 export declare const saveConfig: (paths: CliPaths, config: CliConfig) => Promise<void>;
+export declare const unsetStorageDir: (paths: CliPaths) => Promise<{
+    paths: CliPaths;
+    config: CliConfig;
+}>;
 export declare const switchStorageDir: ({ currentConfig, currentPaths, requestedStorageDir, }: {
     currentConfig: CliConfig;
     currentPaths: CliPaths;

package/dist/cli-config.js

@@ -34,13 +34,31 @@ export const loadCliPathsOrDefault = async () => {
         return getDefaultCliPaths();
     }
 };
-export const clearConfig = async (paths) => {
-    await rm(paths.configPath, { force: true });
+export const resetConfig = async (paths) => {
+    await Promise.all([
+        rm(paths.configPath, { force: true }),
+        rm(paths.globalConfigPath, { force: true }),
+        paths.storageDir === paths.defaultStorageDir
+            ? Promise.resolve()
+            : rm(path.join(paths.defaultStorageDir, CONFIG_FILENAME), { force: true }),
+    ]);
+    return {
+        paths: getDefaultCliPaths(),
+        config: {},
+    };
 };
 export const saveConfig = async (paths, config) => {
     await mkdir(paths.storageDir, { recursive: true });
     await writeFile(paths.configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
 };
+export const unsetStorageDir = async (paths) => {
+    await rm(paths.globalConfigPath, { force: true });
+    const nextPaths = getDefaultCliPaths();
+    return {
+        paths: nextPaths,
+        config: await loadConfig(nextPaths.configPath),
+    };
+};
 export const switchStorageDir = async ({ currentConfig, currentPaths, requestedStorageDir, }) => {
     const storageDir = normalizeStorageDir(requestedStorageDir);
     const nextPaths = buildCliPaths(storageDir);

package/dist/cli-options.d.ts

@@ -1,5 +1,5 @@
 import type { CliConfig } from './cli-config';
-import { type HistoryMetricAlias } from './history-response';
+import { type HistoryBucket, type HistoryMetricAlias } from './history-response';
 type CliFail = (code: string, message: string, details?: unknown) => never;
 export type CliOptionValues = {
     baseUrl?: string;
@@ -10,6 +10,7 @@ export type CliOptionValues = {
     endAt?: string;
     days?: string;
     limit?: string;
+    bucket?: string;
     help?: boolean;
     version?: boolean;
 };
@@ -17,12 +18,12 @@ export declare const requireMarketplaceId: (values: CliOptionValues, config: Cli
 export declare const requireAsins: (commandArgs: string[], values: CliOptionValues, fail: CliFail) => string[];
 export declare const requireSingleAsin: (commandArgs: string[], values: CliOptionValues, fail: CliFail) => string;
 export declare const resolveHistoryMetrics: (values: CliOptionValues, fail: CliFail) => HistoryMetricAlias[];
+export declare const resolveHistoryBucket: (values: CliOptionValues, fail: CliFail) => HistoryBucket;
 export declare const resolveHistoryWindow: (values: CliOptionValues, fail: CliFail) => {
     days: number;
     endAt?: string | undefined;
     startAt?: string | undefined;
 };
-export declare const resolveApiKey: () => string | undefined;
 export declare const resolveBaseUrl: (values: CliOptionValues, config: CliConfig, defaultBaseUrl: string, fail: CliFail) => string;
 export declare const normalizeBaseUrl: (value: string, fail: CliFail) => string;
 export declare const parseIntegerOption: ({ value, optionName, min, max, defaultValue, }: {

package/dist/cli-options.js

@@ -1,4 +1,4 @@
-import { HISTORY_METRIC_ALIASES } from './history-response.js';
+import { HISTORY_BUCKETS, HISTORY_METRIC_ALIASES, } from './history-response.js';
 const ASIN_REGEX = /^[A-Z0-9]{10}$/i;
 const TRAILING_SLASHES_REGEX = /\/+$/;
 const API_SUFFIX_REGEX = /\/api$/i;
@@ -38,6 +38,15 @@ export const resolveHistoryMetrics = (values, fail) => {
     }
     return Array.from(new Set(requested));
 };
+export const resolveHistoryBucket = (values, fail) => {
+    const requested = (values.bucket ?? 'auto').trim().toLowerCase();
+    if (!HISTORY_BUCKETS.includes(requested)) {
+        fail('INVALID_INPUT', `unsupported history bucket: ${requested}`, {
+            supportedBuckets: HISTORY_BUCKETS,
+        });
+    }
+    return requested;
+};
 export const resolveHistoryWindow = (values, fail) => {
     const startAt = values.startAt ? normalizeDateOption('startAt', values.startAt, fail) : undefined;
     const endAt = values.endAt ? normalizeDateOption('endAt', values.endAt, fail) : undefined;
@@ -56,9 +65,6 @@ export const resolveHistoryWindow = (values, fail) => {
         }, fail),
     };
 };
-export const resolveApiKey = () => {
-    return process.env.RR_LICENSE_KEY;
-};
 export const resolveBaseUrl = (values, config, defaultBaseUrl, fail) => {
     return normalizeBaseUrl(values.baseUrl ?? config.baseUrl ?? process.env.RR_API_URL ?? defaultBaseUrl, fail);
 };

package/dist/cli-output.js

@@ -1,3 +1,4 @@
+import { CliAuthError } from './cli-auth.js';
 import { CliStorageError } from './cli-config.js';
 const OUTPUT_PRETTY = true;
 export const printSuccess = (data) => {
@@ -27,6 +28,13 @@ export const resolveError = (error) => {
             details: error.details,
         };
     }
+    if (error instanceof CliAuthError) {
+        return {
+            code: error.code,
+            message: error.message,
+            details: error.details,
+        };
+    }
     if (error && typeof error === 'object' && 'data' in error) {
         const data = error.data;
         if (data?.code) {

package/dist/history-response.d.ts

@@ -1,6 +1,17 @@
 export declare const HISTORY_METRIC_ALIASES: readonly ["bsr", "price"];
+export declare const HISTORY_BUCKETS: readonly ["auto", "day", "week", "month"];
 export type HistoryMetricAlias = (typeof HISTORY_METRIC_ALIASES)[number];
-type HistoryPointTuple = [string, number | null] | [string, null, 1];
+export type HistoryBucket = (typeof HISTORY_BUCKETS)[number];
+type HistoryBucketTuple = [string, number | null];
+type HistoryBucketSummary = {
+    first: number | null;
+    latest: number | null;
+    min: number | null;
+    max: number | null;
+    count: number;
+    firstBucketAt: string | null;
+    latestBucketAt: string | null;
+};
 export type AgentHistorySeries = {
     bsr?: {
         unit: 'rank';
@@ -8,13 +19,15 @@ export type AgentHistorySeries = {
             id: number;
             name: string | null;
         } | null;
-        points: HistoryPointTuple[];
+        buckets: HistoryBucketTuple[];
+        summary: HistoryBucketSummary;
     };
     price?: {
         unit: 'minorCurrency';
         currencyCode: 'USD';
         valueScale: 100;
-        points: HistoryPointTuple[];
+        buckets: HistoryBucketTuple[];
+        summary: HistoryBucketSummary;
     };
 };
 export type AgentHistoryResponse = {
@@ -22,6 +35,11 @@ export type AgentHistoryResponse = {
     status?: string;
     syncTriggered: boolean;
     latestImportAt: string | null;
+    range?: {
+        startAt: string;
+        endAt: string;
+        bucket: Exclude<HistoryBucket, 'auto'>;
+    };
     series?: AgentHistorySeries;
 };
 export declare const buildCliHistoryResponse: ({ asin, marketplaceId, metrics, response, }: {
@@ -30,12 +48,17 @@ export declare const buildCliHistoryResponse: ({ asin, marketplaceId, metrics, r
     metrics: HistoryMetricAlias[];
     response: AgentHistoryResponse;
 }) => {
+    series: AgentHistorySeries;
+    range?: {
+        startAt: string;
+        endAt: string;
+        bucket: Exclude<HistoryBucket, "auto">;
+    } | undefined;
     schemaVersion: number;
     asin: string;
     marketplaceId: string;
     status: string;
     latestImportAt: string | null;
     syncTriggered: boolean;
-    series: AgentHistorySeries;
 };
 export {};

package/dist/history-response.js

@@ -1,4 +1,5 @@
 export const HISTORY_METRIC_ALIASES = ['bsr', 'price'];
+export const HISTORY_BUCKETS = ['auto', 'day', 'week', 'month'];
 export const buildCliHistoryResponse = ({ asin, marketplaceId, metrics, response, }) => {
     const series = {
         ...(metrics.includes('bsr') && response.series?.bsr ? { bsr: response.series.bsr } : {}),
@@ -6,15 +7,16 @@ export const buildCliHistoryResponse = ({ asin, marketplaceId, metrics, response
             ? { price: response.series.price }
             : {}),
     };
-    const hasAnyPoints = Object.values(series).some(metricSeries => metricSeries.points.length > 0);
+    const hasAnyBuckets = Object.values(series).some(metricSeries => metricSeries.buckets.length > 0);
     const status = normalizeHistoryStatus(response.status);
     return {
-        schemaVersion: response.schemaVersion ?? 1,
+        schemaVersion: response.schemaVersion ?? 2,
         asin,
         marketplaceId,
-        status: status ?? (response.syncTriggered ? 'collecting' : hasAnyPoints ? 'ready' : 'empty'),
+        status: status ?? (response.syncTriggered ? 'collecting' : hasAnyBuckets ? 'ready' : 'empty'),
         latestImportAt: response.latestImportAt,
         syncTriggered: response.syncTriggered,
+        ...(response.range ? { range: response.range } : {}),
         series,
     };
 };

package/dist/index.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 import { parseArgs } from 'node:util';
 import { createRankWranglerClient, DEFAULT_API_BASE_URL } from '@rankwrangler/http-client';
+import { resolveApiKey, runAuthCommand } from './cli-auth.js';
 import { printBundledChangelog, printCliVersion } from './cli-metadata.js';
-import { clearConfig, loadCliContext, loadCliPathsOrDefault, saveConfig, switchStorageDir, } from './cli-config.js';
-import { normalizeBaseUrl, parseIntegerOption, requireAsins, requireMarketplaceId, requireSingleAsin, resolveApiKey, resolveBaseUrl, resolveHistoryMetrics, resolveHistoryWindow, } from './cli-options.js';
+import { runConfigCommand } from './cli-config-command.js';
+import { loadCliContext, loadCliPathsOrDefault } from './cli-config.js';
+import { parseIntegerOption, requireAsins, requireMarketplaceId, requireSingleAsin, resolveBaseUrl, resolveHistoryBucket, resolveHistoryMetrics, resolveHistoryWindow, } from './cli-options.js';
 import { fail, printSuccess, resolveError } from './cli-output.js';
 import { buildCliHistoryResponse } from './history-response.js';
 import { printUsage } from './usage.js';
@@ -12,8 +14,13 @@ const SUPPORTED_COMMANDS = new Set([
     'products:history',
     'license:status',
     'license:validate',
+    'auth:status',
+    'auth:set',
+    'auth:clear',
     'config:show',
-    'config:clear',
+    'config:get',
+    'config:unset',
+    'config:reset',
     'config:set',
 ]);
 const { positionals, values } = parseArgs({
@@ -29,6 +36,8 @@ const { positionals, values } = parseArgs({
         endAt: { type: 'string' },
         days: { type: 'string' },
         limit: { type: 'string' },
+        bucket: { type: 'string' },
+        stdin: { type: 'boolean' },
     },
     allowPositionals: true,
 });
@@ -57,12 +66,16 @@ const main = async () => {
     }
     const { config, paths } = await loadCliContext();
     if (command.resource === 'config') {
-        printSuccess(await runConfigCommand(command, config, paths));
+        printSuccess(await runConfigCommand(command, config, paths, fail));
         return;
     }
-    const apiKey = resolveApiKey();
+    if (command.resource === 'auth') {
+        printSuccess(await runAuthCommand(command, fail, { stdin: Boolean(values.stdin) }));
+        return;
+    }
+    const apiKey = await resolveApiKey();
     if (!apiKey) {
-        fail('MISSING_CONFIG', 'api key is required. set RR_LICENSE_KEY');
+        fail('MISSING_CONFIG', 'license key is required. run `rw auth set`, `rw auth set --stdin`, or set RR_LICENSE_KEY');
     }
     const client = createRankWranglerClient({
         baseUrl: resolveBaseUrl(optionValues, config, DEFAULT_API_BASE_URL, fail),
@@ -98,6 +111,7 @@ const runProductHistoryCommand = async (command, client, config) => {
     const asin = requireSingleAsin(command.args, optionValues, fail);
     const marketplaceId = requireMarketplaceId(optionValues, config);
     const metrics = resolveHistoryMetrics(optionValues, fail);
+    const bucket = resolveHistoryBucket(optionValues, fail);
     const historyWindow = resolveHistoryWindow(optionValues, fail);
     const limit = parseIntegerOption({
         value: optionValues.limit,
@@ -111,6 +125,7 @@ const runProductHistoryCommand = async (command, client, config) => {
         asin,
         metrics,
         format: 'agent',
+        bucket,
         limit,
         ...historyWindow,
     });
@@ -121,60 +136,6 @@ const runProductHistoryCommand = async (command, client, config) => {
         response: response,
     });
 };
-const runConfigCommand = async (command, config, paths) => {
-    if (command.verb === 'show') {
-        return buildConfigResponse(paths, config);
-    }
-    if (command.verb === 'clear') {
-        await clearConfig(paths);
-        return {
-            ...buildConfigResponse(paths, {}),
-            cleared: true,
-        };
-    }
-    if (command.verb !== 'set') {
-        fail('UNKNOWN_COMMAND', 'Unknown config command', { verb: command.verb });
-    }
-    const [key, ...valueParts] = command.args;
-    if (!key || valueParts.length === 0) {
-        fail('INVALID_INPUT', 'config set requires <key> <value>');
-    }
-    const value = valueParts.join(' ').trim();
-    if (!value) {
-        fail('INVALID_INPUT', 'config set value cannot be empty');
-    }
-    if (key === 'storage-dir') {
-        const nextState = await switchStorageDir({
-            currentConfig: config,
-            currentPaths: paths,
-            requestedStorageDir: value,
-        });
-        return buildConfigResponse(nextState.paths, nextState.config);
-    }
-    const nextConfig = { ...config };
-    if (key === 'base-url') {
-        nextConfig.baseUrl = normalizeBaseUrl(value, fail);
-    }
-    else if (key === 'marketplace') {
-        nextConfig.marketplaceId = value;
-    }
-    else {
-        fail('INVALID_INPUT', 'unsupported config key', {
-            key,
-            supportedKeys: ['base-url', 'marketplace', 'storage-dir'],
-        });
-    }
-    await saveConfig(paths, nextConfig);
-    return buildConfigResponse(paths, nextConfig);
-};
-const buildConfigResponse = (paths, config) => {
-    return {
-        storageDir: paths.storageDir,
-        path: paths.configPath,
-        globalPath: paths.globalConfigPath,
-        config,
-    };
-};
 const resolveMetaCommand = (inputPositionals) => {
     if (inputPositionals.length === 1 && inputPositionals[0] === 'changelog') {
         return { name: 'changelog' };

package/dist/usage.js

@@ -1,3 +1,4 @@
+import { LICENSE_KEY_ENV_VAR } from './cli-auth.js';
 const DEFAULT_MARKETPLACE_ID = 'ATVPDKIKX0DER';
 export const printUsage = (paths) => {
     const usage = [
@@ -18,11 +19,17 @@ export const printUsage = (paths) => {
         '  products history <ASIN>',
         '  license status',
         '  license validate',
+        '  auth status',
+        '  auth set [licenseKey]',
+        '  auth set --stdin',
+        '  auth clear',
         '  config show',
-        '  config clear',
+        '  config get <key>',
         '  config set base-url <origin>',
         '  config set marketplace <marketplaceId>',
         '  config set storage-dir <path>',
+        '  config unset <key>',
+        '  config reset',
         '',
         'OPTIONS',
         '  -h, --help               Show this help message',
@@ -31,17 +38,19 @@ export const printUsage = (paths) => {
         `  -m, --marketplace <id>   Override marketplace (default: ${DEFAULT_MARKETPLACE_ID})`,
         '  --asin <ASIN>            Add ASIN (repeatable)',
         '  --metrics <list>         History metrics: bsr,price (default: bsr,price)',
+        '  --bucket <unit>          History buckets: auto,day,week,month (default: auto)',
         '  --days <N>               History lookback window (30-3650, default: 365)',
         '  --startAt <ISO>          History range start (ISO date/time)',
         '  --endAt <ISO>            History range end (ISO date/time)',
-        '  --limit <N>              Max points per metric (1-10000, default: 5000)',
+        '  --limit <N>              Internal point cap (1-10000, default: 5000)',
+        '  --stdin                  Read auth secret from standard input',
         '',
         'FILES',
         `  ${paths.configPath}           Active CLI config`,
         `  ${paths.globalConfigPath}           Global CLI settings`,
         '',
         'ENVIRONMENT',
-        '  RR_LICENSE_KEY           API key source',
+        `  ${LICENSE_KEY_ENV_VAR}           License key override for CI/automation`,
         '  RR_API_URL               API origin fallback',
         '  RR_MARKETPLACE_ID        Marketplace fallback',
         '  RR_STORAGE_DIR           Storage directory override',
@@ -50,13 +59,17 @@ export const printUsage = (paths) => {
         '  RR_HISTORY_METRICS       Comma-separated history metrics fallback',
         '',
         'EXAMPLES',
-        '  RR_LICENSE_KEY=rrk_... rw products get B0DV53VS61',
+        '  rw auth set rrk_...',
+        '  printf %s "$RR_LICENSE_KEY" | rw auth set --stdin',
+        `  ${LICENSE_KEY_ENV_VAR}=rrk_... rw products get B0DV53VS61`,
         '  RR_STORAGE_DIR=~/.config/rankwrangler rw config show',
         '  rw --version',
         '  rw changelog',
+        '  rw config get marketplace',
         '  rw config set storage-dir ~/.config/rankwrangler',
-        '  rw products history B0DV53VS61 --metrics bsr,price',
-        '  rw products history B0DV53VS61 --startAt 2025-01-01 --endAt 2025-12-31',
+        '  rw config unset marketplace',
+        '  rw products history B0DV53VS61 --metrics bsr,price --bucket week',
+        '  rw products history B0DV53VS61 --startAt 2025-01-01 --endAt 2025-12-31 --bucket month',
         '  rankwrangler license status',
     ];
     console.log(usage.join('\n'));

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rankwrangler/cli",
-    "version": "0.4.1",
+    "version": "0.6.0",
     "description": "Official RankWrangler command line interface",
     "type": "module",
     "bin": {
@@ -20,14 +20,16 @@
         "prepublishOnly": "node ../../scripts/release/ensure-cli-http-client-published.mjs"
     },
     "publishConfig": {
-        "access": "public"
+        "access": "public",
+        "provenance": true
     },
     "dependencies": {
-        "@rankwrangler/http-client": "^0.4.1"
+        "@rankwrangler/http-client": "^0.6.0",
+        "keytar": "7.9.0"
     },
     "devDependencies": {
-        "@types/node": "^24.3.0",
-        "typescript": "^5.9.2"
+        "@types/node": "24.10.12",
+        "typescript": "5.9.3"
     },
     "packageManager": "bun@1.1.27"
 }