CLI pdfx: local primeiro, nuvem quando você precisar
O pdfx processa PDFs na sua máquina por padrão. Ative o modo nuvem com uma URL base e uma chave de API quando precisar dos endpoints REST do PDF123.
PDF123 é o nome do produto. O pdfx é a CLI curta que conversa com as mesmas operações. O caminho padrão é local: ler um arquivo, executar a operação pelo pdf-core, gravar uma saída. Sem conta, sem chave de API, sem upload.
Local primeiro quer dizer que o arquivo nunca sai daqui
Uma chamada típica é pdfx merge a.pdf b.pdf -o merged.pdf ou pdfx compress input.pdf. O processamento roda onde o binário roda. Isso serve para tarefas de CI num runner privado, para scripts ao lado de um lote de faturas e para qualquer caso em que enviar o arquivo a um terceiro é a resposta errada.
O modo local não é uma camada fina que envia os bytes para outro lugar sem você saber. A CLI compartilha o mesmo registro de operações do servidor (pdf_core::ops::run). Se você quiser o caminho de rede, é você quem ativa, com --cloud.
Os subcomandos embutidos cobrem as operações mais comuns: merge, split, compress, rotate, extract, OCR, convert, protect, unlock, watermark e afins. Na saída local, o padrão é gravar em arquivo com -o / --output; - escreve em stdout.
--cloud é o mesmo catálogo por HTTP
Quando você precisa da API hospedada (ou do seu próprio pdfx-server), passe --cloud com --api-base e --api-key (ou PDFX_API_KEY). O modo nuvem depende do curl por baixo dos panos e falha se nenhuma chave de API estiver definida. Exemplo do skill publicado:
pdfx --cloud --api-base "$PDFX_API_BASE" --api-key "$PDFX_API_KEY" \
merge a.pdf b.pdf -o merged.pdf
Quando não é definido, --api-base assume https://pdf123.xyz, a API hospedada. Para uma pilha local de Docker Compose, aponte-o para http://127.0.0.1:8080. A CLI vira um cliente da superfície REST documentada em Desenvolvedores; os nomes das operações batem com as ferramentas do portal e com a OpenAPI (/v1/openapi.json).
O modo nuvem não muda o que uma operação significa. Compress continua sendo compressão de streams com qpdf; o OCR continua devolvendo texto Markdown pelo caminho em Rust, não uma camada pesquisável em PDF. Opções antigas da CLI que apontam para parâmetros de OCR ignorados desde a época do Java (por exemplo, um campo languages) não mudam esse contrato.
Por que existem dois modos
O modo local cobre confiança offline e custo zero de ida e volta pela rede. O modo nuvem cobre limites de requisição compartilhados, execução em uma máquina que só tem a CLI e o curl instalados e equipes que já emitem chaves de API. Agentes também podem chamar a mesma URL base via MCP em /mcp ou pelo skill em dist/skills/pdf-toolbox/SKILL.md. Índices de descoberta como o /llms.txt ajudam agentes de código a encontrar endpoints; eles não são sinal de posicionamento no Google.
Para repetir com segurança um POST que altera estado, envie Idempotency-Key (veja Idempotency-Key: novas tentativas seguras em tarefas de PDF). O caminho de nuvem da CLI continua sendo uma requisição HTTP por invocação; use o cabeçalho quando o seu wrapper repetir a chamada.
Como escolher o modo na prática
Use o modo local quando os arquivos precisam ficar no runner, quando você já tem o binário pdfx e as dependências nativas naquela máquina e quando a latência é dominada pela operação, não pelo upload. Use o modo nuvem quando as dependências pesadas só existem no servidor, quando você quer os mesmos limites de requisição e a mesma medição de uso dos outros clientes da API, ou quando os agentes já têm uma chave de API para https://pdf123.xyz ou para a sua URL self-hosted.
Não misture as expectativas: o OCR local continua seguindo o contrato de saída em Markdown de misc/ocr-pdf, e o compress em nuvem continua sendo streams com qpdf, não subdivisão de fontes. Trocar de modo muda onde a operação roda, não a semântica do catálogo.
O que a CLI não é
O pdfx não é uma interface gráfica de desktop nem uma biblioteca de OCR que você embute em outro aplicativo. É um cliente de linha de comando para operações de PDF: local por padrão, HTTP quando você pede. Tarefas pontuais no navegador continuam no portal (Comprimir, OCR e o resto do catálogo). Automações que preferem um binário podem ficar no pdfx.
Comparações da mesma operação entre navegador, curl, MCP e CLI estão em A mesma operação em quatro clientes. Comece por Desenvolvedores para chaves e OpenAPI, ou por Self-host se a URL base da API deve ser a sua própria pilha de Docker Compose.