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, verifying that an overlay reproduces an improved spec, and bulk repository operations on a local clone. Scoring and analysis commands moved to the separate, internal-only score-cli 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 seven 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 library directly via prepare_improve_context and submit_improve, with no API hop. The verify-improvement command applies one or more Overlay 1.1.x documents to an original spec and checks that the result reproduces a given improved spec, without touching GitHub. 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:

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 or uv tool, which run the CLI in an isolated environment without affecting your system Python:

# Using pipx
pipx install jentic-apitools-cli

# Using uv
uv tool install jentic-apitools-cli

Alternatively, install with pip:

pip install jentic-apitools-cli

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

jentic-apitools --help

Quick Start

# 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

# Verify that an overlay turns the original spec into the improved spec
jentic-apitools verify-improvement \
  --original original.json --improved improved.json --overlay overlay.json

# 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.

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.

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.

verify-improvement

The verify-improvement command applies one or more Overlay 1.1.x documents to an original OpenAPI spec and confirms that the result reproduces a given improved spec. This complements the Overlay JSON Schema validation an improvement workflow already performs: a schema-valid overlay can still target the wrong node or encode a lossy transform, and this command proves the overlay actually transforms the original into the improved spec. It runs entirely locally and never touches GitHub.

jentic-apitools verify-improvement --original SPEC --improved SPEC \
    --overlay OVERLAY [--overlay OVERLAY ...]

Each of --original, --improved, and --overlay accepts a local file path, an HTTP(S) URL, or - for stdin; only one slot per invocation may consume stdin. --overlay is repeatable and the overlays are applied in order. Every overlay is validated against the Overlay 1.1.x schema before being applied, so the verdict is independent of the configured overlay engine. The match is structural and order-insensitive, matching the invariant the improve flow enforces.

Options:

--original SPEC              Original (input) bundled spec (path / URL / -). Required.
--improved SPEC              Improved (expected output) bundled spec (path / URL / -). Required.
--overlay OVERLAY            Overlay 1.1.x document (path / URL / -). Repeatable, applied in order. Required.
-q, --quiet                  Suppress log output; only emit the result JSON.

The overlay engine is selected by the OVERLAY_BACKEND environment variable. The default speclynx backend requires npx (Node.js) and handles all Overlay 1.1.x targets, including numeric list indices such as $.servers[0]. Setting OVERLAY_BACKEND=oas_patch runs an in-process engine that needs no npx but crashes on numeric list-index targets, so prefer the default for specs whose overlays address list elements by index.

The output is a single JSON document on stdout with success, match, overlay_count, and diff fields; diff is a structural DeepDiff of the improved spec versus the spec produced by applying the overlays, and is empty when they match. The process exits 0 when the overlays reproduce the improved spec, 1 for an operational error (unreadable input, an overlay that fails schema validation, or an apply failure such as a missing npx), and 2 for a clean verification mismatch.

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).

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.

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.

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.

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. The verify-improvement command additionally uses exit code 2 to signal a verification mismatch (the overlays applied cleanly but the result differed from the improved spec), distinct from the operational errors that yield 1. Score and analyze commands (with their --min-score / --fail-on policy gates that also yield exit code 2) live in the separate score-cli package.

Testing

pytest tests -v