Python CLI

Python CLI

Gebruik de opdracht nextpdf om inhoud uit Portable Document Format-bestanden (PDF) in de terminal te extraheren. Wijs de opdracht naar een NextPDF Connect-eindpunt, geef een PDF mee en ontvang gestructureerde uitvoer — geciteerde tekst, tabellen, de volledige semantische Abstract Syntax Tree (AST) of een metadatasamenvatting — via standaarduitvoer (stdout) of in een bestand.

Opdrachtstructuur

De opdracht nextpdf is een Click-opdrachtgroep. Verbindings- en sessieopties — --base-url, --api-key, --log-level, --output/-o en --strict — horen bij de groep, dus plaats deze vóór de subopdracht. Plaats de subopdracht en de bijbehorende opties, zoals --format of --page, erna:

nextpdf [GROUP OPTIONS] COMMAND [SUBCOMMAND] PDF_PATH [COMMAND OPTIONS]

Als u een groepsoptie na de subopdracht plaatst, mislukt de opdracht. Zo rapporteert nextpdf info document.pdf --base-url ... bijvoorbeeld Error: No such option: --base-url en sluit de opdracht af met status 2, omdat Click de subopdracht info dan al verwerkt wanneer het --base-url tegenkomt, terwijl info die optie niet definieert.

Geef inloggegevens door via omgevingsvariabelen om deze volgordevalkuil te vermijden (zie Eenmalig per shell configureren). De onderstaande voorbeelden tonen eerst de vorm met expliciete vlaggen, zodat de juiste volgorde duidelijk is.

Beknopt overzicht

Tekst extraheren als JavaScript Object Notation (JSON):

nextpdf --base-url http://localhost:8080 --api-key "$NEXTPDF_API_KEY" extract text document.pdf

Tabellen extraheren als comma-separated values (CSV):

nextpdf --base-url http://localhost:8080 --api-key "$NEXTPDF_API_KEY" extract tables invoice.pdf --format csv

Documentmetadata en -structuur inspecteren:

nextpdf --base-url http://localhost:8080 --api-key "$NEXTPDF_API_KEY" info document.pdf

De volledige semantische AST ophalen:

nextpdf --base-url http://localhost:8080 --api-key "$NEXTPDF_API_KEY" ast document.pdf

De geïnstalleerde versie van de software development kit (SDK) afdrukken zonder server te benaderen:

nextpdf version

De opdracht version is de enige opdracht die noch --base-url noch --api-key nodig heeft. Alle andere opdrachten benaderen de server en vereisen beide.

In elk voorbeeld wordt de sleutel van de application programming interface (API) gelezen uit de omgevingsvariabele NEXTPDF_API_KEY, in plaats van op de opdrachtregel te staan. Behandel de sleutel als een geheim. Een letterlijke sleutel op de opdrachtregel is zichtbaar voor andere gebruikers op de host, in uw shellgeschiedenis en in de proceslijst (ps).

Opdrachten en opties

Groepsopties

Plaats deze vóór de subopdracht. Elke verbindingsoptie leest ook uit een omgevingsvariabele, zodat u de vlag kunt overslaan wanneer de variabele is ingesteld.

Optie	Omgevingsvariabele	Standaard	Doel
--base-url	NEXTPDF_BASE_URL	(vereist)	Uniform resource locator (URL) van de NextPDF Connect-server.
--api-key	NEXTPDF_API_KEY	(vereist)	API-sleutel voor bearer-authenticatie.
--log-level	—	warning	Logniveau: debug, info, warning of error. Logregels gaan naar standaardfout (stderr).
--output, -o	—	stdout	Schrijf de opdrachtuitvoer naar een bestand in plaats van naar stdout.
--strict	—	uit	Gereserveerd voor toekomstig gebruik. De vlag wordt vandaag verwerkt, maar verandert het gedrag niet.
--help, -h	—	—	Help tonen en afsluiten.

De waarden --base-url en --api-key zijn vereist voor elke opdracht behalve version. Als een van beide waarden ontbreekt — geen vlag en geen omgevingsvariabele — drukt de opdracht een fout af en sluit deze af met status 1.

nextpdf extract text

Extraheer geciteerde tekstblokken. Elk blok bevat een citatieanker met een knooppuntidentificator, pagina-index, omgrenzingsvak en betrouwbaarheidsscore.

nextpdf [GROUP OPTIONS] extract text PDF_PATH [--format FORMAT] [--page N] [--headings-only]

Optie	Waarden	Standaard	Doel
--format	json, markdown, plain	json	Uitvoerformaat.
--page	geheel getal	alle pagina’s	Alleen deze 0-gebaseerde pagina-index extraheren.
--headings-only	vlag	uit	Alleen kopknooppunten extraheren.

PDF_PATH is een bestandspad, of - om PDF-bytes te lezen uit standaardinvoer (stdin).

nextpdf extract tables

Extraheer elke tabel met citatieankers en structuur op celniveau.

nextpdf [GROUP OPTIONS] extract tables PDF_PATH [--format FORMAT] [--page-start N] [--page-end N]

Optie	Waarden	Standaard	Doel
--format	json, csv	json	Uitvoerformaat.
--page-start	geheel getal	eerste pagina	Beginpagina-index (0-gebaseerd).
--page-end	geheel getal	laatste pagina	Eindpagina-index (0-gebaseerd).

PDF_PATH is een bestandspad, of - om van stdin te lezen.

nextpdf ast

De volledige semantische AST als JSON retourneren: een hiërarchische boom van knooppunten met koppen, alinea’s, tabellen, lijsten en figuren, plus omgrenzingsvakken en tekstinhoud.

nextpdf [GROUP OPTIONS] ast PDF_PATH [--page-start N] [--page-end N] [--token-budget N]

Optie	Waarden	Standaard	Doel
--page-start	geheel getal	eerste pagina	Beginpagina-index (0-gebaseerd).
--page-end	geheel getal	laatste pagina	Eindpagina-index (0-gebaseerd).
--token-budget	geheel getal	onbegrensd	Benaderde tokenlimiet voor de geretourneerde AST.

PDF_PATH is een bestandspad, of - om van stdin te lezen. De opdracht ast produceert één documentboom; deze vergelijkt geen twee PDF’s. Zie voor structureel vergelijken Recept: twee PDF-revisies vergelijken.

nextpdf info

Een compacte JSON-samenvatting van één document afdrukken: schemaversie, bronhash, aantal pagina’s, geschat aantal tokens, type van het hoofdknooppunt en het aantal onderliggende hoofdknooppunten.

nextpdf [GROUP OPTIONS] info PDF_PATH

PDF_PATH is een bestandspad, of - om van stdin te lezen.

nextpdf version

De geïnstalleerde SDK-versie afdrukken, zoals nextpdf 1.1.0, en afsluiten. Deze opdracht benadert geen server en heeft geen inloggegevens nodig.

nextpdf version

Eenmalig per shell configureren

Stel de verbindingsopties eenmalig in als omgevingsvariabelen en laat de herhaalde vlaggen weg. Deze vorm vermijdt ook de valkuil met de optievolgorde volledig, omdat de inloggegevens nooit op de opdrachtregel verschijnen.

export NEXTPDF_BASE_URL=http://localhost:8080
export NEXTPDF_API_KEY=your-key
nextpdf extract text document.pdf

In Windows PowerShell:

$env:NEXTPDF_BASE_URL = "http://localhost:8080"
$env:NEXTPDF_API_KEY = "your-key"
nextpdf extract text document.pdf

Laad de sleutel bij voorkeur uit een secret store of een .env-bestand dat u buiten versiebeheer houdt. Plak een productiesleutel niet in een gedeelde terminalsessie of in een script dat u commit.

Uitvoerformaten

Selecteer het uitvoerformaat per opdracht met --format. De tekst- en tabelopdrachten ondersteunen meer dan één formaat; ast en info geven altijd JSON terug.

Opdracht	Formaten	Standaard
extract text	json, markdown, plain	json
extract tables	json, csv	json
ast	json	json
info	json	json

Kies JSON wanneer een downstream-programma pagina-indexen, betrouwbaarheidsscores of knooppuntidentificatoren nodig heeft. Kies CSV wanneer een spreadsheet of tabellaire pijplijn de tabellen verwerkt. Kies plain- of markdown-tekst wanneer een persoon of een tekstuele tool het resultaat leest.

JSON-uitvoer parseren

De tekstopdracht geeft een JSON-array met geciteerde blokken terug. Elk blok heeft text, een citation-object (node_id, page_index, bbox, confidence) en optioneel node_type. Stuur de uitvoer naar een bestand met --output, of leid stdout om en parseer de uitvoer daarna.

Dit shellvoorbeeld gebruikt jq om alleen koppen op pagina 0 te behouden:

nextpdf --output blocks.json extract text report.pdf --format json
jq '[.[] | select(.citation.page_index == 0 and .node_type == "heading") | .text]' blocks.json

Dezelfde gegevens zijn probleemloos te parseren in Python. De command-line interface (CLI) schrijft een JSON-array, dus laad deze met de standaardbibliotheek en lees de getypeerde velden:

"""Parse cited text blocks emitted by `nextpdf extract text --format json`."""

import json
from pathlib import Path


def load_headings(blocks_path: Path) -> list[str]:
    """Return the text of every heading block on page 0.

    Args:
        blocks_path: Path to the JSON file written by `nextpdf extract text`.

    Returns:
        The text of each heading-type block whose citation is on page 0.
    """
    raw = blocks_path.read_text(encoding="utf-8")
    blocks: list[dict[str, object]] = json.loads(raw)
    headings: list[str] = []
    for block in blocks:
        citation = block["citation"]
        if block.get("node_type") == "heading" and citation["page_index"] == 0:
            headings.append(str(block["text"]))
    return headings


if __name__ == "__main__":
    for heading in load_headings(Path("blocks.json")):
        print(heading)

Als u gevalideerde, getypeerde modellen nodig hebt in plaats van ruwe dictionaries, roept u de SDK rechtstreeks aan in plaats van CLI-uitvoer te parseren. Zie het Python-overzicht voor de NextPDF-client en het bijbehorende retourtype CitedTextBlock.

CSV-uitvoer parseren

Met --format csv schrijft de tabelopdracht één CSV-blok per tabel. Een commentaarregel, # Table N (pM), staat vóór elke tabel en vermeldt het 1-gebaseerde tabelnummer en de 0-gebaseerde pagina-index ervan. Een lege regel scheidt opeenvolgende tabellen. De CLI zet celwaarden tussen aanhalingstekens en escapet ze met de csv-module van Python, zodat waarden met komma’s, aanhalingstekens of regeleinden veilig kunnen worden gelezen en geschreven.

nextpdf --output tables.csv extract tables statement.pdf --format csv

Omdat het bestand meerdere CSV-blokken bevat, splitst u het op de commentaarregels voordat u elk blok als een zelfstandige tabel parseert:

"""Split multi-table CSV output from `nextpdf extract tables --format csv`."""

import csv
import io
from pathlib import Path


def read_tables(csv_path: Path) -> list[list[list[str]]]:
    """Parse the multi-block CSV file into a list of tables.

    Each table is a list of rows; each row is a list of cell strings.
    The leading `# Table N (pM)` comment row is dropped from every table.

    Args:
        csv_path: Path to the file written by `nextpdf extract tables`.

    Returns:
        One parsed table per `# Table` block in the file.
    """
    text = csv_path.read_text(encoding="utf-8")
    tables: list[list[list[str]]] = []
    current: list[str] = []
    for line in text.splitlines(keepends=True):
        if line.startswith("# Table ") and current:
            tables.append(_parse_block(current))
            current = []
        current.append(line)
    if current:
        tables.append(_parse_block(current))
    return tables


def _parse_block(lines: list[str]) -> list[list[str]]:
    """Parse one CSV block, discarding its leading comment row."""
    reader = csv.reader(io.StringIO("".join(lines)))
    rows = [row for row in reader if row]
    return rows[1:] if rows and rows[0] and rows[0][0].startswith("# Table ") else rows


if __name__ == "__main__":
    for index, table in enumerate(read_tables(Path("tables.csv")), start=1):
        print(f"table {index}: {len(table)} rows")

Afsluitcodes en foutdetectie

De CLI gebruikt drie afsluitcodes. Controleer $? in shellscripts, of $LASTEXITCODE in PowerShell, om op succes of mislukking te vertakken. Lees diagnostische berichten vanaf stderr; die blijft gescheiden van de gegevens op stdout.

Afsluitcode	Betekenis	Voorbeelden
0	Succes.	Een opdracht is voltooid; version heeft uitvoer afgedrukt.
1	Runtimefout. De CLI drukt Error: <message> af naar stderr.	Invoerbestand niet gevonden of geen regulier bestand, lege stdin, ontbrekende of ongeldige --base-url/--api-key, elke serverzijdige fout (licentie vereist, quotum overschreden, ongetagde PDF, build-time-out of andere API-fout).
2	Gebruiksfout, gerapporteerd door Click.	Onbekende opdracht of optie (waaronder een groepsoptie die na de subopdracht is geplaatst), een ontbrekend vereist argument, zoals PDF_PATH.

Elke serverzijdige fout retourneert afsluitcode 1 met een leesbaar bericht op stderr. De SDK genereert een getypeerde uitzondering — NextPDFLicenseError (Hypertext Transfer Protocol (HTTP) 402), QuotaExceededError (HTTP 429), AstNoStructTreeError (HTTP 422, ongetagde PDF), AstBuildTimeoutError (HTTP 504), of de basis NextPDFAPIError. De CLI vangt ze allemaal af via hun gedeelde basis NextPDFError, drukt het bericht af en sluit af met status 1. De CLI biedt geen afzonderlijke afsluitcodes per fouttype. Als u in een script bijvoorbeeld een quotumfout van een licentiefout wilt onderscheiden, inspecteert u de berichttekst op stderr of roept u de SDK rechtstreeks aan (zie het Python-overzicht voor de uitzonderingsklassen).

Gebruik dit scriptpatroon om gegevens van diagnostiek te scheiden:

#!/usr/bin/env bash
set -euo pipefail

# Credentials come from the environment, not the command line.
: "${NEXTPDF_BASE_URL:?set NEXTPDF_BASE_URL}"
: "${NEXTPDF_API_KEY:?set NEXTPDF_API_KEY}"

if nextpdf --output contract.ast.json ast contract.pdf; then
  echo "AST written to contract.ast.json"
else
  status=$?
  echo "nextpdf failed with exit code ${status}" >&2
  exit "${status}"
fi

Met --output schrijft de CLI gegevens naar het opgegeven bestand en drukt alleen de bevestigingsregel Written to <path> af naar stderr, zodat stdout leeg blijft. Zonder --output gaan de gegevens naar stdout en kunt u deze omleiden.

Recepten

Elk recept hieronder gebruikt uitsluitend geverifieerde opdrachten en vlaggen. In alle gevallen komen de inloggegevens uit de omgeving.

Recept: factuurtabellen extraheren naar CSV

Zet een map met facturen om naar één CSV-bestand per document voor een spreadsheet- of boekhoudpijplijn:

#!/usr/bin/env bash
set -euo pipefail

: "${NEXTPDF_BASE_URL:?set NEXTPDF_BASE_URL}"
: "${NEXTPDF_API_KEY:?set NEXTPDF_API_KEY}"

mkdir -p out
for pdf in invoices/*.pdf; do
  name="$(basename "${pdf}" .pdf)"
  nextpdf --output "out/${name}.csv" extract tables "${pdf}" --format csv
done

Elke out/<name>.csv bevat één CSV-blok per gedetecteerde tabel, met een # Table N (pM)-kop vóór elk blok. Parseer de blokken met de hierboven getoonde CSV-reader.

Recept: een documentoverzicht opbouwen

Combineer --headings-only met het markdown-formaat om snel een overzicht te maken dat u kunt lezen of in notities kunt plakken:

nextpdf --output outline.md extract text whitepaper.pdf --headings-only --format markdown

Recept: twee PDF-revisies vergelijken

De CLI-opdracht ast retourneert de boom voor één document; het heeft geen diff-subopdracht. Structureel vergelijken bevindt zich in de SDK als client.ast.get_ast_diff(...) en in de Model Context Protocol-server (MCP) als de tool nextpdf_diff. Voer de vergelijking uit via de SDK:

"""Compare two PDF revisions structurally with the NextPDF SDK.

The API key is read from the environment, never hard-coded.
"""

import os
from pathlib import Path

from nextpdf import NextPDF


def diff_revisions(original: Path, modified: Path) -> None:
    """Print a structural diff summary between two PDF revisions.

    Args:
        original: Path to the earlier PDF revision.
        modified: Path to the later PDF revision.
    """
    base_url = os.environ["NEXTPDF_BASE_URL"]
    api_key = os.environ["NEXTPDF_API_KEY"]

    client = NextPDF(base_url=base_url, api_key=api_key)
    result = client.ast.get_ast_diff(
        original.read_bytes(),
        modified.read_bytes(),
    )

    summary = result.summary
    print(f"added:   {summary.added_node_count}")
    print(f"removed: {summary.removed_node_count}")
    print(f"changed: {summary.changed_node_count}")
    for entry in result.diff:
        preview = entry.text_preview or ""
        print(f"  {entry.type:<8} {entry.node_type:<12} p{entry.page_index} {preview}")


if __name__ == "__main__":
    diff_revisions(Path("contract-v1.pdf"), Path("contract-v2.pdf"))

Als u dezelfde vergelijking vanuit een artificial intelligence-agent (AI) in plaats van vanuit een script wilt uitvoeren, registreert u de MCP-server en roept u de tool nextpdf_diff aan. Zie de pagina Python MCP-server.

Recept: een PDF vanuit een andere tool binnenlezen

Lees PDF-bytes van stdin met - om nextpdf achter een tool te gebruiken die een PDF naar zijn eigen stdout schrijft:

curl --silent https://example.com/report.pdf | nextpdf info -

Het argument - geeft aan dat de opdracht het document van stdin moet lezen. Als er geen bytes binnenkomen, rapporteert de opdracht een fout en sluit af met 1.

Prestatie-opmerkingen

De CLI bouwt elk antwoord in het geheugen op en schrijft het in één keer weg. Uitvoer omleiden of doorsturen is eenvoudig, maar de uitvoer wordt niet stapsgewijs geproduceerd. Een grote AST of tabelverzameling wordt volledig gebufferd voordat de eerste byte naar stdout of het --output-bestand gaat. Plan geheugen en latentie voor antwoorden voor het hele document, niet voor een stream.

Elke aanroep van nextpdf maakt een nieuwe client en een nieuwe HTTP-verbinding aan, dus een lus over veel bestanden opent en sluit per bestand een verbinding. De verbindingskosten zijn doorgaans klein vergeleken met de serverzijdige extractietijd, maar worden op schaal echte overhead.

• Hergebruik één eindpunt. Richt elke aanroep op dezelfde NextPDF Connect-deployment, zodat de server opgewarmde caches en verbindingspools kan hergebruiken. Vermijd het spreiden van een batch over meerdere eindpunten, tenzij u bewust loadbalancing toepast.
• Begrens het werk per aanroep. Gebruik --page, --page-start/--page-end, of --token-budget om alleen de pagina’s te verwerken die u nodig hebt. Kleinere paginabereiken verkleinen zowel de servertijd als de antwoordgrootte; --token-budget begrenst de AST die uw agent moet lezen.
• Batch in één proces voor grote taken. Geef voor batches met een hoog volume de voorkeur aan de Python-SDK boven herhaalde CLI-aanroepen. Eén langlevende NextPDF- of AsyncNextPDF-client hergebruikt één gepoolde HTTP-verbinding voor elk document, waardoor de opstartkosten per proces en het telkens opzetten van een verbinding wegvallen. Een CLI-lus betaalt die kosten anders bij elke aanroep. Het Python-overzicht toont de levenscyclus van de client, en AsyncNextPDF ondersteunt gelijktijdige extractie over veel PDF’s.
• Houd logregels buiten het gegevenspad. Laat --log-level op de standaardwaarde staan voor batchruns. Diagnostische logregels gaan naar stderr en corrumperen de stdout-gegevens niet, maar het verhogen van het niveau naar debug voegt ruis en lichte overhead toe.