jentic-apitools-cli 1.0.0a18

Jentic Apitools CLI — public-apis repository interactions (import, bulk-rescore, rebuild-*, improve)

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, 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 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 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 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

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

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

pytest tests -v