openapi-cli4ai 0.1.0__tar.gz

openapi_cli4ai-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default: all PRs require review from a maintainer
+* @dbgorilla/maintainers

openapi_cli4ai-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug Report
+about: Report a bug or unexpected behavior
+labels: bug
+---
+
+### What happened?
+
+A clear description of the bug.
+
+### Steps to reproduce
+
+1. Run `./openapi-cli4ai ...`
+2. ...
+
+### Expected behavior
+
+What you expected to happen.
+
+### Actual behavior
+
+What actually happened. Include the full error output if applicable.
+
+### Environment
+
+- OS:
+- Python version (`python3 --version`):
+- uv version (`uv --version`):
+
+### API spec (if relevant)
+
+The OpenAPI spec URL or a minimal example that reproduces the issue.

openapi_cli4ai-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement
+labels: enhancement
+---
+
+### Problem or use case
+
+What are you trying to do? Why is the current behavior insufficient?
+
+### Proposed solution
+
+How should it work?
+
+### Alternatives considered
+
+Any other approaches you've thought about.

openapi_cli4ai-0.1.0/.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "ci"
+    groups:
+      actions:
+        patterns: ["*"]
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "deps"
+    groups:
+      python-deps:
+        patterns: ["*"]

openapi_cli4ai-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: astral-sh/setup-uv@e58605a9b6da7c637471fab8847a5e5a6b8df081 # v5
+        with:
+          enable-cache: true
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Run unit tests
+        run: uv run --python ${{ matrix.python-version }} --with pytest --with pyyaml --with typer --with httpx --with rich --with click --with tomli-w --with python-dotenv pytest tests/ -m "not integration" -v
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: astral-sh/setup-uv@e58605a9b6da7c637471fab8847a5e5a6b8df081 # v5
+      - name: Ruff check
+        run: uvx ruff check .
+      - name: Ruff format check
+        run: uvx ruff format --check .

openapi_cli4ai-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,23 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "0 6 * * 1" # weekly Monday 6am UTC
+
+permissions:
+  security-events: write
+  contents: read
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: github/codeql-action/init@480db559a14342288b67e54bd959dd52dc3ee68f # v3
+        with:
+          languages: python
+      - uses: github/codeql-action/analyze@480db559a14342288b67e54bd959dd52dc3ee68f # v3

openapi_cli4ai-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,49 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions: {}
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: astral-sh/setup-uv@e58605a9b6da7c637471fab8847a5e5a6b8df081 # v5
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Upload artifacts
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 5
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/openapi-cli4ai
+    permissions:
+      id-token: write
+      attestations: write
+      contents: read
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: dist
+          path: dist/
+      - name: Generate attestations
+        uses: actions/attest-build-provenance@96b4a1ef7235a096b17240c259729fdd70c83d45 # v2
+        with:
+          subject-path: dist/*
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

openapi_cli4ai-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment / secrets
+.env
+.env.*
+*.pem
+credentials.json
+
+# Profiles
+profiles.yaml
+!*.example
+
+# Cache
+.cache/
+
+# Test
+.pytest_cache/
+.coverage
+htmlcov/

openapi_cli4ai-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.1.0] - 2026-03-25
+
+### Added
+
+- Installable PyPI package (`uv pip install openapi-cli4ai` / `uvx openapi-cli4ai`)
+- Profile management with TOML config at `~/.openapi-cli4ai.toml`
+- Endpoint discovery with search and tag filtering (`endpoints`)
+- API calling with query params, headers, JSON body, and file body (`call`)
+- Auth support: bearer token, OAuth token endpoint, API key, basic auth
+- Token caching with automatic refresh
+- Auto-fetch spec after login for auth-gated APIs
+- SSE streaming support
+- OpenAPI spec caching with TTL
+- JSON and compact output formats
+- `python -m openapi_cli4ai` support
+- Dependabot for automated dependency and GitHub Actions updates
+- CodeQL code scanning workflow
+- Trusted Publisher release workflow with Sigstore attestation
+- All GitHub Actions pinned to commit SHAs

openapi_cli4ai-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to openapi-cli4ai
+
+Thanks for your interest in contributing!
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork
+3. Install [uv](https://docs.astral.sh/uv/) if you don't have it
+4. Install in editable mode: `uv pip install -e .`
+5. Run `openapi-cli4ai --help` to verify everything works
+
+## Project Structure
+
+```
+src/openapi_cli4ai/
+  __init__.py       # Package exports
+  __main__.py       # python -m support
+  cli.py            # All CLI code lives here
+openapi-cli4ai      # Standalone shim (imports from package)
+tests/              # pytest tests
+```
+
+The core code lives in `src/openapi_cli4ai/cli.py`. The standalone `openapi-cli4ai` script is a thin shim that imports from the package.
+
+## Testing
+
+```bash
+pytest tests/ -m "not integration" -v
+```
+
+## Submitting a Pull Request
+
+1. Create a feature branch (`git checkout -b my-feature`)
+2. Make your changes
+3. Run the tests
+4. Commit with a clear message
+5. Push and open a PR
+
+## Reporting Issues
+
+Open an issue on GitHub. Include:
+- What you tried
+- What happened
+- What you expected
+- The API spec you were using (if relevant)
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

openapi_cli4ai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DBGorilla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openapi_cli4ai-0.1.0/PKG-INFO

@@ -0,0 +1,315 @@
+Metadata-Version: 2.4
+Name: openapi-cli4ai
+Version: 0.1.0
+Summary: Turn any REST API with an OpenAPI spec into an AI-ready CLI
+Project-URL: Homepage, https://github.com/dbgorilla/openapi-cli4ai
+Project-URL: Repository, https://github.com/dbgorilla/openapi-cli4ai
+Project-URL: Issues, https://github.com/dbgorilla/openapi-cli4ai/issues
+Author: DBGorilla
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,api,cli,llm,mcp,openapi,rest
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: python-dotenv<2,>=1.0
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: rich<15,>=13
+Requires-Dist: tomli-w<2,>=1.0
+Requires-Dist: typer<1,>=0.12
+Description-Content-Type: text/markdown
+
+```bash
+                                     _            _ _ _  _         _
+   ___  _ __   ___ _ __   __ _ _ __ (_)       ___| (_) || |   __ _(_)
+  / _ \| '_ \ / _ \ '_ \ / _` | '_ \| |_____ / __| | | || |_ / _` | |
+ | (_) | |_) |  __/ | | | (_| | |_) | |_____| (__| | |__   _| (_| | |
+  \___/| .__/ \___|_| |_|\__,_| .__/|_|      \___|_|_|  |_|  \__,_|_|
+       |_|                    |_|
+```
+
+Turn any REST API with an OpenAPI spec into an AI-ready CLI. No MCP server. No custom integration. Just point it at a URL.
+
+![openapi-cli4ai quickstart demo](demo.gif)
+
+## Install
+
+```bash
+# Requires uv (https://docs.astral.sh/uv/)
+uv pip install openapi-cli4ai
+
+# Or run directly without installing
+uvx openapi-cli4ai --help
+```
+
+## Quick Start
+
+```bash
+# Point it at any API with an OpenAPI spec
+openapi-cli4ai init petstore --url https://petstore3.swagger.io/api/v3
+
+# Discover endpoints
+openapi-cli4ai endpoints
+
+# Search endpoints
+openapi-cli4ai endpoints -s pet
+
+# Call an endpoint
+openapi-cli4ai call GET /pet/findByStatus --query status=available
+```
+
+## How It Works
+
+```
+Your AI Agent (Claude, GPT, Cursor, etc.)
+        |
+        |  1. "endpoints -s users"     <-- discover what's available
+        |  2. reads the endpoint list
+        |  3. "call GET /users/123"    <-- makes the API call
+        |
+        v
++---------------------+         +----------------------+
+|   openapi-cli4ai    |-------->|   Your API Server    |
+|                     |         |   (any REST API)     |
+|  * Fetches spec     |<--------|                      |
+|  * Caches it        |         +----------------------+
+|  * Routes calls     |
+|  * Handles auth     |
++---------------------+
+```
+
+The agent uses `endpoints` to discover what's available, then `call` to hit the right endpoint with the right parameters. That's the entire integration. The agent already knows how to use a CLI — you just give it this one and point it at your API.
+
+## Why Not MCP?
+
+Every MCP tool you connect injects its schema into the prompt. Every parameter, every description, every type definition. Connect a few MCP servers and your agent is burning tokens on tool descriptions before it even starts thinking about your task.
+
+For large API surfaces, there's a better pattern: **pull-based discovery**.
+
+Nothing is injected into the prompt upfront. The agent pulls what it needs, when it needs it. It sees a compact endpoint index, picks the right endpoint, and calls it. This works with APIs of any size — including 10MB+ specs — without stuffing everything into context.
+
+This isn't MCP vs. OpenAPI. It's about having both tools and reaching for the right one. For quick integrations, MCP is great. For large or unfamiliar API surfaces, an OpenAPI spec and a thin CLI is the better play.
+
+## Commands
+
+### `init` — Point it at an API
+
+```bash
+# Auto-detect OpenAPI spec location
+openapi-cli4ai init myapi --url https://api.example.com
+
+# Specify spec path
+openapi-cli4ai init myapi --url https://api.example.com --spec /v2/openapi.json
+
+# Specify auth type
+openapi-cli4ai init myapi --url https://api.example.com --auth bearer
+
+# Use a remote spec URL
+openapi-cli4ai init myapi --url https://api.example.com --spec-url https://example.com/spec.json
+
+# Skip SSL verification (internal/staging APIs)
+openapi-cli4ai -k init myapi --url https://staging.internal.example.com
+```
+
+### `endpoints` — Discover API endpoints
+
+```bash
+# List all endpoints
+openapi-cli4ai endpoints
+
+# Search by keyword
+openapi-cli4ai endpoints -s pet
+
+# Filter by tag
+openapi-cli4ai endpoints --tag store
+
+# Output as JSON (useful for AI agents)
+openapi-cli4ai endpoints --format json
+
+# Compact one-line-per-endpoint view
+openapi-cli4ai endpoints --format compact
+```
+
+### `call` — Call any endpoint
+
+```bash
+# GET request
+openapi-cli4ai call GET /pet/findByStatus --query status=available
+
+# POST with JSON body
+openapi-cli4ai call POST /pet --body '{"name": "Rex", "status": "available"}'
+
+# POST with body from file
+openapi-cli4ai call POST /pet --body @payload.json
+
+# Multiple query parameters
+openapi-cli4ai call GET /pet/findByStatus --query status=available --query limit=10
+
+# Custom headers
+openapi-cli4ai call GET /resource --header "X-Custom:value"
+
+# Stream SSE responses
+openapi-cli4ai call POST /chat --body '{"message": "hello"}' --stream
+
+# Raw output (no formatting)
+openapi-cli4ai call GET /pet/1 --raw
+```
+
+### `profile` — Manage API profiles
+
+```bash
+# List profiles
+openapi-cli4ai profile list
+
+# Switch active profile
+openapi-cli4ai profile use myapi
+
+# Show profile config
+openapi-cli4ai profile show
+
+# Add a profile manually
+openapi-cli4ai profile add myapi --url https://api.example.com
+
+# Remove a profile
+openapi-cli4ai profile remove myapi
+```
+
+### `login` / `logout` — Authentication
+
+```bash
+# Login (for APIs with OAuth/token endpoints)
+openapi-cli4ai login --username admin
+
+# Login with password from file (for automation)
+openapi-cli4ai login --username admin --password-file /path/to/secret
+
+# Login with password from stdin
+echo "my-password" | openapi-cli4ai login --username admin --password-stdin
+
+# Logout (clear cached tokens)
+openapi-cli4ai logout
+```
+
+## Configuration
+
+Profiles are stored in `~/.openapi-cli4ai.toml`. Secrets are referenced via environment variables — never stored in the config file.
+
+```toml
+active_profile = "myapi"
+
+[profiles.myapi]
+base_url = "https://api.example.com"
+openapi_path = "/openapi.json"
+
+[profiles.myapi.auth]
+type = "bearer"
+token_env_var = "MYAPI_TOKEN"
+
+[profiles.stripe]
+base_url = "https://api.stripe.com"
+openapi_url = "https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json"
+
+[profiles.stripe.auth]
+type = "api-key"
+env_var = "STRIPE_SECRET_KEY"
+header = "Authorization"
+prefix = "Bearer "
+
+[profiles.internal-app]
+base_url = "http://localhost:8000"
+verify_ssl = false
+
+[profiles.internal-app.auth]
+type = "bearer"
+token_endpoint = "/api/auth/token"
+refresh_endpoint = "/api/auth/refresh"
+
+[profiles.internal-app.auth.payload]
+username = "{username}"
+password = "{password}"
+tenant = "{env:MY_TENANT}"
+account_type = "USERNAME"
+```
+
+Payload placeholders: `{username}` and `{password}` come from the login prompt. `{env:VAR_NAME}` pulls from environment variables or a `.env` file (loaded automatically).
+
+### Auth Types
+
+| Type | Use Case | Config Fields |
+|------|----------|---------------|
+| `none` | Public APIs | — |
+| `bearer` | Token from env var | `token_env_var` |
+| `bearer` | OAuth token endpoint | `token_endpoint`, `refresh_endpoint`, `payload` |
+| `api-key` | API key in header | `env_var`, `header`, `prefix` |
+| `basic` | HTTP Basic auth | `username_env_var`, `password_env_var` |
+
+## Tested With
+
+| API | Endpoints | Auth | Example |
+|-----|-----------|------|---------|
+| [Petstore](https://petstore3.swagger.io) | 19 | None | `init petstore --url https://petstore3.swagger.io/api/v3` |
+| [NWS Weather](https://api.weather.gov) | 60 | None | `init nws --url https://api.weather.gov` |
+| [PokéAPI](https://pokeapi.co) | 97 | None | `init pokeapi --url https://pokeapi.co --spec-url ...` |
+| [D&D 5e](https://www.dnd5eapi.co) | 47 | None | `init dnd --url https://www.dnd5eapi.co --spec-url ...` |
+| [Nager.Date Holidays](https://date.nager.at) | 8 | None | `init holidays --url https://date.nager.at --spec /openapi/v3.json` |
+| [GitHub](https://api.github.com) | 1,080 | Bearer | `init github --url https://api.github.com --spec-url ... --auth bearer` |
+| [Jira Cloud](https://developer.atlassian.com/cloud/jira/platform/rest/v3/) | 581 | Basic | `init jira --url https://your-domain.atlassian.net --spec-url ... --auth basic` |
+| [OpenRouter](https://openrouter.ai) | 36 | Bearer | `init openrouter --url https://openrouter.ai/api/v1 --spec-url ... --auth bearer` |
+| [DBGorilla](https://dbgorilla.com) | 500+ | Token endpoint | See `examples/profiles.toml.example` |
+
+Works with any AI agent that has shell access — Claude Code, Cursor, GitHub Copilot, or anything that can run `endpoints` and `call`.
+
+### Claude Code Setup
+
+Add this to your global `~/.claude/CLAUDE.md` so every Claude Code session knows about the tool — regardless of which repo you're working in:
+
+```markdown
+## API Access
+
+You have `openapi-cli4ai` installed for interacting with REST APIs.
+
+- Discover endpoints: `openapi-cli4ai endpoints -s <keyword>`
+- Call endpoints: `openapi-cli4ai call <METHOD> <path> [--query key=value] [--body '{}']`
+- List profiles: `openapi-cli4ai profile list`
+- Switch profile: `openapi-cli4ai profile use <name>`
+- Login (if needed): `openapi-cli4ai login`
+
+Use `openapi-cli4ai endpoints` to explore before making calls.
+Use `--format json` when you need to parse the output programmatically.
+Use `-k` flag for APIs with self-signed or internal certificates.
+```
+
+This works because `~/.claude/CLAUDE.md` is loaded into every conversation context, not just the current repo.
+
+## Development
+
+```bash
+git clone https://github.com/dbgorilla/openapi-cli4ai.git
+cd openapi-cli4ai
+uv pip install -e .
+pytest tests/ -m "not integration" -v
+```
+
+## Security
+
+- All credentials stay local — profiles reference env var names, not values
+- Token cache protected with restricted file permissions (0600)
+- PyPI releases use [Trusted Publishers](https://docs.pypi.org/trusted-publishers/) with Sigstore attestation
+- All CI actions pinned to commit SHAs
+- Dependabot monitors dependencies weekly
+- See [SECURITY.md](SECURITY.md) for vulnerability reporting
+
+## Attribution
+
+This project was inspired by [@tomleavy](https://github.com/tomleavy), who originated the idea that an OpenAPI spec and a thin CLI is all an AI agent needs to talk to any API.
+
+## License
+
+MIT — see [LICENSE](LICENSE).