pdfx: a linha de comando do PDF123

Como instalo o pdfx?#

Instale o pacote globalmente para ter o comando pdfx. Ou execute-o uma vez, sem instalar.

npm install -g @pdf123/cli
pdfx --version

npx @pdf123/cli merge a.pdf b.pdf -o merged.pdf
bunx @pdf123/cli merge a.pdf b.pdf -o merged.pdf

bun add -g @pdf123/cli e pnpm add -g @pdf123/cli também funcionam. Não é preciso instalar mais nada.

Como começo?#

Estes seis comandos mostram os padrões mais comuns.

pdfx list                                          # every tool; --category security for one category
pdfx describe watermark                            # a tool's fields and defaults
pdfx merge a.pdf b.pdf -o merged.pdf
pdfx compress *.pdf -o compressed/                 # several files: one result per file
pdfx watermark in.pdf --watermarkText DRAFT
pdfx pipeline a.pdf b.pdf --step merge --step compress -o out.pdf

Como executo qualquer ferramenta?#

O primeiro argumento é o id da ferramenta. Os arquivos de entrada e as opções da ferramenta vêm depois. Toda opção de uma ferramenta é uma flag, escrita como o nome do campo da API (--pageNumbers) ou em kebab-case (--page-numbers). Um número negativo pode vir depois da flag, separado por espaço, como em --rotation -90, ou depois de um sinal de igual.

pdfx <tool> [files...] [--<field> <value>]...

Use pdfx list para ver as ferramentas. Ele aceita --category ou --group, e --query com palavras para buscar. Use pdfx describe <tool> para ver o endpoint, as entradas aceitas, se a ferramenta roda como lote e cada campo com seu valor padrão e os valores permitidos. Um id de ferramenta desconhecido recebe sugestões, e um id digitado errado termina com o código 2.

Quais comandos correspondem a quais páginas de ferramentas?#

Como processo muitos arquivos de uma vez?#

Passe vários arquivos para uma ferramenta de arquivo único e o pdfx executa um lote. Use -o com um diretório que termine em barra. A ferramenta roda uma vez por arquivo, dois arquivos por vez por padrão. Mude isso com --concurrency.

pdfx compress *.pdf -o compressed/
pdfx protect *.pdf --password secret --concurrency 4 -o locked/

O pdfx imprime uma linha, input -> saved, à medida que cada arquivo termina. Um arquivo com falha é informado na saída de erro padrão e os demais arquivos continuam até o fim. Pressione Ctrl-C uma vez para abortar a requisição em andamento; os arquivos já salvos são mantidos. Um segundo Ctrl-C sai imediatamente com o código 130. Com --idempotency-key k, cada arquivo envia k:<index>, e uma repetição da mesma requisição devolve o primeiro resultado por 24 horas.

Um lote de uma ferramenta que devolve um relatório, como get-info, não grava arquivos sem -o. Ele imprime os relatórios organizados por arquivo de entrada.

Como encadeio ferramentas em uma requisição?#

pdfx pipeline executa várias ferramentas em uma única requisição. Repita --step para cada ferramenta. Para definir opções, passe um array JSON com --steps.

pdfx pipeline a.pdf b.pdf --step merge --step compress -o out.pdf
pdfx pipeline in.pdf --steps '[{"tool":"watermark","params":{"watermarkText":"DRAFT"}},{"tool":"compress"}]' -o out.pdf

As etapas não podem usar ferramentas que precisam de um segundo arquivo.

Como abro PDFs protegidos por senha?#

--input-password abre antes todas as entradas criptografadas. --password-for <file>=<password> define a senha de um arquivo. Pode ser repetido, e * como nome de arquivo cobre os demais. Isso serve para um lote que mistura arquivos bloqueados e abertos. Para merge e images-to-pdf, cada arquivo indicado é desbloqueado separadamente antes de a ferramenta rodar.

pdfx compress locked.pdf --input-password secret -o out.pdf
pdfx compress report.pdf --password-for report.pdf=secret -o out.pdf
pdfx merge a.pdf b.pdf --password-for a.pdf=secret -o merged.pdf

As mesmas opções funcionam em um pipeline. Para remover a proteção de forma permanente, use a ferramenta Desbloquear com a opção --password dela.

Como funcionam a entrada e a saída?#

• Uma entrada - lê a entrada padrão, uma vez por execução. -o - grava o resultado na saída padrão.
• -o file.pdf grava esse arquivo. -o dir/ grava dentro de um diretório. Um diretório que ainda não existe precisa da barra final, pois um nome sem ela é gravado como arquivo.
• Sem -o, os resultados vão para o diretório atual com o nome de arquivo dado pelo servidor.
• Dentro de um diretório, o pdfx nunca substitui um arquivo existente; ele escolhe um nome novo. Um -o file.pdf explícito substitui esse arquivo.
• Um nome de arquivo em -o cuja extensão contradiz o resultado, como um ZIP de split salvo como .pdf, é recusado com o código de saída 2 e code: output_mismatch. Nada é gravado.
• Uma saída que não pode ser gravada é um erro de uso detectado antes de qualquer envio.

cat in.pdf | pdfx compress - -o - > out.pdf

O que o --json imprime?#

Para um resultado salvo, --json imprime o caminho, o tipo de conteúdo e o tamanho. Uma ferramenta que devolve um relatório imprime o próprio relatório. Um lote imprime um relatório com um status por arquivo.

{ "path": "one.pdf", "contentType": "application/pdf", "bytes": 1040 }

{
  "processed": 2,
  "unmatched": 0,
  "failed": 0,
  "files": [
    { "input": "/abs/a.pdf", "ok": true, "path": "comp/a.pdf", "contentType": "application/pdf", "bytes": 1040 }
  ]
}

Um arquivo com falha tem error e reason no lugar de path e bytes. Uma ferramenta de filtro sem correspondência imprime { "matched": false }. pdfx list --json imprime linhas com id, category, group, name, description, returns, files e filter.

Quais opções valem para todas as ferramentas?#

Quais são os códigos de saída?#

As falhas imprimem linhas reason:, code: e hint: quando o servidor as fornece, para que um script possa ramificar sem comparar texto. Uma ferramenta que não encontra nada para devolver, como pdf-to-csv em um PDF sem tabelas, sai com 1 e code: no_content em vez de gravar um arquivo vazio. Os códigos estão em Códigos de erro.

Como aponto o pdfx para o meu próprio servidor?#

Defina PDFX_API_BASE, ou passe --api-base, com o endereço de um pdfx-server próprio. Acrescente PDFX_API_KEY se o seu servidor exigir uma chave. Veja Self-host.

export PDFX_API_BASE=http://localhost:8080
export PDFX_API_KEY=<your-key>
pdfx compress in.pdf

Como executo um endpoint que a CLI não conhece?#

pdfx call envia uma requisição bruta para um id de operação ou um caminho /api/.... Use --field name=value para campos de formulário e --file field=path para arquivos extras. Ele envia exatamente uma requisição e não valida nada localmente, então senhas e lotes são recusados.

pdfx call general/merge-pdfs a.pdf b.pdf -o merged.pdf
pdfx call /api/v1/misc/flatten in.pdf --field flattenOnlyForms=true -o flat.pdf

Páginas relacionadas#

• Visão geral para desenvolvedores, com a API REST e a autenticação
• SDK TypeScript, a biblioteca sobre a qual a linha de comando é construída
• Servidores MCP para agentes de IA
• O artigo “pdfx CLI: One Catalog, Called From Your Terminal” no blog do PDF123

FAQ#

O pdfx funciona offline?#

Não. O pdfx envia cada arquivo para a API do PDF123 ou para o seu próprio servidor e salva o resultado localmente, então a base da API precisa estar acessível.

O pdfx precisa de uma chave de API?#

Não. O uso anônimo funciona. Defina PDFX_API_KEY ou passe --api-key se o seu servidor exigir uma. A chave é enviada no cabeçalho X-API-KEY.

Qual versão do Node o pdfx exige?#

Node 20.3 ou mais recente, ou Bun.

O pdfx vai sobrescrever meus arquivos?#

Não quando grava dentro de um diretório: um arquivo existente nunca é substituído. Se você mesmo der o nome do arquivo de saída com -o file.pdf, esse arquivo é substituído, então escolha um nome novo quando quiser manter o original.

O que acontece quando uma ferramenta de filtro não encontra correspondência?#

As ferramentas de filtro, cujos ids começam com filter-, deixam o arquivo passar quando a condição delas é atendida. Quando não é, o pdfx imprime no match e sai com o código 0. Em um lote, esse arquivo conta como sem correspondência, não como falha.