@orth/cli 0.2.0

package/README.md

@@ -0,0 +1,192 @@
+# Orthogonal CLI
+
+CLI to access all APIs and agent skills on the Orthogonal platform.
+
+![Demo](demos/demo.gif)
+
+## Installation
+
+```bash
+# Install globally
+npm install -g @orth/cli
+
+# Or use npx
+npx @orth/cli <command>
+```
+
+## Authentication
+
+```bash
+# Login with API key
+orth login --key orth_live_your_key
+
+# Or set environment variable
+export ORTHOGONAL_API_KEY=orth_live_your_key
+
+# Check auth status
+orth whoami
+
+# Logout
+orth logout
+```
+
+## API Commands
+
+### Search & Browse
+
+```bash
+# Search for APIs
+orth api search "email finder"
+orth api search "web scraping" --limit 20
+
+# List all APIs
+orth api list
+
+# Show API endpoints
+orth api show hunter
+
+# Show endpoint details
+orth api show hunter /v2/domain-search
+```
+
+### Call APIs
+
+```bash
+# GET request with query params
+orth api run hunter /v2/domain-search -q domain=stripe.com
+
+# POST request with body
+orth api run olostep /v1/scrapes --body '{"url": "https://stripe.com"}'
+
+# Raw output for piping
+orth api run hunter /v2/domain-search -q domain=stripe.com --raw | jq '.emails'
+```
+
+### Generate Code
+
+```bash
+# TypeScript (default)
+orth api code hunter /v2/domain-search
+
+# Python
+orth api code hunter /v2/domain-search --lang python
+
+# cURL
+orth api code hunter /v2/domain-search --lang curl
+```
+
+### Request an API
+
+```bash
+# Request an API to be added to the platform
+orth api request https://docs.example.com/api -d "Weather data API"
+```
+
+## Skills Commands
+
+### Browse & Search
+
+```bash
+# List verified & discoverable skills
+orth skills list
+
+# Search for skills
+orth skills search "react best practices"
+
+# Show skill details
+orth skills show owner/skill-name
+```
+
+### Install Skills
+
+```bash
+# Install a skill to all supported agents
+orth skills add owner/skill-name
+
+# Install for a specific agent only
+orth skills add owner/skill-name --agent cursor
+```
+
+Installs to 7 agent skill directories:
+
+| Agent | Directory |
+|-------|-----------|
+| Cursor | `~/.cursor/skills/` |
+| Claude Code | `~/.claude/skills/` |
+| GitHub Copilot | `~/.github/skills/` |
+| Windsurf | `~/.codeium/windsurf/skills/` |
+| Codex | `~/.agents/skills/` |
+| Gemini | `~/.gemini/skills/` |
+| OpenClaw | `~/.openclaw/skills/` |
+
+### Create & Publish Skills
+
+```bash
+# Initialize a new skill from template
+orth skills init my-skill
+orth skills init my-skill --bare  # SKILL.md only, no subdirectories
+
+# Create a skill from a GitHub repo
+orth skills create https://github.com/owner/repo
+orth skills create owner/repo --path skills/my-skill --ref main
+
+# Submit a local skill to the platform
+orth skills submit ./my-skill
+orth skills submit --name "My Skill" --tags "react,testing"
+
+# Request verification (required before discoverability)
+orth skills request-verification owner/my-skill
+
+# Request a skill to be added (by description or GitHub URL)
+orth skills request "A skill for React testing patterns"
+orth skills request https://github.com/owner/cool-skill
+```
+
+### Verification Workflow
+
+1. **Submit** your skill → it's on the platform but not publicly visible
+2. **Request verification** → our team reviews it
+3. **Once verified** → toggle discoverability on/off from your [dashboard](https://orthogonal.com/dashboard/skills)
+
+## Account
+
+```bash
+# Check balance
+orth balance
+
+# View usage
+orth usage --limit 20
+```
+
+## Shorthand Aliases
+
+These top-level commands are aliases for their `orth api` counterparts:
+
+```bash
+orth search "query"          # → orth api search "query"
+orth run slug /path          # → orth api run slug /path
+orth code slug /path         # → orth api code slug /path
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Watch mode
+npm run dev
+
+# Run tests
+npm test
+
+# Watch tests
+npm run test:watch
+```
+
+## License
+
+MIT

package/dist/analytics.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Fire-and-forget analytics event for CLI usage tracking.
+ * Never blocks, never throws, never shows errors to the user.
+ */
+export declare function trackEvent(command: string, args?: Record<string, string | undefined>): void;

package/dist/analytics.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trackEvent = trackEvent;
+const config_js_1 = require("./config.js");
+const CLI_VERSION = process.env.npm_package_version || "0.2.0";
+const BASE_URL = "https://api.orth.sh/v1";
+/**
+ * Fire-and-forget analytics event for CLI usage tracking.
+ * Never blocks, never throws, never shows errors to the user.
+ */
+function trackEvent(command, args) {
+    // Don't track if no API key (not authenticated)
+    const apiKey = (0, config_js_1.getApiKey)();
+    if (!apiKey)
+        return;
+    const payload = {
+        command,
+        args: args ? sanitizeArgs(args) : undefined,
+        cliVersion: CLI_VERSION,
+        os: process.platform,
+        nodeVersion: process.version,
+        apiKeyPrefix: apiKey.substring(0, 12),
+        timestamp: new Date().toISOString(),
+    };
+    // Fire and forget - don't await, don't catch visible errors
+    fetch(`${BASE_URL}/cli/events`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+            "x-orthogonal-source": "cli",
+        },
+        body: JSON.stringify(payload),
+    }).catch(() => {
+        // Silently ignore - analytics should never affect CLI operation
+    });
+}
+/**
+ * Remove any potentially sensitive values from args
+ */
+function sanitizeArgs(args) {
+    const sanitized = {};
+    const sensitiveKeys = ["key", "apiKey", "token", "secret", "password"];
+    for (const [key, value] of Object.entries(args)) {
+        if (sensitiveKeys.some((s) => key.toLowerCase().includes(s))) {
+            sanitized[key] = "[REDACTED]";
+        }
+        else {
+            sanitized[key] = value;
+        }
+    }
+    return sanitized;
+}

package/dist/api.d.ts

@@ -0,0 +1,81 @@
+export declare function apiRequest<T = unknown>(endpoint: string, options?: {
+    method?: string;
+    body?: unknown;
+}): Promise<T>;
+export interface SearchResponse {
+    results: Array<{
+        name: string;
+        slug: string;
+        endpoints: Array<{
+            path: string;
+            method: string;
+            description: string;
+            price?: number;
+        }>;
+    }>;
+    count: number;
+    apisCount: number;
+}
+export interface DetailsResponse {
+    api?: string | {
+        name: string;
+        slug: string;
+        description?: string;
+    };
+    path?: string;
+    method?: string;
+    description?: string;
+    price?: number | string;
+    parameters?: {
+        query?: Array<{
+            name: string;
+            type: string;
+            required: boolean;
+            description?: string;
+        }>;
+        body?: Array<{
+            name: string;
+            type: string;
+            required: boolean;
+            description?: string;
+        }>;
+    };
+    endpoint?: {
+        path: string;
+        method: string;
+        description?: string;
+        price?: number | string;
+        queryParams?: Array<{
+            name: string;
+            type: string;
+            required: boolean;
+            description?: string;
+        }>;
+        bodyParams?: Array<{
+            name: string;
+            type: string;
+            required: boolean;
+            description?: string;
+        }>;
+    };
+}
+export interface RunResponse {
+    success: boolean;
+    data: unknown;
+    price?: string;
+    priceCents?: number;
+    requestId?: string;
+}
+export interface IntegrateResponse {
+    api: string;
+    path: string;
+    snippets: Record<string, string>;
+}
+export declare function search(prompt: string, limit?: number): Promise<SearchResponse>;
+export declare function getDetails(api: string, path: string): Promise<DetailsResponse>;
+export declare function run(api: string, path: string, options?: {
+    method?: string;
+    query?: Record<string, string>;
+    body?: unknown;
+}): Promise<RunResponse>;
+export declare function integrate(api: string, path: string, format?: string): Promise<IntegrateResponse>;

package/dist/api.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiRequest = apiRequest;
+exports.search = search;
+exports.getDetails = getDetails;
+exports.run = run;
+exports.integrate = integrate;
+const config_js_1 = require("./config.js");
+const BASE_URL = "https://api.orth.sh/v1";
+async function apiRequest(endpoint, options = {}) {
+    const apiKey = (0, config_js_1.requireApiKey)();
+    const res = await fetch(`${BASE_URL}${endpoint}`, {
+        method: options.method || "GET",
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+            "x-orthogonal-source": "cli",
+        },
+        body: options.body ? JSON.stringify(options.body) : undefined,
+    });
+    const data = (await res.json());
+    if (!res.ok || data.success === false) {
+        // Include more details in error message
+        let errorMsg = data.error || `API request failed with status ${res.status}`;
+        // Add any additional error details from the response
+        if (data.message) {
+            errorMsg += `: ${data.message}`;
+        }
+        if (data.data?.error) {
+            errorMsg += ` - ${data.data.error}`;
+            if (data.data?.message) {
+                errorMsg += `: ${data.data.message}`;
+            }
+        }
+        // Handle Hunter-style errors array
+        if (data.data?.errors &&
+            Array.isArray(data.data.errors)) {
+            const errors = data.data.errors;
+            for (const err of errors) {
+                if (err.details) {
+                    errorMsg += `\n  → ${err.details}`;
+                }
+                else if (err.id) {
+                    errorMsg += `\n  → ${err.id}: ${err.code || ""}`;
+                }
+            }
+        }
+        if (data.details) {
+            errorMsg += `\n  Details: ${JSON.stringify(data.details)}`;
+        }
+        throw new Error(errorMsg);
+    }
+    // Return the whole response, not just data field
+    return data;
+}
+async function search(prompt, limit = 10) {
+    return apiRequest("/search", {
+        method: "POST",
+        body: { prompt, limit },
+    });
+}
+async function getDetails(api, path) {
+    return apiRequest("/details", {
+        method: "POST",
+        body: { api, path },
+    });
+}
+async function run(api, path, options = {}) {
+    return apiRequest("/run", {
+        method: "POST",
+        body: {
+            api,
+            path,
+            method: options.method || "GET",
+            query: options.query,
+            body: options.body,
+        },
+    });
+}
+async function integrate(api, path, format = "orth-sdk") {
+    return apiRequest("/integrate", {
+        method: "POST",
+        body: { api, path, format },
+    });
+}

package/dist/commands/account.d.ts

@@ -0,0 +1,4 @@
+export declare function balanceCommand(): Promise<void>;
+export declare function usageCommand(options: {
+    limit: string;
+}): Promise<void>;

package/dist/commands/account.js

@@ -0,0 +1,60 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.balanceCommand = balanceCommand;
+exports.usageCommand = usageCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const ora_1 = __importDefault(require("ora"));
+const api_js_1 = require("../api.js");
+async function balanceCommand() {
+    const spinner = (0, ora_1.default)("Fetching balance...").start();
+    try {
+        // Note: This endpoint may not exist yet - placeholder
+        const data = await (0, api_js_1.apiRequest)("/account/balance");
+        spinner.stop();
+        if (data && data.balance !== undefined) {
+            console.log(chalk_1.default.bold("\nAccount Balance:"));
+            console.log(chalk_1.default.green.bold(`  $${data.balance.toFixed(2)} ${data.currency || "USD"}`));
+        }
+        else {
+            console.log(chalk_1.default.gray("Balance information not available."));
+            console.log(chalk_1.default.gray("Check your balance at: https://orthogonal.com/dashboard"));
+        }
+    }
+    catch (error) {
+        spinner.stop();
+        // Graceful fallback if endpoint doesn't exist
+        console.log(chalk_1.default.gray("Balance information not available via API."));
+        console.log(chalk_1.default.gray("Check your balance at: https://orthogonal.com/dashboard"));
+    }
+}
+async function usageCommand(options) {
+    const spinner = (0, ora_1.default)("Fetching usage...").start();
+    try {
+        // Note: This endpoint may not exist yet - placeholder
+        const data = await (0, api_js_1.apiRequest)(`/account/usage?limit=${options.limit}`);
+        spinner.stop();
+        if (data?.usage && data.usage.length > 0) {
+            console.log(chalk_1.default.bold("\nRecent API Usage:\n"));
+            for (const item of data.usage) {
+                const date = new Date(item.timestamp).toLocaleString();
+                console.log(chalk_1.default.gray(date.padEnd(22)) +
+                    chalk_1.default.cyan(item.api.padEnd(15)) +
+                    chalk_1.default.white(item.path.padEnd(30)) +
+                    chalk_1.default.green(`$${item.cost.toFixed(4)}`));
+            }
+            console.log(chalk_1.default.bold(`\nTotal: $${data.total.toFixed(2)}`));
+        }
+        else {
+            console.log(chalk_1.default.gray("No recent usage data available."));
+        }
+    }
+    catch (error) {
+        spinner.stop();
+        // Graceful fallback if endpoint doesn't exist
+        console.log(chalk_1.default.gray("Usage information not available via API."));
+        console.log(chalk_1.default.gray("Check your usage at: https://orthogonal.com/dashboard/usage"));
+    }
+}

package/dist/commands/api.d.ts

@@ -0,0 +1,6 @@
+interface ApiOptions {
+    x402?: boolean;
+    x402Full?: boolean;
+}
+export declare function apiCommand(slug?: string, path?: string, options?: ApiOptions): Promise<void>;
+export {};

package/dist/commands/api.js

@@ -0,0 +1,150 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiCommand = apiCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const ora_1 = __importDefault(require("ora"));
+const api_js_1 = require("../api.js");
+async function apiCommand(slug, path, options) {
+    const spinner = (0, ora_1.default)("Loading...").start();
+    try {
+        if (!slug) {
+            // List all APIs - search multiple terms to get broader coverage
+            const searches = await Promise.all([
+                (0, api_js_1.search)("api", 50),
+                (0, api_js_1.search)("data", 50),
+                (0, api_js_1.search)("search", 50),
+                (0, api_js_1.search)("email", 50),
+            ]);
+            spinner.stop();
+            // Merge and dedupe results
+            const allResults = searches.flatMap(s => s.results || []);
+            const data = {
+                results: allResults,
+                count: allResults.length,
+                apisCount: new Set(allResults.map(r => r.slug)).size,
+            };
+            console.log(chalk_1.default.bold("\nAvailable APIs:\n"));
+            const seen = new Set();
+            for (const api of data.results) {
+                if (!api.slug || seen.has(api.slug))
+                    continue;
+                seen.add(api.slug);
+                console.log(chalk_1.default.cyan.bold(api.slug.padEnd(20)) +
+                    chalk_1.default.white(api.name || "") +
+                    chalk_1.default.gray(` (${api.endpoints?.length || 0} endpoints)`));
+            }
+            console.log(chalk_1.default.gray("\nRun 'orth api <slug>' to see endpoints for an API"));
+            return;
+        }
+        if (path) {
+            // Show endpoint details
+            const data = await (0, api_js_1.getDetails)(slug, path);
+            spinner.stop();
+            console.log(chalk_1.default.bold(`\n${chalk_1.default.cyan(slug)}${chalk_1.default.white(path)}\n`));
+            // Get description from endpoint object if available
+            const desc = data.description || data.endpoint?.description;
+            console.log(chalk_1.default.gray(desc || "No description"));
+            // Get price
+            const price = data.price || data.endpoint?.price;
+            if (price) {
+                console.log(chalk_1.default.green(`\nPrice: ${typeof price === 'number' ? '$' + price : price}`));
+            }
+            // Get params from nested endpoint object if needed
+            const queryParams = data.parameters?.query || data.endpoint?.queryParams || [];
+            const bodyParams = data.parameters?.body || data.endpoint?.bodyParams || [];
+            if (queryParams.length > 0) {
+                console.log(chalk_1.default.bold("\nQuery Parameters:"));
+                for (const param of queryParams) {
+                    const required = param.required ? chalk_1.default.red("*") : "";
+                    console.log(chalk_1.default.yellow(`  ${param.name}${required}`) +
+                        chalk_1.default.gray(` (${param.type})`) +
+                        (param.description ? chalk_1.default.gray(` - ${param.description}`) : ""));
+                }
+            }
+            if (bodyParams.length > 0) {
+                console.log(chalk_1.default.bold("\nBody Parameters:"));
+                for (const param of bodyParams) {
+                    const required = param.required ? chalk_1.default.red("*") : "";
+                    console.log(chalk_1.default.yellow(`  ${param.name}${required}`) +
+                        chalk_1.default.gray(` (${param.type})`) +
+                        (param.description ? chalk_1.default.gray(` - ${param.description}`) : ""));
+                }
+            }
+            // Generate appropriate example
+            console.log(chalk_1.default.gray("\nExample:"));
+            if (bodyParams.length > 0) {
+                const exampleBody = {};
+                for (const param of bodyParams.slice(0, 3)) {
+                    exampleBody[param.name] = param.type === 'object' ? '{}' : `<${param.name}>`;
+                }
+                console.log(chalk_1.default.white(`  orth run ${slug} ${path} --body '${JSON.stringify(exampleBody)}'`));
+            }
+            else if (queryParams.length > 0) {
+                const exampleQuery = queryParams.slice(0, 2).map((p) => `-q ${p.name}=<value>`).join(' ');
+                console.log(chalk_1.default.white(`  orth run ${slug} ${path} ${exampleQuery}`));
+            }
+            else {
+                console.log(chalk_1.default.white(`  orth run ${slug} ${path}`));
+            }
+            // x402 direct payment info
+            if (options?.x402 || options?.x402Full) {
+                const x402Url = `https://x402.orth.sh/${slug}${path}`;
+                // Determine HTTP method: POST if body params, GET otherwise
+                const method = bodyParams.length > 0 ? 'POST' : 'GET';
+                if (options?.x402 && !options?.x402Full) {
+                    // Minimal output - just the URL
+                    console.log(`\n${x402Url}`);
+                }
+                else {
+                    // Full output - actually call the endpoint and get the 402 response
+                    try {
+                        const fetchOptions = { method };
+                        if (method === 'POST') {
+                            fetchOptions.headers = { 'Content-Type': 'application/json' };
+                            fetchOptions.body = '{}';
+                        }
+                        const response = await fetch(x402Url, fetchOptions);
+                        const responseData = await response.json();
+                        console.log(chalk_1.default.bold.magenta("\n── x402 Payment Details ──\n"));
+                        console.log(chalk_1.default.cyan(`URL: ${x402Url}`));
+                        console.log(chalk_1.default.yellow(`Method: ${method}`));
+                        console.log(chalk_1.default.gray(`Status: ${response.status}\n`));
+                        console.log(JSON.stringify(responseData, null, 2));
+                    }
+                    catch (err) {
+                        console.log(chalk_1.default.red(`\nFailed to fetch x402 details: ${err}`));
+                    }
+                }
+            }
+            return;
+        }
+        // Show API endpoints
+        const data = await (0, api_js_1.search)(slug, 20);
+        spinner.stop();
+        const api = data.results.find((a) => a.slug === slug);
+        if (!api) {
+            console.log(chalk_1.default.yellow(`API '${slug}' not found.`));
+            console.log(chalk_1.default.gray("Run 'orth api' to see available APIs"));
+            return;
+        }
+        console.log(chalk_1.default.bold(`\n${chalk_1.default.cyan(api.name)} (${api.slug})\n`));
+        for (const endpoint of api.endpoints) {
+            const method = chalk_1.default.yellow(endpoint.method.padEnd(6));
+            const price = endpoint.price ? chalk_1.default.green(`$${endpoint.price.toFixed(2)}`) : chalk_1.default.gray("free");
+            console.log(`${method} ${chalk_1.default.white(endpoint.path)} ${price}`);
+            if (endpoint.description) {
+                console.log(chalk_1.default.gray(`       ${endpoint.description.slice(0, 80)}${endpoint.description.length > 80 ? "..." : ""}`));
+            }
+        }
+        console.log(chalk_1.default.gray("\nRun 'orth api " + slug + " <path>' for endpoint details"));
+        console.log(chalk_1.default.gray("Run 'orth run " + slug + " <path>' to call an endpoint"));
+    }
+    catch (error) {
+        spinner.stop();
+        console.error(chalk_1.default.red(`Error: ${error instanceof Error ? error.message : "Unknown error"}`));
+        process.exit(1);
+    }
+}

package/dist/commands/apiRequest.d.ts

@@ -0,0 +1,6 @@
+/**
+ * orth api request <docsUrl> - Request an API to be added to the platform
+ */
+export declare function apiRequestCommand(docsUrl: string, options: {
+    description?: string;
+}): Promise<void>;

package/dist/commands/apiRequest.js

@@ -0,0 +1,36 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiRequestCommand = apiRequestCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const ora_1 = __importDefault(require("ora"));
+const api_js_1 = require("../api.js");
+/**
+ * orth api request <docsUrl> - Request an API to be added to the platform
+ */
+async function apiRequestCommand(docsUrl, options) {
+    const spinner = (0, ora_1.default)("Submitting API request...").start();
+    try {
+        await (0, api_js_1.apiRequest)("/requests/api", {
+            method: "POST",
+            body: {
+                docsUrl,
+                description: options.description,
+            },
+        });
+        spinner.stop();
+        console.log(chalk_1.default.green("\n✓ API request submitted!"));
+        console.log(chalk_1.default.gray("Our team has been notified and will review your request."));
+        console.log(chalk_1.default.gray(`  Docs URL: ${docsUrl}`));
+        if (options.description) {
+            console.log(chalk_1.default.gray(`  Notes: ${options.description}`));
+        }
+    }
+    catch (error) {
+        spinner.stop();
+        console.error(chalk_1.default.red(`Error: ${error instanceof Error ? error.message : "Unknown error"}`));
+        process.exit(1);
+    }
+}