highspot-cli 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Advait Shinde
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# highspot-cli
+
+`highspot-cli` is an unofficial CLI client for the [Highspot](https://www.highspot.com/) REST API.
+
+It is designed for both humans and agents:
+
+- default output: JSON on stdout
+- script-stable output: `--plain`
+- diagnostics/errors: stderr
+
+## Install
+
+```bash
+npm install -g highspot-cli
+```
+
+Run without global install:
+
+```bash
+npx highspot-cli --help
+bunx highspot-cli --help
+deno run -A npm:highspot-cli --help
+```
+
+## Auth
+
+Set credentials with environment variables:
+
+```bash
+export HIGHSPOT_API_KEY_ID=hs_key_id_xxx
+export HIGHSPOT_API_KEY_SECRET=hs_key_secret_xxx
+```
+
+Optional:
+
+```bash
+export HIGHSPOT_API_ENDPOINT=https://api.highspot.com/v1.0
+export HIGHSPOT_HS_USER=user@example.com
+```
+
+`HIGHSPOT_HS_USER` (or `--hs-user`) is optional impersonation context.
+It is not implied by the API key:
+- API key (`HIGHSPOT_API_KEY_ID` + `HIGHSPOT_API_KEY_SECRET`) authenticates the caller.
+- `hs-user` sets an explicit user context for requests where impersonation is needed.
+- CLI flag precedence still applies, so `--hs-user` overrides `HIGHSPOT_HS_USER`.
+
+## Config Files
+
+Config precedence (highest to lowest):
+
+1. CLI flags
+2. Environment variables
+3. Project config: `.highspot-cli.json`
+4. User config: `~/.config/highspot-cli/config.json`
+5. System config: `/etc/highspot-cli/config.json`
+
+Example `.highspot-cli.json`:
+
+```json
+{
+  "endpoint": "https://api.highspot.com/v1.0",
+  "hsUser": "user@example.com",
+  "maxRetries": 3,
+  "retryDelayMs": 1200,
+  "timeoutMs": 30000,
+  "apiKeyId": "hs_key_id_xxx",
+  "apiKeySecret": "hs_key_secret_xxx"
+}
+```
+
+## Commands
+
+```bash
+highspot search <query>
+highspot item <item-id>
+highspot content <item-id>
+highspot me
+```
+
+Global flags:
+
+- `-h, --help`
+- `--version`
+- `--json` (default output mode)
+- `--plain` (line-based stable output)
+- `--dry-run` (print request and exit)
+- `--hs-user <value>`
+- `--endpoint <url>`
+- `--timeout-ms <n>`
+- `--max-retries <n>`
+- `--retry-delay-ms <n>`
+- `--quiet`
+- `--verbose`
+- `--no-input`
+- `--no-color`
+
+Exit codes:
+
+- `0` success
+- `1` API/runtime failure
+- `2` invalid usage or missing configuration
+
+## Examples
+
+```bash
+highspot search "GoGuardian Teacher" --limit 10
+highspot search "Beacon" --sort-by date_added --plain
+highspot item it_abc123
+highspot content it_abc123 --format text/plain --plain
+highspot me --json
+highspot search "Fleet" --dry-run
+```
+
+Behavior notes:
+
+- Prompts are not used; `--no-input` is accepted for automation consistency.
+- Primary data goes to stdout, errors go to stderr.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run check
+npm run format
+node dist/bin/highspot.js --help
+```
+
+## Publish (npm)
+
+For `advait/highspot-cli`:
+
+```bash
+npm version patch
+npm publish --access public
+```
+
+Then tag/push your release in GitHub.

package/dist/bin/highspot.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { execute } from "@oclif/core";
+await execute({ dir: import.meta.url });

package/dist/commands/content.js

@@ -0,0 +1,70 @@
+import { Args } from "@oclif/core";
+import { BaseCommand } from "../lib/command.js";
+import { contentFlags, globalFlags } from "../lib/flags.js";
+export default class Content extends BaseCommand {
+    static description = "Fetch Highspot item content";
+    static examples = [
+        "highspot content it_abc123",
+        "highspot content it_abc123 --format text/plain --plain",
+        "highspot content it_abc123 --start cursor-2",
+    ];
+    static args = {
+        itemId: Args.string({
+            description: "Highspot item id",
+            required: false,
+        }),
+    };
+    static flags = {
+        ...globalFlags,
+        ...contentFlags,
+    };
+    async run() {
+        const { args, flags } = await this.parse(Content);
+        this.ensureOutputFlags(flags);
+        this.ensureVerbosityFlags(flags);
+        if (!args.itemId) {
+            this.fail("itemId is required", 2, flags);
+        }
+        const payload = {
+            endpoint: `/items/${encodeURIComponent(args.itemId)}/content`,
+            query: {
+                ...(flags.format ? { format: flags.format } : {}),
+                ...(flags.start ? { start: flags.start } : {}),
+            },
+            headers: {
+                ...(flags["hs-user"] ? { "hs-user": flags["hs-user"] } : {}),
+            },
+        };
+        if (flags["dry-run"]) {
+            this.printJson(payload);
+            return;
+        }
+        try {
+            const client = this.clientFromFlags(flags);
+            const data = await client.getItemContent({
+                itemId: args.itemId,
+                format: flags.format,
+                start: flags.start,
+                hsUser: this.effectiveHsUser(flags),
+            });
+            if (this.outputMode(flags) === "plain") {
+                writeContentPlain(data.content);
+                return;
+            }
+            this.printJson(data);
+        }
+        catch (error) {
+            this.handleError(error, flags);
+        }
+    }
+}
+function writeContentPlain(content) {
+    if (typeof content === "string") {
+        process.stdout.write(content);
+        if (!content.endsWith("\n")) {
+            process.stdout.write("\n");
+        }
+        return;
+    }
+    process.stdout.write(`${JSON.stringify(content, null, 2)}\n`);
+}

package/dist/commands/help.js

@@ -0,0 +1,23 @@
+import { Args, Command, loadHelpClass } from "@oclif/core";
+export default class Help extends Command {
+    static description = "Show help for a command";
+    static args = {
+        command: Args.string({
+            description: "Command to show help for",
+            required: false,
+        }),
+    };
+    static examples = [
+        "highspot help",
+        "highspot help search",
+        "highspot search --help",
+        "highspot -h",
+    ];
+    async run() {
+        const { args } = await this.parse(Help);
+        const HelpClass = await loadHelpClass(this.config);
+        const help = new HelpClass(this.config, this.config.pjson.oclif.helpOptions ?? this.config.pjson.helpOptions);
+        const argv = args.command ? [args.command] : [];
+        await help.showHelp(argv);
+    }
+}

package/dist/commands/item.js

@@ -0,0 +1,66 @@
+import { Args } from "@oclif/core";
+import { BaseCommand } from "../lib/command.js";
+import { globalFlags } from "../lib/flags.js";
+export default class Item extends BaseCommand {
+    static description = "Fetch metadata for a Highspot item";
+    static examples = [
+        "highspot item it_abc123",
+        "highspot item it_abc123 --hs-user user@example.com",
+        "highspot item it_abc123 --plain",
+    ];
+    static args = {
+        itemId: Args.string({
+            description: "Highspot item id",
+            required: false,
+        }),
+    };
+    static flags = {
+        ...globalFlags,
+    };
+    async run() {
+        const { args, flags } = await this.parse(Item);
+        this.ensureOutputFlags(flags);
+        this.ensureVerbosityFlags(flags);
+        if (!args.itemId) {
+            this.fail("itemId is required", 2, flags);
+        }
+        const payload = {
+            endpoint: `/items/${encodeURIComponent(args.itemId)}`,
+            headers: {
+                ...(flags["hs-user"] ? { "hs-user": flags["hs-user"] } : {}),
+            },
+        };
+        if (flags["dry-run"]) {
+            this.printJson(payload);
+            return;
+        }
+        try {
+            const client = this.clientFromFlags(flags);
+            const data = await client.getItem({
+                itemId: args.itemId,
+                hsUser: this.effectiveHsUser(flags),
+            });
+            if (this.outputMode(flags) === "plain") {
+                writeItemPlain(data.item);
+                return;
+            }
+            this.printJson(data);
+        }
+        catch (error) {
+            this.handleError(error, flags);
+        }
+    }
+}
+function writeItemPlain(item) {
+    if (typeof item !== "object" || item === null || Array.isArray(item)) {
+        process.stdout.write(`${JSON.stringify(item)}\n`);
+        return;
+    }
+    const record = item;
+    const id = typeof record.id === "string" ? record.id : "";
+    const title = typeof record.title === "string" ? record.title : "";
+    const url = typeof record.url === "string" ? record.url : "";
+    const contentType = typeof record.content_type === "string" ? record.content_type : "";
+    const description = typeof record.description === "string" ? record.description : "";
+    process.stdout.write(`${id}\t${url}\t${title}\t${contentType}\t${description}\n`);
+}

package/dist/commands/me.js

@@ -0,0 +1,48 @@
+import { BaseCommand } from "../lib/command.js";
+import { globalFlags } from "../lib/flags.js";
+export default class Me extends BaseCommand {
+    static description = "Fetch /me from the Highspot API";
+    static aliases = ["whoami"];
+    static examples = ["highspot me", "highspot me --plain", "highspot whoami"];
+    static flags = {
+        ...globalFlags,
+    };
+    async run() {
+        const { flags } = await this.parse(Me);
+        this.ensureOutputFlags(flags);
+        this.ensureVerbosityFlags(flags);
+        const payload = {
+            endpoint: "/me",
+            headers: {
+                ...(flags["hs-user"] ? { "hs-user": flags["hs-user"] } : {}),
+            },
+        };
+        if (flags["dry-run"]) {
+            this.printJson(payload);
+            return;
+        }
+        try {
+            const client = this.clientFromFlags(flags);
+            const data = await client.getMe({ hsUser: this.effectiveHsUser(flags) });
+            if (this.outputMode(flags) === "plain") {
+                writeMePlain(data);
+                return;
+            }
+            this.printJson(data);
+        }
+        catch (error) {
+            this.handleError(error, flags);
+        }
+    }
+}
+function writeMePlain(data) {
+    if (typeof data !== "object" || data === null || Array.isArray(data)) {
+        process.stdout.write(`${JSON.stringify(data)}\n`);
+        return;
+    }
+    const record = data;
+    const id = typeof record.id === "string" ? record.id : "";
+    const email = typeof record.email === "string" ? record.email : "";
+    const name = typeof record.name === "string" ? record.name : "";
+    process.stdout.write(`${id}\t${email}\t${name}\n`);
+}

package/dist/commands/search.js

@@ -0,0 +1,78 @@
+import { Args } from "@oclif/core";
+import { BaseCommand } from "../lib/command.js";
+import { globalFlags, searchFlags } from "../lib/flags.js";
+export default class Search extends BaseCommand {
+    static description = "Search Highspot items";
+    static examples = [
+        'highspot search "GoGuardian Teacher"',
+        'highspot search "Beacon" --limit 5 --sort-by date_added',
+        'highspot search "Hall Pass" --with-fields spot,id,title,url --plain',
+        'highspot search "Fleet" --dry-run',
+    ];
+    static args = {
+        query: Args.string({
+            description: "Search query",
+            required: false,
+        }),
+    };
+    static flags = {
+        ...globalFlags,
+        ...searchFlags,
+    };
+    async run() {
+        const { args, flags } = await this.parse(Search);
+        this.ensureOutputFlags(flags);
+        this.ensureVerbosityFlags(flags);
+        if (!args.query) {
+            this.fail("query is required", 2, flags);
+        }
+        const sortBy = flags["sort-by"];
+        const normalizedSortBy = sortBy === "relevancy" || sortBy === "date_added" ? sortBy : undefined;
+        if (sortBy && !normalizedSortBy) {
+            this.fail("--sort-by must be one of: relevancy, date_added", 2, flags);
+        }
+        const payload = {
+            endpoint: "/search/items",
+            query: {
+                "query-string": args.query,
+                ...(flags.limit !== undefined ? { limit: flags.limit } : {}),
+                ...(flags.start !== undefined ? { start: flags.start } : {}),
+                ...(normalizedSortBy ? { sortby: normalizedSortBy } : {}),
+                ...(flags["with-fields"]
+                    ? { "with-fields": flags["with-fields"] }
+                    : {}),
+            },
+            headers: {
+                ...(flags["hs-user"] ? { "hs-user": flags["hs-user"] } : {}),
+            },
+        };
+        if (flags["dry-run"]) {
+            this.printJson(payload);
+            return;
+        }
+        try {
+            const client = this.clientFromFlags(flags);
+            const data = await client.searchItems({
+                query: args.query,
+                limit: flags.limit,
+                start: flags.start,
+                sortBy: normalizedSortBy,
+                withFields: flags["with-fields"],
+                hsUser: this.effectiveHsUser(flags),
+            });
+            if (this.outputMode(flags) === "plain") {
+                writeSearchPlain(data);
+                return;
+            }
+            this.printJson(data);
+        }
+        catch (error) {
+            this.handleError(error, flags);
+        }
+    }
+}
+function writeSearchPlain(data) {
+    for (const [index, item] of data.results.entries()) {
+        process.stdout.write(`${index + 1}\t${item.id}\t${item.url}\t${item.title}\t${item.contentType}\n`);
+    }
+}

package/dist/lib/api.js

@@ -0,0 +1,215 @@
+import { Buffer } from "node:buffer";
+const TEXTUAL_CONTENT_TYPE_HINTS = [
+    "application/xml",
+    "application/xhtml+xml",
+    "application/csv",
+    "application/rtf",
+    "application/markdown",
+    "application/x-markdown",
+    "text/csv",
+    "text/html",
+    "text/markdown",
+];
+export class ApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.name = "ApiError";
+        this.status = status;
+        this.body = body;
+    }
+}
+const sleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+function sanitizeEndpoint(endpoint) {
+    return endpoint.replace(/\/+$/, "");
+}
+function looksTextual(contentType) {
+    if (contentType.startsWith("text/")) {
+        return true;
+    }
+    return TEXTUAL_CONTENT_TYPE_HINTS.some((hint) => contentType.includes(hint));
+}
+export class HighspotClient {
+    #authorizationHeader;
+    #endpoint;
+    #hsUser;
+    #maxRetries;
+    #retryDelayMs;
+    #timeoutMs;
+    constructor(config) {
+        this.#authorizationHeader = `Basic ${Buffer.from(`${config.apiKeyId}:${config.apiKeySecret}`).toString("base64")}`;
+        this.#endpoint = sanitizeEndpoint(config.endpoint);
+        this.#hsUser = config.hsUser;
+        this.#maxRetries = config.maxRetries;
+        this.#retryDelayMs = config.retryDelayMs;
+        this.#timeoutMs = config.timeoutMs;
+    }
+    #buildUrl(pathname) {
+        return new URL(`${this.#endpoint}${pathname}`);
+    }
+    async #fetchWithRetry(args) {
+        let response;
+        for (let attempt = 0; attempt <= this.#maxRetries; attempt += 1) {
+            const controller = new AbortController();
+            const timeoutHandle = setTimeout(() => controller.abort(), this.#timeoutMs);
+            try {
+                response = await fetch(args.url, {
+                    method: "GET",
+                    headers: {
+                        Accept: "*/*",
+                        Authorization: this.#authorizationHeader,
+                        ...((args.hsUser ?? this.#hsUser)
+                            ? { "hs-user": args.hsUser ?? this.#hsUser }
+                            : {}),
+                    },
+                    signal: controller.signal,
+                });
+            }
+            catch (error) {
+                if (attempt === this.#maxRetries) {
+                    throw error;
+                }
+                const delayMs = this.#retryDelayMs * (attempt + 1);
+                await sleep(delayMs);
+                continue;
+            }
+            finally {
+                clearTimeout(timeoutHandle);
+            }
+            if (response.ok) {
+                return response;
+            }
+            if (attempt < this.#maxRetries &&
+                (response.status === 429 || response.status >= 500)) {
+                const delayMs = this.#retryDelayMs * (attempt + 1);
+                await sleep(delayMs);
+                continue;
+            }
+            const body = await readResponseBody(response);
+            throw new ApiError(`Highspot request "${args.operation}" failed with status ${response.status}`, response.status, body);
+        }
+        throw new Error(`Highspot request "${args.operation}" failed unexpectedly`);
+    }
+    async searchItems(args) {
+        const limit = args.limit ?? 10;
+        const start = args.start ?? 0;
+        const url = this.#buildUrl("/search/items");
+        url.searchParams.set("query-string", args.query);
+        url.searchParams.set("limit", String(limit));
+        if (args.start !== undefined) {
+            url.searchParams.set("start", String(args.start));
+        }
+        if (args.sortBy) {
+            url.searchParams.set("sortby", args.sortBy);
+        }
+        if (args.withFields) {
+            url.searchParams.set("with-fields", args.withFields);
+        }
+        const response = await this.#fetchWithRetry({
+            operation: "searchItems",
+            url,
+            ...(args.hsUser ? { hsUser: args.hsUser } : {}),
+        });
+        const payload = (await response.json());
+        const source = payload.collection ?? payload.results ?? [];
+        const results = source
+            .filter((item) => typeof item.id === "string" && item.id.trim().length > 0)
+            .map((item) => ({
+            contentType: item.content_type ?? "",
+            description: item.description ?? "",
+            id: item.id ?? "",
+            title: item.title ?? "",
+            url: item.url ?? "",
+        }));
+        return {
+            limit,
+            query: args.query,
+            results,
+            start,
+            total: payload.counts_total ?? payload.total_results ?? results.length,
+        };
+    }
+    async getItem(args) {
+        const url = this.#buildUrl(`/items/${encodeURIComponent(args.itemId)}`);
+        const response = await this.#fetchWithRetry({
+            operation: "getItem",
+            url,
+            ...(args.hsUser ? { hsUser: args.hsUser } : {}),
+        });
+        const payload = (await response.json());
+        return { item: payload };
+    }
+    async getItemContent(args) {
+        const url = this.#buildUrl(`/items/${encodeURIComponent(args.itemId)}/content`);
+        if (args.format) {
+            url.searchParams.set("format", args.format);
+        }
+        if (args.start) {
+            url.searchParams.set("start", args.start);
+        }
+        const response = await this.#fetchWithRetry({
+            operation: "getItemContent",
+            url,
+            ...(args.hsUser ? { hsUser: args.hsUser } : {}),
+        });
+        const contentType = response.headers.get("content-type")?.split(";")[0]?.trim() ||
+            "application/octet-stream";
+        if (contentType.includes("json")) {
+            const payload = (await response.json());
+            return {
+                content: payload,
+                contentEncoding: "json",
+                contentType,
+                isBinary: false,
+                isJson: true,
+                itemId: args.itemId,
+            };
+        }
+        if (!looksTextual(contentType)) {
+            const binary = await response.arrayBuffer();
+            return {
+                content: Buffer.from(binary).toString("base64"),
+                contentEncoding: "base64",
+                contentLength: binary.byteLength,
+                contentType,
+                isBinary: true,
+                isJson: false,
+                itemId: args.itemId,
+            };
+        }
+        const textContent = await response.text();
+        return {
+            content: textContent,
+            contentEncoding: "utf8",
+            contentLength: textContent.length,
+            contentType,
+            isBinary: false,
+            isJson: false,
+            itemId: args.itemId,
+        };
+    }
+    async getMe(args = {}) {
+        const url = this.#buildUrl("/me");
+        const response = await this.#fetchWithRetry({
+            operation: "getMe",
+            url,
+            ...(args.hsUser ? { hsUser: args.hsUser } : {}),
+        });
+        return (await response.json());
+    }
+}
+async function readResponseBody(response) {
+    const text = await response.text();
+    if (!text) {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}

package/dist/lib/command.js

@@ -0,0 +1,62 @@
+import { Command } from "@oclif/core";
+import { ApiError, HighspotClient } from "./api.js";
+import { ConfigError, loadResolvedConfig } from "./config.js";
+import { formatApiError, resolveOutputMode, writeError, writeJson, } from "./output.js";
+export class BaseCommand extends Command {
+    outputMode(flags) {
+        return resolveOutputMode(flags);
+    }
+    ensureOutputFlags(flags) {
+        if (flags.json && flags.plain) {
+            this.fail("--json and --plain cannot be used together", 2, flags);
+        }
+    }
+    ensureVerbosityFlags(flags) {
+        if (flags.quiet && flags.verbose) {
+            this.fail("--quiet and --verbose cannot be used together", 2, flags);
+        }
+    }
+    clientFromFlags(flags) {
+        const config = loadResolvedConfig({
+            endpoint: flags.endpoint,
+            hsUser: flags["hs-user"],
+            maxRetries: flags["max-retries"],
+            retryDelayMs: flags["retry-delay-ms"],
+            timeoutMs: flags["timeout-ms"],
+        });
+        return new HighspotClient(config);
+    }
+    effectiveHsUser(flags) {
+        return flags["hs-user"];
+    }
+    printJson(data) {
+        writeJson(data);
+    }
+    fail(message, exitCode, flags) {
+        const mode = this.outputMode(flags);
+        writeError(mode, { error: message });
+        this.exit(exitCode);
+    }
+    failWithHint(message, hint, exitCode, flags) {
+        const mode = this.outputMode(flags);
+        writeError(mode, { error: message, hint });
+        this.exit(exitCode);
+    }
+    handleError(error, flags) {
+        const mode = this.outputMode(flags);
+        if (error instanceof ApiError) {
+            writeError(mode, formatApiError(error));
+            this.exit(1);
+        }
+        if (error instanceof ConfigError) {
+            writeError(mode, {
+                error: error.message,
+                hint: "Set HIGHSPOT_API_KEY_ID and HIGHSPOT_API_KEY_SECRET, or configure .highspot-cli.json.",
+            });
+            this.exit(2);
+        }
+        const message = error instanceof Error ? error.message : "Unknown error";
+        writeError(mode, { error: message });
+        this.exit(1);
+    }
+}

package/dist/lib/config.js

@@ -0,0 +1,114 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+const DEFAULT_ENDPOINT = "https://api.highspot.com/v1.0";
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_RETRY_DELAY_MS = 1200;
+const DEFAULT_TIMEOUT_MS = 30000;
+function readConfigFile(path) {
+    if (!existsSync(path)) {
+        return {};
+    }
+    const raw = readFileSync(path, "utf8").trim();
+    if (!raw) {
+        return {};
+    }
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new ConfigError(`Invalid config file at ${path}: expected a JSON object.`);
+    }
+    return parsed;
+}
+function toInteger(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return Math.trunc(value);
+    }
+    if (typeof value === "string" && value.trim()) {
+        const parsed = Number.parseInt(value.trim(), 10);
+        if (!Number.isNaN(parsed)) {
+            return parsed;
+        }
+    }
+    return undefined;
+}
+function normalize(config) {
+    return {
+        endpoint: typeof config.endpoint === "string" ? config.endpoint.trim() : undefined,
+        hsUser: typeof config.hsUser === "string" ? config.hsUser.trim() : undefined,
+        maxRetries: toInteger(config.maxRetries),
+        retryDelayMs: toInteger(config.retryDelayMs),
+        timeoutMs: toInteger(config.timeoutMs),
+        apiKeyId: typeof config.apiKeyId === "string" ? config.apiKeyId.trim() : undefined,
+        apiKeySecret: typeof config.apiKeySecret === "string"
+            ? config.apiKeySecret.trim()
+            : undefined,
+    };
+}
+function systemConfigPath() {
+    if (process.platform === "win32") {
+        const programData = process.env.PROGRAMDATA ?? "C:\\ProgramData";
+        return join(programData, "highspot-cli", "config.json");
+    }
+    return "/etc/highspot-cli/config.json";
+}
+function userConfigPath() {
+    const xdg = process.env.XDG_CONFIG_HOME;
+    if (xdg?.trim()) {
+        return join(xdg, "highspot-cli", "config.json");
+    }
+    const home = process.env.HOME;
+    if (!home?.trim()) {
+        return join(process.cwd(), ".highspot-cli.user.json");
+    }
+    return join(home, ".config", "highspot-cli", "config.json");
+}
+function projectConfigPath() {
+    return join(process.cwd(), ".highspot-cli.json");
+}
+function fromEnv() {
+    return normalize({
+        endpoint: process.env.HIGHSPOT_API_ENDPOINT,
+        hsUser: process.env.HIGHSPOT_HS_USER,
+        maxRetries: process.env.HIGHSPOT_MAX_RETRIES,
+        retryDelayMs: process.env.HIGHSPOT_RETRY_DELAY_MS,
+        timeoutMs: process.env.HIGHSPOT_TIMEOUT_MS,
+        apiKeyId: process.env.HIGHSPOT_API_KEY_ID,
+        apiKeySecret: process.env.HIGHSPOT_API_KEY_SECRET,
+    });
+}
+function overlay(base, next) {
+    return {
+        ...base,
+        ...Object.fromEntries(Object.entries(next).filter(([, value]) => value !== undefined)),
+    };
+}
+export function loadResolvedConfig(overrides = {}) {
+    let config = normalize(readConfigFile(systemConfigPath()));
+    config = overlay(config, normalize(readConfigFile(userConfigPath())));
+    config = overlay(config, normalize(readConfigFile(projectConfigPath())));
+    config = overlay(config, fromEnv());
+    config = overlay(config, normalize(overrides));
+    const maxRetries = toInteger(config.maxRetries) ?? DEFAULT_MAX_RETRIES;
+    const retryDelayMs = toInteger(config.retryDelayMs) ?? DEFAULT_RETRY_DELAY_MS;
+    const timeoutMs = toInteger(config.timeoutMs) ?? DEFAULT_TIMEOUT_MS;
+    if (!config.apiKeyId) {
+        throw new ConfigError("Missing HIGHSPOT_API_KEY_ID. Set env vars or configure apiKeyId in .highspot-cli.json.");
+    }
+    if (!config.apiKeySecret) {
+        throw new ConfigError("Missing HIGHSPOT_API_KEY_SECRET. Set env vars or configure apiKeySecret in .highspot-cli.json.");
+    }
+    return {
+        endpoint: config.endpoint || DEFAULT_ENDPOINT,
+        hsUser: config.hsUser,
+        maxRetries,
+        retryDelayMs,
+        timeoutMs,
+        apiKeyId: config.apiKeyId,
+        apiKeySecret: config.apiKeySecret,
+    };
+}

package/dist/lib/flags.js

@@ -0,0 +1,75 @@
+import { Flags } from "@oclif/core";
+export const globalFlags = {
+    json: Flags.boolean({
+        description: "Output JSON (default)",
+        default: false,
+    }),
+    plain: Flags.boolean({
+        description: "Output stable, line-based text",
+        default: false,
+    }),
+    "dry-run": Flags.boolean({
+        description: "Print request details and exit without calling the API",
+        default: false,
+    }),
+    "no-input": Flags.boolean({
+        description: "Disable any interactive prompts (none are used today)",
+        default: false,
+    }),
+    "no-color": Flags.boolean({
+        description: "Disable color output",
+        default: false,
+    }),
+    quiet: Flags.boolean({
+        description: "Reduce non-essential output",
+        default: false,
+    }),
+    verbose: Flags.boolean({
+        description: "Increase diagnostic output",
+        default: false,
+    }),
+    "hs-user": Flags.string({
+        description: "Highspot user context header (hs-user)",
+    }),
+    endpoint: Flags.string({
+        description: "Override Highspot API endpoint",
+    }),
+    "timeout-ms": Flags.integer({
+        description: "HTTP timeout in milliseconds",
+        min: 1,
+    }),
+    "max-retries": Flags.integer({
+        description: "Retry attempts for throttled/transient errors",
+        min: 0,
+    }),
+    "retry-delay-ms": Flags.integer({
+        description: "Base retry delay in milliseconds",
+        min: 1,
+    }),
+};
+export const searchFlags = {
+    limit: Flags.integer({
+        description: "Results per page",
+        min: 1,
+        max: 100,
+    }),
+    start: Flags.integer({
+        description: "Search offset",
+        min: 0,
+    }),
+    "sort-by": Flags.string({
+        description: "Sort order",
+        options: ["relevancy", "date_added"],
+    }),
+    "with-fields": Flags.string({
+        description: "Comma-separated list of extra fields to return",
+    }),
+};
+export const contentFlags = {
+    format: Flags.string({
+        description: "Optional format query parameter forwarded to /content",
+    }),
+    start: Flags.string({
+        description: "Optional cursor/start token for paginated content",
+    }),
+};

package/dist/lib/help.js

@@ -0,0 +1,23 @@
+import { Help as OclifHelp } from "@oclif/core";
+const AUTH_TEXT = "Requires HIGHSPOT_API_KEY_ID and HIGHSPOT_API_KEY_SECRET via env or config file.";
+const CONFIG_TEXT = "Precedence: flags > env > project config (.highspot-cli.json) > user config (~/.config/highspot-cli/config.json) > system config.";
+export default class Help extends OclifHelp {
+    formatRoot() {
+        const base = super.formatRoot();
+        const auth = this.section("AUTH", AUTH_TEXT);
+        const config = this.section("CONFIG", CONFIG_TEXT);
+        const examples = this.section("EXAMPLES", this.renderList([
+            ["highspot --help"],
+            ['highspot search "GoGuardian Teacher" --limit 5'],
+            ["highspot item it_abc123 --plain"],
+            ["highspot content it_abc123 --format text/plain --plain"],
+            ["highspot me --json"],
+        ], { indentation: 2, spacer: "\n", stripAnsi: this.opts.stripAnsi }));
+        return `${base}\n\n${auth}\n\n${config}\n\n${examples}`;
+    }
+    formatCommand(command) {
+        const base = super.formatCommand(command);
+        const auth = this.section("AUTH", AUTH_TEXT);
+        return `${base}\n${auth}`;
+    }
+}

package/dist/lib/output.js

@@ -0,0 +1,29 @@
+export function resolveOutputMode(flags) {
+    return flags.plain ? "plain" : "json";
+}
+export function writeJson(data) {
+    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+}
+export function writeError(mode, error) {
+    if (mode === "plain") {
+        process.stderr.write(`${error.error}\n`);
+        if (error.hint) {
+            process.stderr.write(`hint: ${error.hint}\n`);
+        }
+        return;
+    }
+    process.stderr.write(`${JSON.stringify(error, null, 2)}\n`);
+}
+export function formatApiError(err) {
+    if (typeof err.body === "object" && err.body !== null) {
+        return {
+            error: "API error",
+            status: err.status,
+            details: err.body,
+        };
+    }
+    return {
+        error: err.body ? String(err.body) : err.message,
+        status: err.status,
+    };
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "highspot-cli",
+  "version": "0.1.1",
+  "description": "Agent-first CLI for the Highspot API",
+  "license": "MIT",
+  "author": "Advait Shinde",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/advait/highspot-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/advait/highspot-cli/issues"
+  },
+  "homepage": "https://github.com/advait/highspot-cli#readme",
+  "bin": {
+    "highspot": "dist/bin/highspot.js",
+    "highspot-cli": "dist/bin/highspot.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "npm run build && node dist/bin/highspot.js",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "check": "npm run typecheck && npm run lint",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20.10.0"
+  },
+  "dependencies": {
+    "@oclif/core": "^4.8.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.4",
+    "@types/node": "^25.0.3",
+    "typescript": "^5.9.3"
+  },
+  "oclif": {
+    "commands": "./dist/commands",
+    "bin": "highspot",
+    "additionalHelpFlags": [
+      "-h"
+    ],
+    "additionalVersionFlags": [
+      "-v"
+    ],
+    "helpClass": "./dist/lib/help.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "keywords": [
+    "highspot",
+    "cli",
+    "oclif",
+    "sales-enablement"
+  ]
+}