@orth/cli 0.2.28 → 0.2.29

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orthogonal
+
+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

@@ -1,204 +1,269 @@
+<div align="center">
+
 # Orthogonal CLI
 
-CLI to access all APIs and agent skills on the Orthogonal platform.
+**One command line for every API and agent skill on the [Orthogonal](https://orthogonal.com) platform.**
+
+Discover APIs in natural language, call them with a single command, and pay per request from your Orthogonal credit balance — no per-provider signups, keys, or contracts.
+
+[![npm version](https://img.shields.io/npm/v/@orth/cli.svg?logo=npm&color=cb3837)](https://www.npmjs.com/package/@orth/cli)
+[![npm downloads](https://img.shields.io/npm/dm/@orth/cli.svg?color=cb3837)](https://www.npmjs.com/package/@orth/cli)
+[![node](https://img.shields.io/node/v/@orth/cli.svg?logo=node.js&color=339933)](https://nodejs.org)
+[![license](https://img.shields.io/npm/l/@orth/cli.svg?color=blue)](./LICENSE)
 
 ![Demo](https://raw.githubusercontent.com/orthogonal-sh/cli/main/demos/demo.gif)
 
+</div>
+
+## Table of Contents
+
+- [Why Orthogonal](#why-orthogonal)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Authentication](#authentication)
+- [Calling APIs](#calling-apis)
+- [Agent Skills](#agent-skills)
+- [Scheduled Tasks](#scheduled-tasks)
+- [Account & Usage](#account--usage)
+- [Command Reference](#command-reference)
+- [Configuration](#configuration)
+- [Programmatic Use](#programmatic-use)
+- [Development](#development)
+- [License](#license)
+
+## Why Orthogonal
+
+Orthogonal is a marketplace of production APIs and agent skills behind one account and one balance. The CLI lets you — and your AI agents — find and call any of them without leaving the terminal:
+
+- **Discover** APIs and skills with natural-language search.
+- **Call** any endpoint with one command — auth, billing, and routing are handled for you.
+- **Pay per use** from a single credit balance instead of juggling dozens of provider subscriptions.
+- **Script it** — clean JSON output (`--raw`) pipes straight into `jq` and shell pipelines.
+
 ## Installation
 
+Requires **Node.js 18+**.
+
 ```bash
 # Install globally
 npm install -g @orth/cli
 
-# Or use npx
+# …or run without installing
 npx @orth/cli <command>
 ```
 
+Verify the install:
+
+```bash
+orth --version
+```
+
+## Quick Start
+
+```bash
+# 1. Authenticate (get a key at https://orthogonal.com)
+orth login --key orth_live_your_key
+
+# 2. Find an API in plain English
+orth api search "search the web"
+
+# 3. Call an endpoint
+orth run tavily /search -q query="latest AI news"
+
+# 4. See what it cost
+orth balance
+```
+
 ## Authentication
 
 ```bash
-# Login with API key
+# Log in with your API key (stored in your OS user-config directory)
 orth login --key orth_live_your_key
 
-# Or set environment variable
+# …or use an environment variable (takes precedence — great for CI)
 export ORTHOGONAL_API_KEY=orth_live_your_key
 
-# Check auth status
+# Show the current identity
 orth whoami
 
-# Logout
+# Remove the stored key
 orth logout
 ```
 
-## API Commands
+Get an API key from your [Orthogonal dashboard](https://orthogonal.com/dashboard).
 
-### Search & Browse
+## Calling APIs
+
+### Discover & inspect
 
 ```bash
-# Search for APIs
-orth api search "email finder"
-orth api search "web scraping" --limit 20
+# Natural-language search across the marketplace
+orth api search "generate images"
 
-# List all APIs
+# List every available API
 orth api list
 
-# Show API endpoints
-orth api show hunter
+# Show an API's endpoints
+orth api show tavily
 
-# Show endpoint details
-orth api show hunter /v2/domain-search
+# Show one endpoint's parameters, pricing, and schema
+orth api show tavily /search
 ```
 
-### Call APIs
+### Call an endpoint
 
 ```bash
-# GET request with query params
-orth run hunter /v2/domain-search -q domain=stripe.com
-
-# Multiple query params (two ways)
-orth run searchapi /api/v1/search -q 'engine=amazon_search&q=wireless earbuds'
-orth run searchapi /api/v1/search -q engine=amazon_search -q q=wireless earbuds
-
-# POST request with body
-orth run olostep /v1/scrapes -d '{"url": "https://stripe.com"}'
+# GET with query params
+orth run fantastic-jobs /v1/active-ats -q time_frame=1h -q limit=10
 
-# Raw output for piping
-orth run hunter /v2/domain-search -q domain=stripe.com --raw | jq '.emails'
-```
+# Query params can also be passed as a single string
+orth run fantastic-jobs /v1/active-ats -q "time_frame=1h&limit=10"
 
-### Generate Code
+# POST with a JSON body
+orth run some-api /v1/generate -X POST -b '{"prompt":"a red bicycle"}'
 
-```bash
-# TypeScript (default)
-orth api code hunter /v2/domain-search
+# Estimate the cost without spending credits
+orth run some-api /v1/generate --dry-run
 
-# Python
-orth api code hunter /v2/domain-search --lang python
+# Save a binary response (image, audio, PDF, …) to a file
+orth run image-api /v1/render -q prompt="sunset" -o out.png
 
-# cURL
-orth api code hunter /v2/domain-search --lang curl
+# Machine-readable output for pipelines
+orth run tavily /search -q query="orthogonal" --raw | jq '.results[0].url'
 ```
 
-### Request an API
+### Generate integration code
+
+Scaffold a ready-to-run snippet for any endpoint:
 
 ```bash
-# Request an API to be added to the platform
-orth api request https://docs.example.com/api -d "Weather data API"
+orth api code tavily /search                 # TypeScript (default)
+orth api code tavily /search --lang python   # Python
+orth api code tavily /search --lang curl     # cURL
 ```
 
-## Skills Commands
-
-### Browse & Search
+### Request a new API
 
 ```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
+orth api request https://docs.example.com/api
 ```
 
-### Install Skills
+## Agent Skills
 
-```bash
-# Install a skill to all supported agents
-orth skills add owner/skill-name
+Skills are packaged capabilities your AI agents can install and run. Browse the library, publish your own, and sync them to your local agent directories.
 
-# Install for a specific agent only
-orth skills add owner/skill-name --agent cursor
+```bash
+# Browse & search
+orth skills list                     # verified, discoverable skills
+orth skills search "web scraping"
+orth skills show <slug>              # details + files
+
+# Install into your local agent skill directories
+orth skills add <slug>              # alias: orth skills install <slug>
+
+# Author & publish
+orth skills init [name]             # scaffold a SKILL.md template
+orth skills create <owner/repo>    # create a skill from a GitHub repo
+orth skills submit [path]          # submit a local skill
+orth skills push <slug> [path]     # push local changes to the platform
+orth skills update <slug> [path]   # pull the latest version locally
+orth skills mine                   # list your skills
+orth skills request-verification <slug>
+orth skills request <input>        # request a skill by URL or description
 ```
 
-Installs to 7 agent skill directories:
+**Verification workflow:** to make a skill discoverable to others, go `init`/`create` → `submit` → `request-verification`. Once approved, it becomes discoverable in the library.
 
-| 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/` |
+## Scheduled Tasks
 
-### Create & Publish Skills
+Run API calls and skills on a schedule.
 
 ```bash
-# Initialize a new skill from template
-orth skills init my-skill
-orth skills init my-skill --bare  # SKILL.md only, no subdirectories
+orth tasks list                # your scheduled tasks
+orth tasks create              # create a task
+orth tasks show <id>           # task details
+orth tasks trigger <id>        # run it now
+orth tasks logs <id>           # run history
+orth tasks pause <id>          # pause
+orth tasks resume <id>         # resume
+orth tasks delete <id>         # delete
+```
 
-# 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
+## Account & Usage
 
-# Submit a local skill to the platform
-orth skills submit ./my-skill
-orth skills submit --name "My Skill" --tags "react,testing"
+```bash
+orth balance   # current credit balance
+orth usage     # recent API usage
+```
 
-# Update local skill from platform (pull)
-orth skills update owner/my-skill
-orth skills update owner/my-skill ./local-dir --force
+## Command Reference
 
-# Push local changes to platform
-orth skills push owner/my-skill
-orth skills push owner/my-skill ./local-dir
+| Command | Description |
+| --- | --- |
+| `orth login` / `logout` / `whoami` | Manage authentication |
+| `orth balance` / `usage` | Credit balance and recent usage |
+| `orth api list` | List available APIs |
+| `orth api search <query>` | Natural-language API search |
+| `orth api show <slug> [path]` | Show endpoints / endpoint details (alias: `info`) |
+| `orth api run <slug> <path>` | Call an endpoint |
+| `orth api code <slug> <path>` | Generate integration code |
+| `orth api request <docsUrl>` | Request an API to be added |
+| `orth skills …` | Browse, install, author, and publish skills |
+| `orth tasks …` | Create and manage scheduled tasks |
 
-# Request verification (required before discoverability)
-orth skills request-verification owner/my-skill
+**Shorthand aliases** for the most common commands:
 
-# 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
+```bash
+orth search <query>       # → orth api search
+orth run <slug> <path>    # → orth api run
+orth code <slug> <path>   # → orth api code
 ```
 
-### Verification Workflow
+Run `orth <command> --help` for the full options on any command.
 
-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)
+### `run` options
 
-## Account
+| Flag | Description |
+| --- | --- |
+| `-X, --method <method>` | HTTP method (default `GET`) |
+| `-q, --query <k=v...>` | Query params (repeatable, or one `a=1&b=2` string) |
+| `-b, --body <json>` / `-d, --data <json>` | JSON request body |
+| `-o, --output <file>` | Save the response to a file (auto-detects binary) |
+| `--raw` | Print raw JSON (ideal for piping) |
+| `--dry-run` | Estimate the cost without executing |
 
-```bash
-# Check balance
-orth balance
+## Configuration
 
-# View usage
-orth usage --limit 20
-```
+| Environment variable | Purpose |
+| --- | --- |
+| `ORTHOGONAL_API_KEY` | API key; overrides the stored credential (use in CI) |
+| `ORTH_API_URL` | Override the API base URL (advanced) |
 
-## Shorthand Aliases
+Credentials from `orth login` are stored in your OS user-config directory (managed automatically); use `orth logout` to remove them.
 
-These top-level commands are aliases for their `orth api` counterparts:
+## Programmatic Use
+
+Building an application instead of scripting the terminal? Use the official TypeScript SDK, [`@orth/sdk`](https://www.npmjs.com/package/@orth/sdk):
 
 ```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
+npm install @orth/sdk
 ```
 
 ## Development
 
 ```bash
-# Install dependencies
+git clone https://github.com/orthogonal-sh/cli.git
+cd cli
 npm install
 
-# Build
-npm run build
-
-# Watch mode
-npm run dev
-
-# Run tests
-npm test
-
-# Watch tests
-npm run test:watch
+npm run build      # compile TypeScript to dist/
+npm run dev        # compile in watch mode
+npm test           # run the test suite (vitest)
+npm start          # run the built CLI
 ```
 
+Contributions are welcome — please open an issue or a pull request.
+
 ## License
 
-MIT
+[MIT](./LICENSE) © Orthogonal

package/dist/api.js

@@ -25,8 +25,10 @@ async function apiRequest(endpoint, options = {}) {
     // or non-JSON body, which would otherwise throw here and lose the status.
     const rawBody = await res.text();
     let data;
+    let bodyParsed = false;
     try {
         data = (rawBody ? JSON.parse(rawBody) : {});
+        bodyParsed = rawBody.length > 0;
     }
     catch {
         data = {};
@@ -64,6 +66,19 @@ async function apiRequest(endpoint, options = {}) {
         // string-matching the message (e.g. whoami treating 404 as "no /me").
         const err = new Error(errorMsg);
         err.status = res.status;
+        // Surface the self-correction hint the API attaches on contract violations
+        // (missing/out-of-range params, upstream 4xx). Without this the run command
+        // only sees `error.message` and the expected-schema diagnostics are lost.
+        if (data._orthogonal) {
+            err.orthogonal = data._orthogonal;
+        }
+        // Keep the full parsed error body too, so callers can render structured
+        // diagnostics (missing / out_of_range) and emit machine-readable JSON.
+        // Only when the body actually parsed as JSON — otherwise a non-JSON body
+        // would surface as `{}` and mask the real error message.
+        if (bodyParsed) {
+            err.responseBody = data;
+        }
         throw err;
     }
     // Return the whole response, not just data field

package/dist/commands/run.js

@@ -58,6 +58,80 @@ function isBinaryEnvelope(data) {
         typeof data.contentType === "string" &&
         typeof data.size === "number");
 }
+/**
+ * Render the API's self-correction diagnostics attached to a failed run.
+ * Pulls the `_orthogonal` hint (expected schema + field diagnostics) plus the
+ * top-level `missing` / `out_of_range` arrays from the error response body.
+ * The upstream-4xx path returns the schema ONLY inside `_orthogonal`, and the
+ * pre-validation path returns `out_of_range` at the top level — so without this
+ * the concrete violation is invisible in the human output.
+ */
+function printFailureHint(body) {
+    if (!body || typeof body !== "object")
+        return;
+    const hint = body._orthogonal;
+    const hasHint = hint && typeof hint === "object";
+    const outOfRange = Array.isArray(body.out_of_range) ? body.out_of_range : [];
+    const missing = Array.isArray(body.missing) ? body.missing : [];
+    if (!hasHint && outOfRange.length === 0 && missing.length === 0)
+        return;
+    console.error(chalk_1.default.yellow("\nHint:"));
+    if (hasHint && hint.message)
+        console.error(chalk_1.default.gray(`  ${hint.message}`));
+    if (missing.length > 0) {
+        console.error(chalk_1.default.gray("  Missing required params: ") + chalk_1.default.white(missing.join(", ")));
+    }
+    if (outOfRange.length > 0) {
+        const parts = outOfRange.map((p) => {
+            const bounds = [
+                typeof p.min === "number" ? `>= ${p.min}` : null,
+                typeof p.max === "number" ? `<= ${p.max}` : null,
+            ]
+                .filter(Boolean)
+                .join(" and ");
+            return bounds ? `${p.name}=${p.value} (must be ${bounds})` : `${p.name}=${p.value}`;
+        });
+        console.error(chalk_1.default.gray("  Out of range: ") + chalk_1.default.white(parts.join(", ")));
+    }
+    if (!hasHint)
+        return;
+    const diagnostics = [
+        ["Missing required query params", hint.missing_required_query],
+        ["Unexpected query fields", hint.unexpected_query_fields],
+        ["Missing required body params", hint.missing_required_body],
+        ["Unexpected body fields", hint.unexpected_body_fields],
+    ];
+    for (const [label, value] of diagnostics) {
+        if (Array.isArray(value) && value.length > 0) {
+            console.error(chalk_1.default.gray(`  ${label}: `) + chalk_1.default.white(value.join(", ")));
+        }
+    }
+    const summarize = (schema, kind) => {
+        if (!schema?.properties)
+            return;
+        const required = new Set(schema.required || []);
+        const names = Object.keys(schema.properties).map((name) => {
+            const prop = schema.properties[name] || {};
+            const bits = [name];
+            if (required.has(name))
+                bits.push("(required)");
+            const range = [
+                typeof prop.minimum === "number" ? `min ${prop.minimum}` : null,
+                typeof prop.maximum === "number" ? `max ${prop.maximum}` : null,
+            ]
+                .filter(Boolean)
+                .join(", ");
+            if (range)
+                bits.push(`[${range}]`);
+            return bits.join(" ");
+        });
+        if (names.length > 0) {
+            console.error(chalk_1.default.gray(`  Expected ${kind}: `) + chalk_1.default.white(names.join(", ")));
+        }
+    };
+    summarize(hint.expected_schema?.queryParams, "query params");
+    summarize(hint.expected_schema?.body, "body params");
+}
 function formatCost(result) {
     if (result.price)
         return result.price;
@@ -67,7 +141,11 @@ function formatCost(result) {
     return null;
 }
 async function runCommand(api, path, options) {
-    const spinner = (0, ora_1.default)(`Calling ${api}${path}...`).start();
+    // In --raw mode keep the streams clean for piping: don't animate the spinner
+    // on stderr, so a failed call's stderr is a single parseable JSON document.
+    const spinner = (0, ora_1.default)(`Calling ${api}${path}...`);
+    if (!options.raw)
+        spinner.start();
     try {
         // Parse query params
         // Supports both `-q key=value -q key2=value2` and `-q 'key=value&key2=value2'`
@@ -190,7 +268,24 @@ async function runCommand(api, path, options) {
     }
     catch (error) {
         spinner.stop();
-        console.error(chalk_1.default.red(`Error: ${error instanceof Error ? error.message : "Unknown error"}`));
+        const err = error;
+        const message = error instanceof Error ? error.message : "Unknown error";
+        if (options.raw) {
+            // In --raw mode, stderr must always be a single parseable JSON document
+            // so agents can JSON.parse it. Prefer the server's parsed body; otherwise
+            // (e.g. a non-JSON HTML 502) emit a synthesized error envelope.
+            const envelope = err?.responseBody ?? {
+                success: false,
+                error: message,
+                ...(typeof err?.status === "number" ? { status: err.status } : {}),
+            };
+            console.error(JSON.stringify(envelope, null, 2));
+        }
+        else {
+            console.error(chalk_1.default.red(`Error: ${message}`));
+            if (err?.responseBody)
+                printFailureHint(err.responseBody);
+        }
         process.exit(1);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orth/cli",
-  "version": "0.2.28",
+  "version": "0.2.29",
   "description": "CLI to access all APIs and skills on the Orthogonal platform",
   "main": "dist/index.js",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "build": "tsc",