Metadata-Version: 2.4
Name: jentic-apitools-cli
Version: 1.0.0a17
Summary: Jentic Apitools CLI — public-apis repository interactions (import, bulk-rescore, rebuild-*, improve)
Author: Jentic
Author-email: Jentic <hello@jentic.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Requires-Dist: pydantic>=2.7,<3.0
Requires-Dist: jentic-apitools-common~=1.0.0a17
Requires-Dist: jentic-apitools-pipelines~=1.0.0a17
Requires-Dist: jentic-apitools-jobs~=1.0.0a17
Requires-Dist: jentic-apitools-public-apis-client~=1.0.0a17
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: httpx>=0.27,<1.0
Requires-Dist: pyyaml>=6.0
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/jentic/jentic-apitools
Description-Content-Type: text/markdown

# Jentic API Tools - CLI

Click-based OSS command-line interface for the Jentic public-apis repository workflows: importing specs, opening improve PRs against [`jentic-public-apis`](https://github.com/jentic/jentic-public-apis), and bulk repository operations on a local clone. Scoring and analysis commands moved to the separate, internal-only [`score-cli`](../score-cli/README.md) package.

## Prerequisites

Node.js (>= 18) is required for full functionality. The CLI uses npx to run Redocly, Spectral, and Speclynx for OpenAPI validation and bundling. Without Node.js, the tool still runs but produces partial results using only the built-in Python validation backends. Install Node.js from https://nodejs.org/.

## Key Features

The CLI registers as the `jentic-apitools` entry point and provides six commands. The `import` command processes a spec through the full import pipeline, producing scored and cataloged artifacts written to a directory or ZIP archive. The `improve` command applies an improve set (an updated bundled spec plus any number of Overlay 1.1.x documents and a markdown changelog) to an existing version directory in the public-apis repository and opens a PR — post-refactor it calls the [`public-apis-client`](../public-apis-client/README.md) library directly via `prepare_improve_context` and `submit_improve`, with no API hop. The remaining four commands operate against a local clone of the public-apis repository: `bulk-rescore` iterates all specs and copies updated scorecards back, `recalculate-scores` rebuilds the `scores.json` index, `rebuild-scores-json` and `rebuild-apis-json` rebuild the catalog files.

The `import` and `improve` commands accept input as a local file path, an HTTP(S) URL, or stdin (using `-` with optional `--stdin-filepath` for `import`, or `-` for any of `improve`'s `--spec`, `--overlay`, `--changelog` slots; only one slot per `improve` invocation may consume stdin). The `import` command writes its artifacts to a directory (via `--output`) or to a ZIP archive (via `--archive`) and emits a summary JSON document to stdout. The `improve` command emits a JSON payload describing the resulting PR (or the failure) to stdout. The `-q`/`--quiet` flag, available on `import` and `improve`, suppresses log output so only command results appear on stdout, useful when piping to tools like `jq`.

## LLM Configuration

The `--enable-llm-analysis` flag (on `import` and `improve`) and the `bulk-rescore` command (which always uses LLM) require credentials for the configured LLM provider. Set `LLM_PROVIDER` and `LIGHT_LLM_PROVIDER` (default: `BEDROCK`) and provide the corresponding API key:

| Provider | Required environment variable |
|---|---|
| `OPENAI` | `OPENAI_API_KEY` or `JENTIC_OPENAI_API_KEY` |
| `CLAUDE` / `ANTHROPIC` | `ANTHROPIC_API_KEY` or `JENTIC_ANTHROPIC_API_KEY` |
| `GEMINI` | `GEMINI_API_KEY` or `JENTIC_GEMINI_API_KEY` |
| `BEDROCK` | AWS credentials via boto3 (IAM role, `~/.aws/credentials`, or AWS `AWS_BEARER_TOKEN_BEDROCK` env vars) |

See `.env.example` for the full list of configuration options. The CLI validates credentials at startup and provides actionable error messages if they are missing.

## Dependencies

Internal: `jentic.apitools.common`, `jentic.apitools.pipelines`, `jentic.apitools.jobs`, `jentic.apitools.public_apis_client`. External: click, rich, httpx, pyyaml, pydantic.

## Installation

The recommended way to install is with [pipx](https://pipx.pypa.io/) or [uv tool](https://docs.astral.sh/uv/guides/tools/), which run the CLI in an isolated environment without affecting your system Python:

```bash
# Using pipx
pipx install jentic-apitools-cli

# Using uv
uv tool install jentic-apitools-cli
```

Alternatively, install with pip:

```bash
pip install jentic-apitools-cli
```

Once installed, the `jentic-apitools` command is available on your PATH:

```bash
jentic-apitools --help
```

## Quick Start

```bash
# Import from URL to directory
jentic-apitools import https://petstore3.swagger.io/api/v3/openapi.json \
  --output ./output --label example.com/api

# Import to ZIP archive
jentic-apitools import openapi.json --archive output.zip

# Open an improve PR against jentic-public-apis
jentic-apitools improve --vendor acme.com --api main --version 1.0.0 \
  --changelog CHANGELOG.md --overlay overlay.yaml

# Bulk-rescore all specs in a local clone
jentic-apitools bulk-rescore /path/to/jentic-public-apis --dry-run
```

### import

The `import` command processes an OpenAPI specification through the full import pipeline.

```bash
jentic-apitools import <SPEC> (--output DIR | --archive FILE.zip) [--label LABEL] [--vendor VENDOR] [--api API] [--overwrite] [--enable-llm-analysis] [--skip-bundle] [--reject-invalid-server-urls / --no-reject-invalid-server-urls] [--reject-invalid-security / --no-reject-invalid-security] [--stdin-filepath PATH] [--original-url URL] [--api-id ID] [--api-version-id ID] [--canonical-source-url URL] [--canonical-artifacts-base-url URL] [--canonical-artifacts-base-url-ui URL]
```

Either `--output DIR` or `--archive FILE.zip` must be specified. With `--output`, artifacts are written to the directory. With `--archive`, they are packaged as a ZIP file. On success, a JSON manifest is written to stdout.

Options:

```
SPEC                         Local file path, URL, or - for stdin (required)
--output, -o DIR             Output directory for artifacts
--archive FILE.zip           Write artifacts as a ZIP archive
--label TEXT                 Vendor/API label (mutually exclusive with --vendor)
--vendor TEXT                Vendor name, combined with --api to form label
--api TEXT                   API name (default: main, requires --vendor)
--overwrite                  Overwrite existing output directory or archive
--enable-llm-analysis        Enable LLM-based semantic analysis
--skip-bundle                Skip bundling step
--reject-invalid-server-urls / --no-reject-invalid-server-urls
                             Reject specs with invalid server URLs (default: enabled)
--reject-invalid-security / --no-reject-invalid-security
                             Reject specs with invalid security definitions (default: enabled)
--stdin-filepath PATH        Virtual filepath for stdin input
--original-url URL           Original spec URL for provenance tracking
--api-id ID                  Logical API identifier
--api-version-id ID          Logical API version identifier
--canonical-source-url URL   Canonical source URL for metadata
--canonical-artifacts-base-url URL       Canonical base URL for raw artifacts
--canonical-artifacts-base-url-ui URL    Canonical base URL for UI artifact links
```

### improve

The `improve` command applies an improve set to an existing version directory in the public-apis repository and opens a pull request.

```bash
jentic-apitools improve --vendor V --api A --version X \
    [--spec SPEC] [--overlay OVERLAY ...] --changelog CHANGELOG \
    [--base-sha SHA] [--enable-llm-analysis]
```

Each of `--spec`, `--overlay`, and `--changelog` accepts a local file path, an HTTP(S) URL, or `-` for stdin. Only one slot per invocation may consume stdin; the second use raises a `BadParameter` naming both consumers. The CLI runs the improve orchestration directly against GitHub via `jentic.apitools.public_apis_client`; no API service is contacted. Authentication uses `GITHUB_TOKEN` from the environment.

Options:

```
--vendor TEXT                Vendor directory name, e.g. acme.com (required)
--api TEXT                   API directory name, e.g. main (required)
--version TEXT               Version directory name, e.g. 1.0.0 (required)
--spec SPEC                  Updated bundled spec (path / URL / -). Required
                             only when no --overlay is supplied.
--overlay OVERLAY            Overlay 1.1.x document (path / URL / -). Repeatable.
--changelog CHANGELOG        Markdown changelog (path / URL / -). Required.
--base-sha SHA               Optimistic-concurrency token compared against
                             the current head SHA of the base branch;
                             mismatch fails the run with the current SHA.
--enable-llm-analysis        Run the score pipeline with LLM analysis enabled.
                             The CLI runs synchronously regardless of this flag.
```

The output is a single JSON document on stdout with `success`, `pr_url`, `branch_name`, `vendor`, `api_name`, `version`, `base_sha_used`, `per_run_dir`, `score_delta`, `sanity_warning`, and `error` fields. On failure the process exits with code 1.

### bulk-rescore

The `bulk-rescore` command rescores all OpenAPI specs in a local clone of a repository with the `apis/openapi/<vendor>/<api>/<version>/openapi.json` directory structure. It runs `import_openapi` for each spec, then copies the updated `scorecard.json`, `diagnostics.json`, and the `diagnostics` section of `meta.json` back into the local repo. When not in dry-run mode, the command also recalculates `scores.json` with all scores sorted by value in descending order.

> **Note:** This command always uses LLM analysis. Ensure your LLM provider credentials are configured (see [LLM Configuration](#llm-configuration)).

```bash
jentic-apitools bulk-rescore /path/to/jentic-public-apis
jentic-apitools bulk-rescore /path/to/jentic-public-apis --max-iterations 2 --dry-run
```

Options:

```
LOCAL_REPO_PATH              Path to root of the local repo clone (required)
--github-repo-url TEXT       GitHub repository URL (default: https://github.com/jentic/jentic-public-apis)
--output-dir, -o PATH        Output directory for rescore results (default: __data__/rescore_<datetime>)
--github-repo-branch TEXT    GitHub repository branch (default: main)
--base-dir TEXT              Base directory for OpenAPI specs within the repo (default: apis/openapi)
--max-iterations INTEGER     Maximum number of APIs to process, useful for testing (default: no limit)
--dry-run                    Run without copying results to the local repo
```

### recalculate-scores

Rebuilds `scores.json` from all `scorecard.json` files found under a local repository clone.

```bash
jentic-apitools recalculate-scores /path/to/jentic-public-apis
```

Options:

```
LOCAL_REPO_PATH              Path to root of the local repo clone (required)
--base-dir TEXT              Base directory for OpenAPI specs within the repo (default: apis/openapi)
```

### rebuild-scores-json

Rebuilds `scores.json` from all `scorecard.json` files found under the local repository clone.

```bash
jentic-apitools rebuild-scores-json /path/to/jentic-public-apis
```

### rebuild-apis-json

Rebuilds the root `apis.json` catalog from all version-level `apis.json` files.

```bash
jentic-apitools rebuild-apis-json /path/to/jentic-public-apis
```

## Exit Codes

All commands use consistent exit codes: 0 for success and 1 for runtime or pipeline errors. Score and analyze commands (with their `--min-score` / `--fail-on` policy gates that yield exit code 2) live in the separate `score-cli` package.

## Testing

```bash
pytest tests -v
```
