Python CLI

Python CLI

Gunakan perintah nextpdf untuk mengekstrak konten dari berkas Portable Document Format (PDF) di terminal. Arahkan CLI ke endpoint NextPDF Connect, berikan PDF, lalu terima keluaran terstruktur — teks bersitasi, tabel, Abstract Syntax Tree (AST) semantik lengkap, atau ringkasan metadata — melalui keluaran standar (stdout) atau ke berkas.

Struktur perintah

Perintah nextpdf merupakan grup perintah Click. Opsi koneksi dan sesi — --base-url, --api-key, --log-level, --output/-o, dan --strict — adalah bagian dari grup, jadi tempatkan opsi tersebut sebelum subperintah. Tempatkan subperintah beserta opsinya, seperti --format atau --page, sesudahnya:

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

Jika Anda menempatkan opsi grup setelah subperintah, perintah akan gagal. Sebagai contoh, nextpdf info document.pdf --base-url ... melaporkan Error: No such option: --base-url dan keluar dengan status 2, karena Click sudah mengurai subperintah info saat menemukan --base-url, sementara info tidak mendefinisikan opsi tersebut.

Untuk menghindari masalah urutan ini, sediakan kredensial melalui variabel lingkungan (lihat Konfigurasikan sekali per shell). Contoh-contoh di bawah menampilkan bentuk flag eksplisit terlebih dahulu agar urutan yang benar tampak jelas.

Referensi singkat

Ekstrak teks sebagai JavaScript Object Notation (JSON):

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

Ekstrak tabel sebagai comma-separated values (CSV):

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

Periksa metadata dan struktur dokumen:

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

Dapatkan AST semantik lengkap:

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

Cetak versi software development kit (SDK) yang terpasang tanpa menghubungi server:

nextpdf version

Perintah version adalah satu-satunya perintah yang tidak memerlukan --base-url maupun --api-key. Semua perintah lain menghubungi server dan memerlukan keduanya.

Setiap contoh membaca kunci application programming interface (API) dari variabel lingkungan NEXTPDF_API_KEY, bukan menyematkannya pada baris perintah. Perlakukan kunci tersebut sebagai rahasia. Kunci yang ditulis langsung pada baris perintah dapat terlihat di riwayat shell Anda dan di daftar proses (ps) oleh pengguna lain pada host.

Perintah dan opsi

Opsi grup

Tempatkan opsi ini sebelum subperintah. Setiap opsi koneksi juga dapat membaca nilai dari variabel lingkungan, jadi Anda dapat menghilangkan flag tersebut setelah variabelnya disetel.

Opsi	Variabel lingkungan	Standar	Tujuan
--base-url	NEXTPDF_BASE_URL	(wajib)	Uniform resource locator (URL) untuk server NextPDF Connect.
--api-key	NEXTPDF_API_KEY	(wajib)	Kunci API untuk autentikasi bearer.
--log-level	—	warning	Tingkat detail log: debug, info, warning, atau error. Log dikirim ke aliran kesalahan standar (stderr).
--output, -o	—	stdout	Tulis keluaran perintah ke berkas, bukan ke stdout.
--strict	—	off	Dicadangkan untuk penggunaan mendatang. Saat ini flag ini tetap diurai, tetapi tidak mengubah perilaku.
--help, -h	—	—	Tampilkan bantuan dan keluar.

Nilai --base-url dan --api-key wajib untuk setiap perintah kecuali version. Jika salah satu nilai tidak ada — baik melalui flag maupun variabel lingkungan — perintah akan mencetak kesalahan dan keluar dengan status 1.

nextpdf extract text

Ekstrak blok teks bersitasi. Setiap blok mencakup penanda sitasi yang berisi pengenal node, indeks halaman, kotak pembatas, dan skor keyakinan.

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

Opsi	Nilai	Standar	Tujuan
--format	json, markdown, plain	json	Format keluaran.
--page	integer	semua halaman	Ekstrak hanya halaman dengan indeks berbasis-0 tersebut.
--headings-only	flag	mati	Ekstrak hanya node heading.

PDF_PATH adalah jalur berkas, atau - untuk membaca byte PDF dari masukan standar (stdin).

nextpdf extract tables

Ekstrak setiap tabel beserta penanda sitasi dan struktur tingkat sel.

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

Opsi	Nilai	Standar	Tujuan
--format	json, csv	json	Format keluaran.
--page-start	integer	halaman pertama	Indeks halaman awal (berbasis-0).
--page-end	integer	halaman terakhir	Indeks halaman akhir (berbasis-0).

PDF_PATH adalah jalur berkas, atau - untuk membaca dari stdin.

nextpdf ast

Kembalikan AST semantik lengkap sebagai JSON: pohon node hierarkis yang mencakup heading, paragraf, tabel, daftar, dan figur, lengkap dengan kotak pembatas dan konten teks.

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

Opsi	Nilai	Standar	Tujuan
--page-start	integer	halaman pertama	Indeks halaman awal (berbasis-0).
--page-end	integer	halaman terakhir	Indeks halaman akhir (berbasis-0).
--token-budget	integer	tak terbatas	Perkiraan batas token untuk AST yang dikembalikan.

PDF_PATH adalah jalur berkas, atau - untuk membaca dari stdin. Perintah ast menghasilkan satu pohon dokumen; perintah ini tidak membandingkan dua PDF. Untuk perbandingan struktural, lihat Resep: bandingkan dua revisi PDF.

nextpdf info

Cetak ringkasan JSON singkat dari satu dokumen: versi skema, hash sumber, jumlah halaman, perkiraan jumlah token, tipe node akar, dan jumlah anak dari akar.

nextpdf [GROUP OPTIONS] info PDF_PATH

PDF_PATH adalah jalur berkas, atau - untuk membaca dari stdin.

nextpdf version

Cetak versi SDK terpasang, seperti nextpdf 1.1.0, lalu keluar. Perintah ini tidak menghubungi server dan tidak memerlukan kredensial.

nextpdf version

Konfigurasikan sekali per shell

Atur opsi koneksi sekali sebagai variabel lingkungan, lalu hilangkan flag yang berulang. Bentuk ini juga sepenuhnya menghindari masalah urutan opsi, karena kredensial tidak pernah muncul pada baris perintah.

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

Pada Windows PowerShell:

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

Sebaiknya muat kunci dari penyimpanan rahasia atau berkas .env yang tidak dimasukkan ke kontrol versi. Jangan menempelkan kunci produksi ke sesi terminal bersama atau ke skrip yang Anda commit.

Format keluaran

Pilih format keluaran untuk tiap perintah dengan --format. Perintah teks dan tabel mendukung lebih dari satu format; ast dan info selalu menghasilkan JSON.

Perintah	Format	Standar
extract text	json, markdown, plain	json
extract tables	json, csv	json
ast	json	json
info	json	json

Pilih JSON ketika program hilir memerlukan indeks halaman, skor keyakinan, atau pengenal node. Pilih CSV ketika tabel akan dikonsumsi oleh spreadsheet atau alur tabular. Pilih format plain atau markdown ketika hasilnya dibaca oleh manusia atau alat berbasis teks.

Mengurai keluaran JSON

Perintah teks menghasilkan array JSON berisi blok bersitasi. Setiap blok memiliki text, objek citation (node_id, page_index, bbox, confidence), dan node_type opsional. Kirim keluaran ke berkas dengan --output, atau alihkan stdout, lalu uraikan.

Contoh shell ini menggunakan jq untuk menyimpan hanya heading pada halaman 0:

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

Data yang sama dapat diurai dengan rapi di Python. Antarmuka baris perintah (CLI) menulis array JSON, jadi muat dengan pustaka standar dan baca field bertipe:

"""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)

Ketika Anda memerlukan model bertipe dan tervalidasi, bukan kamus mentah, panggil SDK secara langsung alih-alih mengurai keluaran CLI. Lihat Ikhtisar Python untuk klien NextPDF dan tipe hasil CitedTextBlock-nya.

Mengurai keluaran CSV

Dengan --format csv, perintah tabel menulis satu blok CSV per tabel. Baris komentar, # Table N (pM), mendahului setiap tabel dan menyebutkan nomor tabel berbasis-1 serta indeks halaman berbasis-0-nya. Baris kosong memisahkan tabel yang berurutan. CLI mengutip dan meng-escape nilai sel dengan modul csv dari Python, sehingga nilai yang mengandung koma, tanda kutip, atau baris baru tetap aman untuk round-trip.

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

Karena berkas berisi beberapa blok CSV, pisahkan berdasarkan baris komentar sebelum Anda mengurai setiap blok sebagai tabel terpisah:

"""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")

Kode keluar dan deteksi kesalahan

CLI menggunakan tiga kode keluar. Periksa $? dalam skrip shell, atau $LASTEXITCODE dalam PowerShell, untuk menentukan cabang logika berdasarkan keberhasilan atau kegagalan. Baca pesan diagnostik dari stderr, yang tetap terpisah dari data pada stdout.

Kode keluar	Makna	Contoh
0	Berhasil.	Perintah selesai; version tercetak.
1	Kesalahan runtime. CLI mencetak Error: <message> ke stderr.	Berkas masukan tidak ditemukan atau bukan berkas reguler, stdin kosong, --base-url/--api-key hilang atau tidak valid, kesalahan sisi server apa pun (lisensi diperlukan, kuota terlampaui, PDF tanpa tag, batas waktu build, atau kegagalan API lainnya).
2	Kesalahan penggunaan, dilaporkan oleh Click.	Perintah atau opsi tidak dikenal (termasuk opsi grup yang ditempatkan setelah subperintah), argumen wajib yang hilang seperti PDF_PATH.

Setiap kegagalan di sisi server mengembalikan kode keluar 1 dengan pesan yang dapat dibaca manusia pada stderr. SDK memunculkan eksepsi bertipe — NextPDFLicenseError (Hypertext Transfer Protocol (HTTP) 402), QuotaExceededError (HTTP 429), AstNoStructTreeError (HTTP 422, PDF tanpa tag), AstBuildTimeoutError (HTTP 504), atau kelas dasar NextPDFAPIError. CLI menangkap semuanya melalui kelas dasar umum NextPDFError, mencetak pesan, dan keluar 1. CLI tidak menyediakan kode keluar terpisah untuk tiap tipe kegagalan. Untuk membedakan, misalnya, kesalahan kuota dari kesalahan lisensi dalam skrip, periksa teks pesan pada stderr atau panggil SDK secara langsung (lihat Ikhtisar Python untuk kelas eksepsi).

Gunakan pola skrip ini untuk memisahkan data dari diagnostik:

#!/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

Dengan --output, CLI menulis data ke berkas yang ditentukan dan hanya mencetak baris konfirmasi Written to <path> ke stderr, sehingga stdout tetap kosong. Tanpa --output, data dikirim ke stdout, dan Anda dapat mengalihkannya.

Resep

Setiap resep di bawah hanya menggunakan perintah dan flag yang terverifikasi. Pada setiap kasus, kredensial berasal dari lingkungan.

Resep: ekstrak tabel faktur ke CSV

Konversikan satu folder faktur menjadi satu berkas CSV per dokumen untuk spreadsheet atau alur akuntansi:

#!/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

Setiap out/<name>.csv berisi satu blok CSV per tabel yang terdeteksi, dengan header # Table N (pM) sebelum setiap blok. Uraikan blok tersebut dengan pembaca CSV yang ditampilkan di atas.

Resep: bangun kerangka dokumen

Gabungkan --headings-only dengan format markdown untuk menghasilkan kerangka ringkas yang dapat Anda baca atau tempelkan ke catatan:

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

Resep: bandingkan dua revisi PDF

Perintah ast pada CLI mengembalikan pohon untuk satu dokumen; perintah ini tidak memiliki subperintah diff. Perbandingan struktural tersedia dalam SDK sebagai client.ast.get_ast_diff(...) dan di server Model Context Protocol (MCP) sebagai alat nextpdf_diff. Jalankan diff melalui 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"))

Untuk menjalankan diff yang sama dari agen kecerdasan buatan (AI), bukan dari skrip, daftarkan server MCP dan panggil alat nextpdf_diff. Lihat halaman Server MCP Python.

Resep: alirkan PDF masuk dari alat lain

Baca byte PDF dari stdin dengan - untuk merangkai nextpdf setelah alat lain yang menghasilkan PDF pada stdout-nya sendiri:

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

Argumen - memberi tahu perintah agar membaca dokumen dari stdin. Jika tidak ada byte yang masuk, perintah akan melaporkan kesalahan dan keluar 1.

Catatan performa

CLI membangun setiap respons di memori dan menulisnya satu kali. Mengalihkan atau menyalurkan keluaran tetap mudah, tetapi keluaran tidak dihasilkan secara bertahap. AST atau kumpulan tabel yang besar di-buffer sepenuhnya sebelum byte pertama mencapai stdout atau berkas --output. Rencanakan memori dan latensi untuk respons seluruh dokumen, bukan untuk aliran.

Setiap pemanggilan nextpdf membuat klien dan koneksi HTTP baru, jadi loop atas banyak berkas akan membuka dan menutup satu koneksi per berkas. Biaya koneksi biasanya kecil dibandingkan waktu ekstraksi di sisi server, tetapi menjadi overhead nyata pada skala besar.

• Gunakan kembali satu endpoint. Arahkan setiap pemanggilan ke deployment NextPDF Connect yang sama agar server dapat menggunakan kembali cache yang sudah hangat dan pool koneksi. Hindari menyebarkan satu batch ke beberapa endpoint kecuali Anda memang sengaja menyeimbangkan beban.
• Batasi pekerjaan per panggilan. Gunakan --page, --page-start/--page-end, atau --token-budget untuk memproses hanya halaman yang Anda perlukan. Rentang halaman yang lebih kecil mengurangi waktu server sekaligus ukuran respons; --token-budget membatasi AST yang harus dibaca oleh agen Anda.
• Lakukan batch dalam satu proses untuk pekerjaan besar. Untuk batch bervolume tinggi, sebaiknya gunakan SDK Python daripada panggilan CLI berulang. Satu klien NextPDF atau AsyncNextPDF berumur panjang menggunakan kembali satu koneksi HTTP yang di-pool untuk seluruh dokumen, sehingga menghilangkan biaya startup per proses dan penyiapan koneksi yang muncul pada setiap iterasi CLI. Ikhtisar Python menampilkan siklus hidup klien, dan AsyncNextPDF mendukung ekstraksi konkuren di banyak PDF.
• Jauhkan log dari jalur data. Biarkan --log-level pada nilai standarnya untuk proses batch. Log diagnostik dikirim ke stderr dan tidak merusak data stdout, tetapi menaikkan tingkatnya ke debug menambah noise dan sedikit overhead.