Metadata-Version: 2.4
Name: jabb-cli
Version: 0.2.0
Summary: CLI for JABB Public API v1 — locations, CX scores, reviews, PNIF, sentiment.
Author: JABB
License-Expression: MIT
Project-URL: Homepage, https://github.com/JAB-Bers/jabb-cli
Project-URL: Repository, https://github.com/JAB-Bers/jabb-cli
Project-URL: Issues, https://github.com/JAB-Bers/jabb-cli/issues
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: requests>=2.31
Requires-Dist: mcp<2,>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# jabb

CLI for JABB Public API v1 — locations, CX scores, reviews, PNIF, sentiment. A thin wrapper: every command is one HTTP GET, no business logic.

## Install

```bash
pip install -e .
```

## Quickstart

```bash
export JABB_API_KEY=jabb_test_...
jabb locations list
```

Time to first result: under 5 minutes from a minted key.

## Usage

```
jabb [--json] [--detailed] <resource> list [--cursor <opaque>] [--limit <1-100>]
```

Resources: `locations`, `scores`, `reviews`, `pnif`, `sentiment`.

- `--json` — print the raw API envelope (`{"data": [...], "next_cursor": ...}`) instead of a table. Use for scripting/agents.
- `--detailed` — request more fields per row (costs more tokens/bandwidth).
- `--cursor` — pass the previous response's `next_cursor` to page forward.
- `--limit` — rows per page, 1-100, default 20.

Examples:

```bash
jabb scores list --detailed
jabb reviews list --limit 5
jabb pnif list --json
jabb locations list --cursor eyJwIjo... --limit 50
```

## Auth

Set `JABB_API_KEY` to a key minted by your JABB admin (`jabb_live_...` in production, `jabb_test_...` for sandbox). No config file, no `--api-key` flag — env var only, so keys don't land in shell history.

For local development against a jabb-server instance running on your machine:

```bash
export JABB_API_BASE_URL=http://127.0.0.1:5500
```

Default base URL is `https://api.jabb.cx`. There is no automatic failover to `api.jabb.pro` — that host runs a separate, diverged database, and silently reading from it would risk returning stale data.

## Exit codes

| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Generic API error |
| 2 | Auth/config error (missing/invalid/revoked key, wrong scope) |
| 3 | Rate limited (message includes retry-after seconds) |

## MCP server (agent integration)

`jabb mcp` starts a **stdio MCP server** that exposes the same 5 resources as agent tools, so any MCP host (Claude Code, Claude Desktop, Cursor…) can query your JABB data with nothing but an API key.

### Tools exposed

| Tool | When to call |
|------|-------------|
| `jabb_list_locations` | User asks about branches/stores or needs location IDs |
| `jabb_get_cx_scores` | User wants quantitative CX quality metrics |
| `jabb_list_quick_jabbs` | User wants individual evaluation content / verbatim feedback |
| `jabb_get_pnif` | User asks for Price/Need/Impact/Frequency breakdown |
| `jabb_get_sentiment` | User asks for sentiment labels or topic-level trends |

All tools accept `cursor`, `limit`, `response_format` (`"concise"` | `"detailed"`). `jabb_get_pnif` and `jabb_get_sentiment` also accept `language` (ISO 639-1: `en`/`fr`/`ar`).

Responses are capped at ~25 KB. When truncated, the payload includes `"truncated": true` and preserves the original `next_cursor` so the agent can page forward.

API errors are returned as tool errors carrying the API's `code` + `hint` verbatim. 429 errors also include `Retry-After` seconds.

### Connect from Claude Code

```bash
# One-time setup (project scope):
claude mcp add jabb -- jabb mcp
```

Or add a project-scope `.mcp.json` at your repo root:

```json
{
  "mcpServers": {
    "jabb": {
      "command": "jabb",
      "args": ["mcp"],
      "env": {
        "JABB_API_KEY": "${JABB_API_KEY}"
      }
    }
  }
}
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "jabb": {
      "command": "jabb",
      "args": ["mcp"],
      "env": {
        "JABB_API_KEY": "jabb_live_..."
      }
    }
  }
}
```

### Environment variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `JABB_API_KEY` | Yes | — | API key minted by your JABB admin |
| `JABB_API_BASE_URL` | No | `https://api.jabb.cx` | Override for local dev |

## For Claude Code users

See `skills/jabb-cx/SKILL.md` — copy it into your project's `.claude/skills/jabb-cx/` to let Claude Code drive this CLI directly when you ask about your CX data. The MCP server (`jabb mcp`) is an alternative path that works with any MCP-capable host without the skill.

## Scope

Read-only. `list` operations against 5 resources, nothing else. No write/create/update commands exist.
