api-squash-cli

name	api-squash-cli
description	Extract and summarise Python API surfaces using api-squash. Use when the user asks to summarise a Python project's API, understand a codebase's class or function structure, list public interfaces, inspect module signatures, or before code-generation tasks that need structural awareness — even if they don't say 'api-squash' explicitly. Also use when the user says 'what does this project expose?', 'show me the API surface', or asks to generate code that must conform to an existing Python interface. Do NOT use for non-Python projects or for reading full source code.
compatibility	{"platform":"universal"}
metadata	{"author":"b-j-karl","version":"1.0"}

api-squash

Extract Python API surfaces in a compact, token-efficient Markdown format using AST parsing. Produces summaries containing only classes, functions, and their signatures — no implementation details, no function bodies. Typically reduces token count by 60–90% compared to reading full source files.

Use for

• Summarising a Python module or project's public API
• Understanding codebase structure before generating code, writing tests, or planning refactors
• Gathering structural context without wasting tokens on full source files
• Answering questions like "what classes/functions does this project expose?"
• Preparing context for code-generation agents that need interface awareness

Do not use for

• Non-Python projects
• Reading full source code or implementation details
• Projects where you need function bodies, not just signatures

---

Installation

pip install api-squash

If api-squash is not installed, install it before proceeding. In development repos that bundle it, use uv run api-squash instead. To run without installation, use uvx api-squash.

Note: --wrap and --public-only are not in the v0.1.0 PyPI release. If api-squash --help does not show these flags, use uv run api-squash from a cloned repo, or wait for the next release.

---

Commands

api-squash file — single-module summary

api-squash file [OPTIONS] PATH

Option	Description
--no-docstrings	Strip all docstrings from the output
--no-private	Skip private classes/methods (except __init__); keeps items referenced by public signatures
--no-constants	Exclude module-level UPPER_CASE constants from output
--wrap INTEGER	Wrap long signatures at this column width (one param per line)
--public-only	Only include names listed in __all__ (modules without __all__ are unaffected)

Examples:

# Full summary with docstrings and private methods
api-squash file src/auth/models.py

# Minimal summary — signatures only
api-squash file --no-docstrings --no-private src/auth/models.py

# Wrap long signatures at 80 characters for readability
api-squash file --wrap 80 src/auth/models.py

# Only names declared in __all__
api-squash file --public-only src/auth/models.py

api-squash project — whole-project summary

api-squash project [OPTIONS] PATH

Option	Description
--max-depth INTEGER	Limit directory recursion depth
--exclude TEXT	Glob patterns to exclude (repeatable)
--no-docstrings	Strip all docstrings from the output
--no-private	Skip private classes/methods (except __init__); keeps items referenced by public signatures
--no-constants	Exclude module-level UPPER_CASE constants from output
--wrap INTEGER	Wrap long signatures at this column width (one param per line)
--public-only	Only include names listed in __all__ (modules without __all__ are unaffected)

Common directories(__pycache__, .venv, .git, node_modules, build, dist) are excluded automatically.

Examples:

# Summarise entire project
api-squash project src/

# Summarise top-level modules only, excluding tests
api-squash project --max-depth 1 --exclude "tests/*" src/

# Compact summary for token-constrained contexts
api-squash project --no-docstrings --no-private src/

# Only __all__ exports across the project
api-squash project --public-only src/

---

Output format

The output is Markdown-style, optimised for LLM consumption:

• File headers — each module starts with # path/to/file.py
• Classes — rendered as class Name(Base): with docstrings indented below
• Functions / methods — rendered as def name(signature) -> return_type with docstrings indented below
• Module separators — in project mode, modules are separated by ---

Example output

For a file containing an AcmeClient class:

# acme/client.py

class Config:
  Connection settings.

class AcmeClient:
  High-level client for the Acme REST API.
  def __init__(self, config: Config) -> None
  async def get_user(self, user_id: int) -> dict
    Fetch a single user by ID.
  async def list_users(self, *, active: bool = True) -> list[dict]
    Return all users, optionally filtered.
  def _build_url(self, path: str) -> str

With --no-docstrings --no-private:

# acme/client.py

class Config:

class AcmeClient:
  def __init__(self, config: Config) -> None
  async def get_user(self, user_id: int) -> dict
  async def list_users(self, *, active: bool = True) -> list[dict]

---

Practical patterns

Capture output to a file for later use

api-squash project src/ > api-surface.md

Choosing the right flags

Context	Recommended flags
Full API documentation	(none — defaults)
Quick structural overview	--no-docstrings
Minimal token budget	--no-docstrings --no-private
Top-level architecture only	--max-depth 1 --no-docstrings
Large codebase (30+ files)	--max-depth 1 --no-docstrings, then drill into subpackages
Exclude test files	--exclude "tests/*" --exclude "test_*"
Readable long signatures	--wrap 80
Only __all__ exports	--public-only

Combining with other tools

# Summarise API, then use the output as context for code generation
api-squash project src/ > api-surface.md

# Summarise only a specific subpackage
api-squash project src/api_squash/