CLI do Python

CLI do Python

Use o comando nextpdf para extrair conteúdo de arquivos Portable Document Format (PDF) no terminal. Aponte-o para um endpoint do NextPDF Connect, envie um PDF e receba uma saída estruturada — texto citado, tabelas, a árvore sintática abstrata (AST) semântica completa ou um resumo de metadados — na saída padrão (stdout) ou em um arquivo.

Estrutura do comando

O comando nextpdf é um grupo de comandos do Click. As opções de conexão e sessão — --base-url, --api-key, --log-level, --output/-o e --strict — pertencem ao grupo, portanto coloque-as antes do subcomando. Coloque o subcomando e suas opções, como --format ou --page, depois:

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

Se você colocar uma opção de grupo depois do subcomando, o comando falha. Por exemplo, nextpdf info document.pdf --base-url ... relata Error: No such option: --base-url e sai com status 2, porque o Click já está analisando o subcomando info quando encontra --base-url, e info não define essa opção.

Para evitar a armadilha de ordenação, forneça as credenciais por meio de variáveis de ambiente (consulte Configure uma vez por shell). Os exemplos abaixo mostram primeiro a forma com flag explícita, para deixar clara a ordem correta.

Referência rápida

Extrair texto como JavaScript Object Notation (JSON):

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

Extrair tabelas como valores separados por vírgula (CSV):

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

Inspecionar os metadados e a estrutura do documento:

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

Obter a AST semântica completa:

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

Imprimir a versão instalada do kit de desenvolvimento de software (SDK) sem contatar nenhum servidor:

nextpdf version

O comando version é o único que não precisa de --base-url nem de --api-key. Todos os outros comandos contatam o servidor e exigem ambos.

Cada exemplo lê a chave da interface de programação de aplicações (API) pela variável de ambiente NEXTPDF_API_KEY, em vez de incorporá-la à linha de comando. Trate a chave como um segredo. Uma chave literal na linha de comando fica visível no histórico do shell e na lista de processos (ps) para outros usuários no host.

Comandos e opções

Opções de grupo

Coloque-as antes do subcomando. Cada opção de conexão também é lida de uma variável de ambiente, portanto você pode omitir a flag quando a variável estiver definida.

Opção	Variável de ambiente	Padrão	Finalidade
--base-url	NEXTPDF_BASE_URL	(obrigatório)	Localizador uniforme de recursos (URL) do servidor NextPDF Connect.
--api-key	NEXTPDF_API_KEY	(obrigatório)	Chave de API para autenticação bearer.
--log-level	—	warning	Nível de detalhamento do registro: debug, info, warning ou error. Os registros vão para a saída de erro padrão (stderr).
--output, -o	—	stdout	Grava a saída do comando em um arquivo em vez de stdout.
--strict	—	desativado	Reservado para uso futuro. A flag é analisada hoje, mas não altera o comportamento.
--help, -h	—	—	Mostra a ajuda e sai.

Os valores de --base-url e --api-key são obrigatórios para todos os comandos, exceto version. Se qualquer um deles estiver ausente — sem flag e sem variável de ambiente — o comando imprime um erro e sai com status 1.

nextpdf extract text

Extrai blocos de texto citado. Cada bloco inclui uma âncora de citação com identificador de nó, índice de página, caixa delimitadora e pontuação de confiança.

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

Opção	Valores	Padrão	Finalidade
--format	json, markdown, plain	json	Formato de saída.
--page	inteiro	todas as páginas	Extrai apenas este índice de página baseado em 0.
--headings-only	flag	desativado	Extrai apenas os nós de cabeçalho.

PDF_PATH é um caminho de arquivo ou - para ler os bytes do PDF da entrada padrão (stdin).

nextpdf extract tables

Extrai todas as tabelas com âncoras de citação e estrutura no nível de célula.

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

Opção	Valores	Padrão	Finalidade
--format	json, csv	json	Formato de saída.
--page-start	inteiro	primeira página	Índice da página inicial (baseado em 0).
--page-end	inteiro	última página	Índice da página final (baseado em 0).

PDF_PATH é um caminho de arquivo ou - para ler da stdin.

nextpdf ast

Retorna a AST semântica completa como JSON: uma árvore hierárquica de nós, incluindo cabeçalhos, parágrafos, tabelas, listas e figuras, com caixas delimitadoras e conteúdo de texto.

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

Opção	Valores	Padrão	Finalidade
--page-start	inteiro	primeira página	Índice da página inicial (baseado em 0).
--page-end	inteiro	última página	Índice da página final (baseado em 0).
--token-budget	inteiro	ilimitado	Limite aproximado de tokens para a AST retornada.

PDF_PATH é um caminho de arquivo ou - para ler da stdin. O comando ast produz uma árvore de documento; ele não compara dois PDFs. Para fazer comparação estrutural, consulte Receita: comparar duas revisões de PDF.

nextpdf info

Imprime um resumo JSON compacto de um documento: versão do esquema, hash de origem, contagem de páginas, contagem estimada de tokens, tipo do nó raiz e número de filhos da raiz.

nextpdf [GROUP OPTIONS] info PDF_PATH

PDF_PATH é um caminho de arquivo ou - para ler da stdin.

nextpdf version

Imprime a versão instalada do SDK, como nextpdf 1.1.0, e sai. Este comando não contata nenhum servidor e não precisa de credenciais.

nextpdf version

Configure uma vez por shell

Defina as opções de conexão uma vez como variáveis de ambiente e omita as flags repetidas. Essa forma também evita completamente a armadilha de ordenação de opções, porque as credenciais nunca aparecem na linha de comando.

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

No Windows PowerShell:

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

Prefira carregar a chave a partir de um armazenamento de segredos ou de um arquivo .env mantido fora do controle de versão. Não cole uma chave de produção em uma sessão de terminal compartilhada nem em um script que você inclui em commit.

Formatos de saída

Selecione o formato de saída por comando com --format. Os comandos de texto e de tabela aceitam mais de um formato; ast e info sempre emitem JSON.

Comando	Formatos	Padrão
extract text	json, markdown, plain	json
extract tables	json, csv	json
ast	json	json
info	json	json

Escolha JSON quando um programa downstream precisar de índices de página, pontuações de confiança ou identificadores de nó. Escolha CSV quando uma planilha ou um pipeline tabular consumir as tabelas. Escolha texto plain ou markdown quando uma pessoa ou uma ferramenta somente de texto ler o resultado.

Análise da saída JSON

O comando de texto emite um array JSON de blocos citados. Cada bloco tem text, um objeto citation (node_id, page_index, bbox, confidence) e um node_type opcional. Envie a saída para um arquivo com --output ou redirecione o stdout; depois analise-a.

Este exemplo de shell usa jq para manter apenas os cabeçalhos na página 0:

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

Os mesmos dados podem ser analisados diretamente em Python. A interface de linha de comando (CLI) grava um array JSON, portanto carregue-o com a biblioteca padrão e leia os campos tipados:

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

Quando você precisar de modelos validados e tipados em vez de dicionários brutos, chame o SDK diretamente, em vez de analisar a saída da CLI. Consulte a Visão geral do Python para conhecer o cliente NextPDF e o tipo de retorno CitedTextBlock.

Análise da saída CSV

Com --format csv, o comando de tabela grava um bloco CSV por tabela. Uma linha de comentário, # Table N (pM), precede cada tabela e indica o número da tabela baseado em 1 e o índice de página baseado em 0. Uma linha em branco separa tabelas consecutivas. A CLI coloca os valores das células entre aspas e faz escape com o módulo csv do Python, de modo que valores que contêm vírgulas, aspas ou quebras de linha sejam preservados sem perda.

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

Como o arquivo contém vários blocos CSV, divida-o nas linhas de comentário antes de analisar cada bloco como uma tabela independente:

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

Códigos de saída e detecção de erros

A CLI usa três códigos de saída. Verifique $? em scripts de shell ou $LASTEXITCODE no PowerShell para decidir o fluxo conforme o sucesso ou a falha. Leia as mensagens de diagnóstico no stderr, que permanece separado dos dados no stdout.

Código de saída	Significado	Exemplos
0	Sucesso.	Um comando foi concluído; version foi impresso.
1	Erro de tempo de execução. A CLI imprime Error: <message> no stderr.	Arquivo de entrada não encontrado ou não é um arquivo comum, stdin vazio, --base-url/--api-key ausente ou inválido, qualquer erro do lado do servidor (licença obrigatória, cota excedida, PDF não marcado, tempo limite de build ou outra falha de API).
2	Erro de uso, relatado pelo Click.	Comando ou opção desconhecido (incluindo uma opção de grupo colocada depois do subcomando), um argumento obrigatório ausente, como PDF_PATH.

Toda falha do lado do servidor retorna o código de saída 1 com uma mensagem legível por humanos no stderr. O SDK lança uma exceção tipada — NextPDFLicenseError (Hypertext Transfer Protocol (HTTP) 402), QuotaExceededError (HTTP 429), AstNoStructTreeError (HTTP 422, PDF não marcado), AstBuildTimeoutError (HTTP 504) ou a base NextPDFAPIError. A CLI captura todas elas pela base compartilhada NextPDFError, imprime a mensagem e sai com 1. A CLI não expõe códigos de saída distintos por tipo de falha. Para distinguir, por exemplo, um erro de cota de um erro de licença em um script, inspecione o texto da mensagem no stderr ou chame o SDK diretamente (consulte a Visão geral do Python para as classes de exceção).

Use este padrão de script para separar os dados dos diagnósticos:

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

Com --output, a CLI grava os dados no arquivo indicado e imprime apenas a linha de confirmação Written to <path> no stderr, de modo que o stdout permaneça vazio. Sem --output, os dados vão para o stdout e você pode redirecioná-los.

Receitas

Cada receita abaixo usa somente comandos e flags verificados. Em todos os casos, as credenciais vêm do ambiente.

Receita: extrair tabelas de faturas para CSV

Transforme uma pasta de faturas em um arquivo CSV por documento para uma planilha ou um pipeline de contabilidade:

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

Cada out/<name>.csv contém um bloco CSV por tabela detectada, com um cabeçalho # Table N (pM) antes de cada bloco. Analise os blocos com o leitor de CSV acima.

Receita: criar um sumário de documento

Combine --headings-only com o formato markdown para produzir um sumário rápido, que você pode ler ou colar em anotações:

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

Receita: comparar duas revisões de PDF

O comando ast da CLI retorna a árvore de um documento; ele não tem subcomando de comparação. A comparação estrutural reside no SDK como client.ast.get_ast_diff(...) e no servidor Model Context Protocol (MCP) como a ferramenta nextpdf_diff. Execute a comparação por meio do 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"))

Para executar a mesma comparação a partir de um agente de inteligência artificial (IA), em vez de um script, registre o servidor MCP e chame a ferramenta nextpdf_diff. Consulte a página Servidor MCP do Python.

Receita: transmitir um PDF de outra ferramenta

Leia os bytes do PDF da stdin com - para encadear nextpdf após uma ferramenta que emite um PDF no próprio stdout:

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

O argumento - instrui o comando a ler o documento da stdin. Se nenhum byte chegar, o comando relata um erro e sai com 1.

Notas de desempenho

A CLI cria cada resposta na memória e a grava de uma só vez. Redirecionar ou encaminhar a saída via pipe é simples, mas a saída não é produzida de forma incremental. Uma AST ou um conjunto grande de tabelas fica totalmente armazenado em buffer antes que o primeiro byte chegue ao stdout ou ao arquivo --output. Planeje memória e latência para respostas de documento inteiro, não para um fluxo.

Cada invocação de nextpdf cria um novo cliente e uma nova conexão HTTP, portanto um loop sobre muitos arquivos abre e fecha uma conexão por arquivo. O custo da conexão geralmente é pequeno em comparação com o tempo de extração do lado do servidor, mas se torna uma sobrecarga real em escala.

• Reutilize um único endpoint. Aponte cada invocação para a mesma implantação do NextPDF Connect, para que o servidor possa reutilizar caches aquecidos e pools de conexão. Evite distribuir um lote entre endpoints, a menos que esteja fazendo balanceamento de carga intencionalmente.
• Limite o trabalho por chamada. Use --page, --page-start/--page-end, ou --token-budget para processar apenas as páginas de que você precisa. Intervalos de páginas menores reduzem tanto o tempo do servidor quanto o tamanho da resposta; --token-budget limita a AST que o agente precisa ler.
• Agrupe em um único processo para tarefas grandes. Para lotes de alto volume, prefira o SDK do Python a chamadas repetidas da CLI. Um único cliente NextPDF ou AsyncNextPDF de longa duração reutiliza uma única conexão HTTP em pool em todos os documentos, o que elimina a inicialização por processo e a configuração de conexão que um loop da CLI paga a cada execução. A Visão geral do Python mostra o ciclo de vida do cliente, e AsyncNextPDF oferece suporte a extração concorrente em muitos PDFs.
• Mantenha os registros fora do caminho dos dados. Deixe --log-level no padrão para execuções em lote. Os registros de diagnóstico vão para o stderr e não corrompem os dados do stdout, mas elevar o nível para debug adiciona ruído e uma pequena sobrecarga.