Cli

cli

AXM-AST CLI entry point — AST introspection for AI agents.

Usage::

Text Only

axm-ast describe src/mylib
axm-ast describe src/mylib --detail detailed --json
axm-ast inspect src/mylib --symbol MyClass
axm-ast inspect src/mylib --symbol MyClass --source --json
axm-ast graph src/mylib --format mermaid
axm-ast search src/mylib --returns str
axm-ast version

callees(path='.', *, symbol, json_output=False)

Find all functions/methods called by a given symbol.

Source code in packages/axm-ast/src/axm_ast/cli.py

@app.command()
def callees(
    path: Annotated[
        str,
        cyclopts.Parameter(help="Path to package directory"),
    ] = ".",
    *,
    symbol: Annotated[
        str,
        cyclopts.Parameter(
            name=["--symbol", "-s"],
            help="Symbol name to find callees of",
        ),
    ],
    json_output: Annotated[
        bool,
        cyclopts.Parameter(name=["--json"], help="Output as JSON"),
    ] = False,
) -> None:
    """Find all functions/methods called by a given symbol."""
    project_path = _resolve_dir(path)

    pkg = get_package(project_path)

    from axm_ast.core.flows import find_callees

    results = find_callees(pkg, symbol)

    if json_output:
        print(
            json.dumps(
                [r.model_dump(mode="json") for r in results],
                indent=2,
            )
        )
    elif not results:
        print(f"📭 No callees found for '{symbol}'")
    else:
        print(f"📞 {len(results)} callee(s) of '{symbol}':\n")
        for r in results:
            ctx = f" in {r.context}()" if r.context else ""
            print(f"  {r.module}:{r.line} → {r.symbol}{ctx}")
            print(f"    {r.call_expression}")

callers(path='.', *, symbol, json_output=False)

Find all call-sites of a given symbol across a package.

Source code in packages/axm-ast/src/axm_ast/cli.py

@app.command()
def callers(
    path: Annotated[
        str,
        cyclopts.Parameter(help="Path to package or workspace directory"),
    ] = ".",
    *,
    symbol: Annotated[
        str,
        cyclopts.Parameter(
            name=["--symbol", "-s"],
            help="Symbol name to search for callers of",
        ),
    ],
    json_output: Annotated[
        bool,
        cyclopts.Parameter(name=["--json"], help="Output as JSON"),
    ] = False,
) -> None:
    """Find all call-sites of a given symbol across a package."""
    target = _resolve_workspace_or_package(path)
    project_path = target.path

    if target.workspace is not None:
        from axm_ast.core.callers import find_callers_workspace
        from axm_ast.core.workspace import analyze_workspace

        ws = analyze_workspace(project_path, detected=target.workspace)
        results = find_callers_workspace(ws, symbol)
    else:
        pkg = get_package(project_path)

        from axm_ast.core.callers import find_callers

        results = find_callers(pkg, symbol)

    if json_output:
        print(
            json.dumps(
                [r.model_dump(mode="json") for r in results],
                indent=2,
            )
        )
    elif not results:
        print(f"📭 No callers found for '{symbol}'")
    else:
        print(f"📞 {len(results)} caller(s) of '{symbol}':\n")
        for r in results:
            ctx = f" in {r.context}()" if r.context else ""
            print(f"  {r.module}:{r.line}{ctx}")
            print(f"    {r.call_expression}")

context(path='.', *, json_output=False, depth=None)

Dump complete project context in one shot for AI agents.

Source code in packages/axm-ast/src/axm_ast/cli.py

@app.command()
def context(
    path: Annotated[
        str,
        cyclopts.Parameter(help="Path to package or workspace directory"),
    ] = ".",
    *,
    json_output: Annotated[
        bool,
        cyclopts.Parameter(name=["--json"], help="Output as JSON"),
    ] = False,
    depth: Annotated[
        int | None,
        cyclopts.Parameter(
            name=["--depth", "-d"],
            help="Detail level: 0=top-5, 1=sub-packages, 2=modules, 3=symbols",
        ),
    ] = None,
) -> None:
    """Dump complete project context in one shot for AI agents."""
    target = _resolve_workspace_or_package(path)
    project_path = target.path

    if target.workspace is not None:
        _print_workspace_context(project_path, json_output=json_output, depth=depth)
        return

    from axm_ast.core.context import (
        build_context as _build_context,
    )
    from axm_ast.core.context import (
        format_context,
        format_context_json,
    )

    ctx = _build_context(project_path)

    if json_output:
        print(json.dumps(format_context_json(ctx, depth=depth), indent=2))
    elif depth is not None:
        _print_compact_context(format_context_json(ctx, depth=depth))
    else:
        print(format_context(ctx))

dead_code(path='.', *, json_output=False, include_tests=False)

Detect dead (unreferenced) code in a Python package.

Source code in packages/axm-ast/src/axm_ast/cli.py

@app.command(name="dead-code")
def dead_code(
    path: Annotated[
        str,
        cyclopts.Parameter(help="Path to package directory"),
    ] = ".",
    *,
    json_output: Annotated[
        bool,
        cyclopts.Parameter(name=["--json"], help="Output as JSON"),
    ] = False,
    include_tests: Annotated[
        bool,
        cyclopts.Parameter(
            name=["--include-tests"],
            help="Include test fixtures in scan",
        ),
    ] = False,
) -> None:
    """Detect dead (unreferenced) code in a Python package."""
    project_path = _resolve_dir(path)

    from axm_ast.core.dead_code import find_dead_code, format_dead_code

    pkg = get_package(project_path)
    results = find_dead_code(pkg, include_tests=include_tests)

    if json_output:
        print(
            json.dumps(
                {
                    "dead_symbols": [
                        {
                            "name": d.name,
                            "module_path": d.module_path,
                            "line": d.line,
                            "kind": d.kind,
                        }
                        for d in results
                    ],
                    "total": len(results),
                },
                indent=2,
            )
        )
    else:
        print(format_dead_code(results))

describe(path='.', *, detail='detailed', json_output=False, budget=None, rank=False, compress=False, modules=None)

Describe a Python package at the chosen detail level.

Source code in packages/axm-ast/src/axm_ast/cli.py

@app.command()
def describe(
    path: Annotated[
        str,
        cyclopts.Parameter(help="Path to package/module directory"),
    ] = ".",
    *,
    detail: Annotated[
        str,
        cyclopts.Parameter(
            name=["--detail", "-d"],
            help="Detail level: toc < names < summary < detailed",
        ),
    ] = "detailed",
    json_output: Annotated[
        bool,
        cyclopts.Parameter(name=["--json"], help="Output as JSON"),
    ] = False,
    budget: Annotated[
        int | None,
        cyclopts.Parameter(
            name=["--budget", "-b"],
            help="Max output lines (truncate intelligently)",
        ),
    ] = None,
    rank: Annotated[
        bool,
        cyclopts.Parameter(
            name=["--rank"],
            help="Sort symbols by importance (PageRank)",
        ),
    ] = False,
    compress: Annotated[
        bool,
        cyclopts.Parameter(
            name=["--compress"],
            help="Compressed output: signatures + docstring summaries",
        ),
    ] = False,
    modules: Annotated[
        str | None,
        cyclopts.Parameter(
            name=["--modules", "-m"],
            help="Comma-separated module name filters (substring, case-insensitive)",
        ),
    ] = None,
) -> None:
    """Describe a Python package at the chosen detail level."""
    if detail == "full":
        print(
            "❌ detail='full' has been removed. "
            "Use --detail detailed or ast_inspect --source.",
            file=sys.stderr,
        )
        raise SystemExit(1)

    if compress and detail not in ("summary", "detailed"):
        print(
            f"❌ --compress and --detail {detail} are mutually exclusive. "
            "Use --compress alone or --detail without --compress.",
            file=sys.stderr,
        )
        raise SystemExit(1)

    project_path = _resolve_dir(path)

    from axm_ast.formatters import filter_modules, format_toc

    pkg = get_package(project_path)

    # Apply module filter
    mod_filter = [m.strip() for m in modules.split(",")] if modules else None
    pkg = filter_modules(pkg, mod_filter)

    if detail == "toc":
        _print_toc(format_toc(pkg), json_output=json_output)
        return

    if detail == "names" and not json_output:
        from axm_ast.tools.describe_text import render_describe_text

        data = cast("dict[str, object]", format_json(pkg, detail=detail))
        print(render_describe_text(data, detail))
        return

    if compress:
        from axm_ast.formatters import format_compressed

        print(format_compressed(pkg))
    elif json_output:
        print(json.dumps(format_json(pkg, detail=detail), indent=2))
    else:
        print(format_text(pkg, detail=detail, budget=budget, rank=rank))

diff_cmd(refs, path='.', *, json_output=False)

Structural diff between two branches at symbol level.

Source code in packages/axm-ast/src/axm_ast/cli.py

@app.command(name="diff")
def diff_cmd(
    refs: Annotated[
        str,
        cyclopts.Parameter(help="Git refs in base..head format"),
    ],
    path: Annotated[
        str,
        cyclopts.Parameter(help="Path to package directory"),
    ] = ".",
    *,
    json_output: Annotated[
        bool,
        cyclopts.Parameter(name=["--json"], help="Output as JSON"),
    ] = False,
) -> None:
    """Structural diff between two branches at symbol level."""
    if ".." not in refs:
        print("❌ Expected format: base..head (e.g. main..feature)", file=sys.stderr)
        raise SystemExit(1)

    parts = refs.split("..", 1)
    base, head = parts[0], parts[1]
    if not base or not head:
        print("❌ Both base and head refs are required", file=sys.stderr)
        raise SystemExit(1)

    project_path = _resolve_dir(path)

    from axm_ast.core.structural_diff import structural_diff

    result = structural_diff(project_path, base, head)

    if "error" in result:
        print(f"❌ {result['error']}", file=sys.stderr)
        raise SystemExit(1)

    if json_output:
        print(json.dumps(result, indent=2))
    else:
        _print_diff(result, base, head)

docs(path='.', *, detail='full', pages_filter=None, json_output=False, tree_only=False)

Dump project documentation tree and content in one shot.

Source code in packages/axm-ast/src/axm_ast/cli.py

@app.command()
def docs(
    path: Annotated[
        str,
        cyclopts.Parameter(help="Project root directory"),
    ] = ".",
    *,
    detail: Annotated[
        str,
        cyclopts.Parameter(
            name=["--detail", "-d"],
            help="Detail level: toc, summary, full",
        ),
    ] = "full",
    pages_filter: Annotated[
        str | None,
        cyclopts.Parameter(
            name=["--pages", "-p"],
            help="Comma-separated page name substrings to filter",
        ),
    ] = None,
    json_output: Annotated[
        bool,
        cyclopts.Parameter(name=["--json"], help="Output as JSON"),
    ] = False,
    tree_only: Annotated[
        bool,
        cyclopts.Parameter(name=["--tree"], help="Only show directory tree"),
    ] = False,
) -> None:
    """Dump project documentation tree and content in one shot."""
    project_path = _resolve_dir(path)

    from axm_ast.core.docs import discover_docs, format_docs, format_docs_json

    pages = [p.strip() for p in pages_filter.split(",")] if pages_filter else None
    result = discover_docs(project_path, detail=detail, pages=pages)

    if json_output:
        print(json.dumps(format_docs_json(result), indent=2))
    else:
        print(format_docs(result, tree_only=tree_only))

flows(path='.', *, trace=None, max_depth=5, cross_module=False, detail='trace', no_exclude_stdlib=False, json_output=False)

Detect entry points and trace execution flows.

Source code in packages/axm-ast/src/axm_ast/cli.py

@app.command()
def flows(
    path: Annotated[
        str,
        cyclopts.Parameter(help="Path to package directory"),
    ] = ".",
    *,
    trace: Annotated[
        str | None,
        cyclopts.Parameter(
            name=["--trace", "-t"],
            help="Entry point name to trace flow from",
        ),
    ] = None,
    max_depth: Annotated[
        int,
        cyclopts.Parameter(
            name=["--max-depth"],
            help="Maximum BFS depth for flow tracing",
        ),
    ] = 5,
    cross_module: Annotated[
        bool,
        cyclopts.Parameter(
            name=["--cross-module"],
            help="Resolve imports and trace into external modules",
        ),
    ] = False,
    detail: Annotated[
        str,
        cyclopts.Parameter(
            name=["--detail", "-d"],
            help="Detail level: trace (default) or source (include function source)",
        ),
    ] = "trace",
    no_exclude_stdlib: Annotated[
        bool,
        cyclopts.Parameter(
            name=["--no-exclude-stdlib"],
            help="Include stdlib/builtin callees in flow trace",
        ),
    ] = False,
    json_output: Annotated[
        bool,
        cyclopts.Parameter(name=["--json"], help="Output as JSON"),
    ] = False,
) -> None:
    """Detect entry points and trace execution flows."""
    project_path = _resolve_dir(path)

    from axm_ast.core.flows import (
        VALID_DETAILS,
        find_entry_points,
        format_flow_compact,
        format_flows,
        trace_flow,
    )

    if detail not in VALID_DETAILS:
        print(
            f"Invalid detail={detail!r}; must be one of {sorted(VALID_DETAILS)}",
            file=sys.stderr,
        )
        raise SystemExit(1)

    pkg = get_package(project_path)

    if trace is not None:
        try:
            steps, _truncated = trace_flow(
                pkg,
                trace,
                max_depth=max_depth,
                cross_module=cross_module,
                detail=detail,
                exclude_stdlib=not no_exclude_stdlib,
            )
        except ValueError as exc:
            print(str(exc), file=sys.stderr)
            raise SystemExit(1) from None
        if json_output:
            print(
                json.dumps(
                    {
                        "entry": trace,
                        "steps": [s.model_dump(mode="json") for s in steps],
                        "count": len(steps),
                    },
                    indent=2,
                )
            )
        elif not steps:
            print(f"📭 No flow found for '{trace}'")
        else:
            print(f"🔀 Flow from '{trace}' ({len(steps)} step(s)):\n")
            print(format_flow_compact(steps))
        return

    entries = find_entry_points(pkg)
    if json_output:
        print(
            json.dumps(
                {
                    "entry_points": [e.model_dump(mode="json") for e in entries],
                    "count": len(entries),
                },
                indent=2,
            )
        )
    else:
        print(format_flows(entries))

graph(path='.', *, fmt='text', json_output=False, scope=None)

Display the internal import/dependency graph.

Source code in packages/axm-ast/src/axm_ast/cli.py

@app.command()
def graph(
    path: Annotated[
        str,
        cyclopts.Parameter(help="Path to package or workspace directory"),
    ] = ".",
    *,
    fmt: Annotated[
        str,
        cyclopts.Parameter(
            name=["--format", "-f"],
            help="Output format: text, mermaid, json",
        ),
    ] = "text",
    json_output: Annotated[
        bool,
        cyclopts.Parameter(name=["--json"], help="Output as JSON"),
    ] = False,
    scope: Annotated[
        str | None,
        cyclopts.Parameter(
            name=["--scope"],
            help=(
                "Graph scope: 'package', 'workspace' (merged module-level),"
                " or 'workspace-deps'. Omit for auto-detection."
            ),
        ),
    ] = None,
) -> None:
    """Display the internal import/dependency graph."""
    project_path = _resolve_dir(path)

    if scope == "workspace":
        _print_workspace_module_graph(project_path, fmt=fmt, json_output=json_output)
        return
    if scope == "workspace-deps":
        _print_workspace_graph(project_path, fmt=fmt, json_output=json_output)
        return
    if scope == "package":
        _print_package_graph(project_path, fmt=fmt, json_output=json_output)
        return

    target = _resolve_workspace_or_package(path)
    if target.workspace is not None:
        _print_workspace_graph(
            target.path,
            fmt=fmt,
            json_output=json_output,
            detected=target.workspace,
        )
        return

    _print_package_graph(project_path, fmt=fmt, json_output=json_output)

impact(path='.', *, symbol, json_output=False, exclude_tests=False, test_filter=None, precise_callers=False, compact=False)

Analyze the impact of changing a symbol.

Source code in packages/axm-ast/src/axm_ast/cli.py

@app.command()
def impact(
    path: Annotated[
        str,
        cyclopts.Parameter(help="Path to package or workspace directory"),
    ] = ".",
    *,
    symbol: Annotated[
        str,
        cyclopts.Parameter(
            name=["--symbol", "-s"],
            help="Symbol name to analyze impact for",
        ),
    ],
    json_output: Annotated[
        bool,
        cyclopts.Parameter(name=["--json"], help="Output as JSON"),
    ] = False,
    exclude_tests: Annotated[
        bool,
        cyclopts.Parameter(
            name=["--exclude-tests"],
            help="Filter test callers from impact output",
        ),
    ] = False,
    test_filter: Annotated[
        str | None,
        cyclopts.Parameter(
            name=["--test-filter"],
            help="Test caller filter mode: none, all, or related",
        ),
    ] = None,
    precise_callers: Annotated[
        bool,
        cyclopts.Parameter(
            name=["--precise-callers"],
            help=(
                "Exclude callers proven to import a homonymous symbol; "
                "ambiguous imports remain included (fail-open)"
            ),
        ),
    ] = False,
    compact: Annotated[
        bool,
        cyclopts.Parameter(
            name=["--compact"],
            help="Output a compact markdown table summary",
        ),
    ] = False,
) -> None:
    """Analyze the impact of changing a symbol."""
    from axm_ast.tools.impact import ImpactTool

    detail = "compact" if compact else None
    tool = ImpactTool()
    tool_result = tool.execute(
        path=path,
        symbol=symbol,
        exclude_tests=exclude_tests,
        test_filter=test_filter,
        precise_callers=precise_callers,
        detail=detail,
    )

    if not tool_result.success:
        print(tool_result.error, file=sys.stderr)
        raise SystemExit(1)

    if compact:
        print(tool_result.text)
    elif json_output:
        print(json.dumps(tool_result.data, indent=2))
    else:
        _print_impact(
            cast(ImpactResult, tool_result.data), caller_paths=precise_callers
        )

inspect(path='.', *, symbol=None, symbols=None, source=False, json_output=False)

Inspect a symbol by name across a package.

Operates on packages (not individual files). Supports dotted paths like ClassName.method or module.symbol. Returns file path, line numbers, and optionally source code — matching MCP ast_inspect.

Source code in packages/axm-ast/src/axm_ast/cli.py

@app.command()
def inspect(
    path: Annotated[
        str,
        cyclopts.Parameter(help="Path to package directory"),
    ] = ".",
    *,
    symbol: Annotated[
        str | None,
        cyclopts.Parameter(
            name=["--symbol", "-s"],
            help="Symbol name to inspect (supports dotted paths like Class.method)",
        ),
    ] = None,
    symbols: Annotated[
        list[str] | None,
        cyclopts.Parameter(
            name=["--symbols"],
            consume_multiple=True,
            help="Symbol names to inspect in batch",
        ),
    ] = None,
    source: Annotated[
        bool,
        cyclopts.Parameter(
            name=["--source"],
            help="Include source code in output",
        ),
    ] = False,
    json_output: Annotated[
        bool,
        cyclopts.Parameter(name=["--json"], help="Output as JSON"),
    ] = False,
) -> None:
    """Inspect a symbol by name across a package.

    Operates on packages (not individual files). Supports dotted paths
    like ``ClassName.method`` or ``module.symbol``. Returns file path,
    line numbers, and optionally source code — matching MCP ``ast_inspect``.
    """
    if symbol and symbols:
        print("❌ --symbol and --symbols are mutually exclusive", file=sys.stderr)
        raise SystemExit(1)

    project_path = _resolve_dir(path)

    if symbols:
        _inspect_batch(project_path, symbols, source=source, json_output=json_output)
        return

    if not symbol:
        _inspect_list_all(project_path, json_output=json_output)
        return

    from axm_ast.tools.inspect import InspectTool

    tool = InspectTool()
    result = tool.execute(path=str(project_path), symbol=symbol, source=source)

    if not result.success:
        print(f"❌ {result.error}", file=sys.stderr)
        raise SystemExit(1)

    if json_output:
        print(json.dumps(result.data["symbol"], indent=2))
    else:
        print(result.text)

main()

Main entry point.

Source code in packages/axm-ast/src/axm_ast/cli.py

def main() -> None:
    """Main entry point."""
    app()

search(path='.', *, name=None, returns=None, kind=None, inherits=None, json_output=False)

Search for symbols across a package with filters.

Source code in packages/axm-ast/src/axm_ast/cli.py

@app.command()
def search(
    path: Annotated[
        str,
        cyclopts.Parameter(help="Path to package directory"),
    ] = ".",
    *,
    name: Annotated[
        str | None,
        cyclopts.Parameter(name=["--name", "-n"], help="Search by symbol name"),
    ] = None,
    returns: Annotated[
        str | None,
        cyclopts.Parameter(name=["--returns", "-r"], help="Filter by return type"),
    ] = None,
    kind: Annotated[
        str | None,
        cyclopts.Parameter(
            name=["--kind", "-k"],
            help=(
                "Filter by kind: function, method, property,"
                " classmethod, staticmethod, abstract, class"
            ),
        ),
    ] = None,
    inherits: Annotated[
        str | None,
        cyclopts.Parameter(name=["--inherits"], help="Filter classes by base class"),
    ] = None,
    json_output: Annotated[
        bool,
        cyclopts.Parameter(name=["--json"], help="Output as JSON"),
    ] = False,
) -> None:
    """Search for symbols across a package with filters."""
    project_path = _resolve_dir(path)

    pkg = get_package(project_path)

    kind_enum = SymbolKind(kind) if kind else None
    results = search_symbols(
        pkg, name=name, returns=returns, kind=kind_enum, inherits=inherits
    )

    if not results:
        print("No results found.")
        return

    if json_output:
        print(json.dumps([r.model_dump(mode="json") for _, r in results], indent=2))
    else:
        print(f"🔍 {len(results)} result(s):\n")
        for module, r in results:
            if hasattr(r, "signature"):
                print(f"  · {r.signature} [{module}]")
            else:
                print(f"  · class {r.name} [{module}]")

version()

Show axm-ast version.

Source code in packages/axm-ast/src/axm_ast/cli.py

@app.command()
def version() -> None:
    """Show axm-ast version."""
    from axm_ast import __version__

    print(f"axm-ast {__version__}")