@ogment-ai/cli 0.3.5 → 0.4.0

package/README.md

@@ -1,145 +1,159 @@
 # Ogment CLI
 
-**Secure your AI agents' SaaS credentials.**
+<!-- Generated from docs/command-spec.json via scripts/sync-command-docs.mjs -->
+
+Agent-first CLI for discovering and invoking Ogment-backed tools.
 
 Package: `@ogment-ai/cli`  
 Binary: `ogment`
 
-Ogment sits between your AI agent and your SaaS tools. Your agent gets a scoped, revocable API key — your real credentials never leave Ogment.
-
 ## Install
 
 ```bash
-# Global install (recommended)
 npm install -g @ogment-ai/cli
-
-# One-off usage without installing globally
-npx @ogment-ai/cli --help
 ```
 
+## Core Behavior
+
+1. Output is machine-readable JSON by default.
+2. Use `--human` for readable terminal output.
+3. Default login flow is device-code + human approval.
+4. Discovery uses progressive disclosure (`catalog` -> `catalog tools` -> `catalog tool`).
+
 ## Quick Start
 
 ```bash
-# Log in (opens browser for OAuth + agent selection)
-ogment login
+# 1) Authenticate (device flow by default)
+ogment auth login
+
+# 2) Discover servers (summary only)
+ogment catalog
+
+# 3) Narrow to one server when already known
+ogment catalog --server <server-id>
 
-# List available servers
-ogment servers
+# 4) Discover tools for one server
+ogment catalog tools <server-id>
 
-# Show runtime configuration and connectivity diagnostics
-ogment info
+# 5) Inspect one tool schema and include generated example input
+ogment catalog tool <server-id> <tool-name> --example
+
+# 6) Invoke
+ogment invoke <server-id>/<tool-name> --input '{}'
 
-# Call a tool
-ogment call <server> <tool> '{"param": "value"}'
 ```
 
-## Development
+## Commands
+
+### `ogment auth login`
 
-### Run Tests
+Default device-code login.
 
 ```bash
-pnpm test          # Single run
-pnpm test:coverage # Coverage (text + html + lcov)
-pnpm test:changed  # Run tests related to changed files
-pnpm test:ci       # CI profile (coverage + CI reporters)
+ogment auth login
 ```
 
-## Commands
+### `ogment auth login --browser`
 
-### `ogment login`
+Fallback browser callback flow.
 
-Authenticate with the Ogment platform. Opens your browser for OAuth sign-in, then shows an agent picker where you create or select an agent. The resulting API key is stored locally.
+```bash
+ogment auth login --browser
+```
+
+### `ogment auth login --api-key <key>`
+
+Last-resort path for CI/unattended setups.
 
 ```bash
-ogment login
+ogment auth login --api-key "$OGMENT_API_KEY"
 ```
 
-### `ogment login --device`
+### `ogment auth status`
 
-For headless or remote environments (VMs, CI servers) where a browser isn't available. Displays a short code that you enter on the Ogment dashboard from any device.
+Show credential presence/source.
 
 ```bash
-ogment login --device
+ogment auth status
+```
+
+### `ogment auth logout`
 
-# Shows:
-#   Enter this code on the Ogment dashboard:
-#     ABCD-1234
-#   Open: https://dashboard.ogment.ai/cli/activate
+Revoke and clear local credentials.
+
+```bash
+ogment auth logout
 ```
 
-### `ogment servers [path]`
+### `ogment catalog`
 
-List configured servers or inspect a server's tools.
+Server metadata only (includes `toolCount`, no full tool schemas). Supports cursor pagination and server filtering.
 
 ```bash
-ogment servers                # List all servers
-ogment servers <path>         # Inspect tools
-ogment servers --json         # Machine-readable output
+ogment catalog
+ogment catalog --limit 20
+ogment catalog --cursor <last-server-id> --limit 20
+ogment catalog --server billing
 ```
 
-### `ogment call <server> <tool> [args]`
+### `ogment catalog tools <server-id>`
 
-Call a tool on an Ogment server. Always outputs JSON.
+Tool summaries for one server.
 
 ```bash
-ogment call ecommerce-api get__health
-ogment call ecommerce-api get__api_products_ '{"limit":2}'
+ogment catalog tools billing
 ```
 
-### `ogment logout`
+### `ogment catalog tool <server-id> <tool-name>`
 
-Delete local credentials. To revoke the API key (prevent all access), use the Ogment dashboard.
+Full details and schemas for one tool.
 
 ```bash
-ogment logout
+ogment catalog tool billing get_health
+ogment catalog tool billing get_health --example
 ```
 
-### `ogment info`
+### `ogment invoke <server-id>/<tool-name>`
 
-Show effective runtime configuration, auth source, and live connectivity diagnostics against the configured Ogment base URL.
+Invoke a tool with one input mode.
 
 ```bash
-ogment info
-ogment info --json
+ogment invoke billing/get_health --input '{}'
+ogment invoke billing/get_health --input @./payload.json
+cat payload.json | ogment invoke billing/get_health --input -
 ```
 
-## Authentication Model
+### `ogment status`
 
-Ogment uses **Clerk API keys** for machine authentication:
+Runtime and connectivity diagnostics.
 
-1. **`ogment login`** — Human authenticates via OAuth, picks an agent → Clerk API key created
-2. **API key stored locally** — At `~/.config/ogment/credentials.json`
-3. **All requests use the API key** — Sent as `Authorization: Bearer <api-key>`
-4. **Revoke anytime** — In the Ogment dashboard → Agents tab
+```bash
+ogment status
+```
 
-### For Remote VMs
+## Global Options
 
-Use the device flow (`ogment login --device`) — the human approves from their own device, the VM never sees credentials or a browser. The API key is the only credential the VM receives.
+```bash
+--api-key <key>     API key override
+--human             Human-readable output
+--quiet             Suppress non-essential output
+--non-interactive   Disable interactive behavior
+--yes               Assume yes for confirmations
+```
 
 ## Environment Variables
 
 | Variable | Default | Description |
 |---|---|---|
-| `OGMENT_BASE_URL` | `https://dashboard.ogment.ai` | Ogment platform URL (for development) |
-| `OGMENT_API_KEY` | — | API key (alternative to `ogment login`) |
+| `OGMENT_BASE_URL` | `https://dashboard.ogment.ai` | Ogment platform URL |
+| `OGMENT_API_KEY` | `—` | API key fallback |
 
-## How It Works
+## Development
 
-```
-AI Agent (Claude, Cursor, ChatGPT)
-    │
-    │  Clerk API key (long-lived, revocable)
-    ▼
-┌─────────────────────────────────┐
-│       Ogment MCP Proxy          │
-│  ✓ Validate API key             │
-│  ✓ Inject real credentials      │
-│  ✓ Log every tool call          │
-└──────────────┬──────────────────┘
-               │
-    ┌──────────┼──────────┐
-    ▼          ▼          ▼
-Salesforce   Linear    Snowflake
+```bash
+pnpm test
+pnpm test:e2e
+pnpm build
 ```
 
 ## License

package/dist/cli.d.ts

@@ -5,7 +5,7 @@ import { type InfoService } from "./services/info.js";
 import { type ExitCode } from "./shared/exit-codes.js";
 export interface GlobalCliOptions {
     apiKey: string | undefined;
-    json: boolean | undefined;
+    human: boolean | undefined;
     nonInteractive: boolean | undefined;
     quiet: boolean | undefined;
     yes: boolean | undefined;

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AASA,OAAO,KAAK,EAAE,cAAc,EAAmB,MAAM,uBAAuB,CAAC;AAQ7E,OAAO,EAAE,aAAa,EAA0B,MAAM,qBAAqB,CAAC;AAG5E,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGzE,OAAO,EAAa,KAAK,QAAQ,EAAoB,MAAM,wBAAwB,CAAC;AAIpF,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,IAAI,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1B,cAAc,EAAE,OAAO,GAAG,SAAS,CAAC;IACpC,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,GAAG,EAAE,OAAO,GAAG,SAAS,CAAC;CAC1B;AAED,UAAU,OAAO;IACf,OAAO,EAAE,cAAc,CAAC;IACxB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,MAAM,EAAE,aAAa,CAAC;CACvB;AAyfD,eAAO,MAAM,MAAM,GACjB,OAAM,SAAS,MAAM,EAA0B,EAC/C,UAAS,OAAyB,KACjC,OAAO,CAAC,QAAQ,CAmBlB,CAAC;AAEF,eAAO,MAAM,UAAU,QAAa,OAAO,CAAC,IAAI,CAG/C,CAAC;AAMF,eAAO,MAAM,gBAAgB,GAAI,eAAe,MAAM,EAAE,OAAO,MAAM,GAAG,SAAS,KAAG,OAanF,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAmBA,OAAO,KAAK,EAAE,cAAc,EAAmB,MAAM,uBAAuB,CAAC;AAO7E,OAAO,EAAE,aAAa,EAA0B,MAAM,qBAAqB,CAAC;AAG5E,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAazE,OAAO,EAAa,KAAK,QAAQ,EAAoB,MAAM,wBAAwB,CAAC;AAapF,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,cAAc,EAAE,OAAO,GAAG,SAAS,CAAC;IACpC,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,GAAG,EAAE,OAAO,GAAG,SAAS,CAAC;CAC1B;AAED,UAAU,OAAO;IACf,OAAO,EAAE,cAAc,CAAC;IACxB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,MAAM,EAAE,aAAa,CAAC;CACvB;AAy5BD,eAAO,MAAM,MAAM,GACjB,OAAM,SAAS,MAAM,EAA0B,EAC/C,UAAS,OAAyB,KACjC,OAAO,CAAC,QAAQ,CAuBlB,CAAC;AAEF,eAAO,MAAM,UAAU,QAAa,OAAO,CAAC,IAAI,CAG/C,CAAC;AAMF,eAAO,MAAM,gBAAgB,GAAI,eAAe,MAAM,EAAE,OAAO,MAAM,GAAG,SAAS,KAAG,OAanF,CAAC"}