CI e automação

Em scripts e pipelines, escolha o perfil explicitamente e use a saída JSON para interpretar os resultados. Injete credenciais pelo gerenciador de segredos do seu ambiente e preserve seus valores fora dos logs.

Use perfis de chave de API em pipelines: configure a variável da chave pelo gerenciador de segredos e associe seu nome com raims profile set. O login OAuth exige uma pessoa no navegador e um armazenamento seguro disponível. Ele não é iniciado automaticamente por uma requisição nem por --no-input.

Executar sem interação

Use --no-input para impedir perguntas durante a execução:

raims --no-input --profile sandbox --output json accounts fees

O CLI também considera a execução sem interação quando identifica um ambiente de CI ou quando a entrada não é um terminal. Um comando que precisar de uma entrada ausente termina com erro, sem aguardar uma resposta no terminal.

O perfil deve existir na configuração do usuário que executa o processo. Consulte Configuração e perfis para preparar essa configuração e a variável associada à chave.

Capturar a saída

--output json, ou -o json, seleciona JSON para os resultados dos comandos que apresentam dados. A saída padrão (stdout) contém o resultado; as falhas e o diagnóstico usam a saída de erros (stderr). Ajuda e scripts de autocompletar preservam seu formato próprio.

raims --no-input --output json version

Comandos da API retornam um objeto com status_code, request_id e data. Os dois primeiros campos preservam o status HTTP e o identificador da tentativa; data contém a resposta JSON. HTTP 204 retorna data: null. HTTP 202 indica um resultado pendente: o comando não aguarda a conclusão. Consulte o recurso indicado na resposta antes de repetir uma solicitação de criação, alteração, cancelamento ou devolução.

Use --debug quando precisar investigar uma execução. Ele acrescenta eventos JSON em stderr, um por linha, preservando o resultado em stdout. Os eventos omitem argumentos livres e valores de credenciais. Antes de compartilhar um arquivo capturado, revise também os caminhos e nomes locais que possam identificar seu ambiente.

Respostas da API podem conter dados da conta e segredos, como os retornados na criação ou rotação de um webhook. Proteja arquivos e logs que capturem stdout; a ocultação das credenciais no debug não remove dados da resposta solicitada.

Inspecionar headers de resposta

Use --show-headers nos comandos da API para incluir os headers públicos disponíveis na resposta:

raims --profile sandbox --output json accounts fees --show-headers

No sucesso, o JSON acrescenta response_headers; na falha, acrescenta error.response_headers. Sem a opção, o formato padrão permanece igual. Com --all, cada página mantém seus próprios headers. A propriedade é omitida quando não há metadados permitidos.

A seleção contém Request-Id, X-Request-Id, Idempotency-Replayed, Retry-After e Raims-Rate-Limited-Reason, quando presentes e válidos. Isso permite conferir um replay idempotente ou a espera informada pela API. Credenciais, cookies e outros headers não são apresentados. A opção não altera o resultado da requisição nem a política de retry.

Erros em modo texto também apresentam o identificador da tentativa, os detalhes por campo, a espera e o motivo do limite, quando disponíveis. Os códigos de saída permanecem os mesmos.

Controlar as cores do terminal

No modo texto, o CLI usa cores na ajuda, nos campos JSON, nos status e nas mensagens de erro. --color auto é o padrão: cada saída usa cores quando está conectada a um terminal compatível e o ambiente permite.

Para desativar as cores em uma execução:

raims --color off doctor

--color on força cores na saída de texto, inclusive em arquivos e pipes. on e off prevalecem sobre as variáveis de ambiente. Em auto, NO_COLOR não vazio desativa cores; depois dele, CLICOLOR_FORCE não vazio e diferente de 0 força cores. Sem essas condições, CLICOLOR=0, CI ou TERM=dumb desativam as cores. O CLI avalia stdout e stderr separadamente.

--output json, eventos JSONL de --debug e scripts de autocompletar sempre saem sem códigos ANSI, mesmo com --color on. As cores não alteram os valores, os status HTTP ou os códigos de saída.

Enviar um corpo JSON

Use --data-file CAMINHO nos comandos que recebem corpo. Prepare um arquivo UTF-8 com os campos descritos na referência da API. Por exemplo, para editar os textos de uma cobrança:

{
  "title": "Pedido de integração",
  "description": null
}

raims --profile sandbox --output json charges update CHARGE_ID --data-file charge-update.json

Substitua CHARGE_ID pelo ID de uma cobrança da empresa e do ambiente da chave. Nesse PATCH, description: null limpa a descrição, enquanto um campo omitido preserva seu valor. O CLI valida a entrada e envia o JSON sem converter inteiros nem trocar omissão por null. As regras de cada campo seguem o endpoint. O limite de corpo no CLI é 8 MiB.

--data-file - lê o JSON de stdin, inclusive em CI e com --no-input. Essa opção recebe dados do pipeline e não abre uma pergunta no terminal.

Usar flags para campos simples

Os comandos com corpo oferecem flags para campos escalares de primeiro nível, derivadas dos nomes da API. Por exemplo, tax_id vira --tax-id:

raims customers create --tax-id 12345678909 --full-name "Cliente de teste" --dry-run

Consulte --help para ver as flags de cada comando. Strings, inteiros, números e booleanos mantêm seus tipos; 0, false e uma string vazia são enviados quando informados explicitamente. Uma flag omitida não envia o campo nem aplica o valor padrão exibido na ajuda.

Use --body-null CAMPO para enviar null em um campo com flag que permita esse valor. Informe o nome JSON do campo; repita a opção para outros campos:

raims charges update CHARGE_ID --title "Pedido revisado" --body-null description --dry-run

Não informe um valor e --body-null para o mesmo campo. Flags de corpo não podem ser combinadas com --data-file, mesmo quando ele lê stdin. Objetos sem opções próprias, listas de objetos e campos sem flag continuam sendo enviados pelo arquivo JSON ou por stdin. As validações e regras do endpoint permanecem as mesmas.

Enviar listas por flags

Repita a flag de uma lista para enviar seus itens na ordem informada. Por exemplo, para preparar o cadastro de um webhook com dois tipos de evento:

raims webhooks create --name "Pedidos pagos" --url https://webhooks.example.com/raims --events charge.paid --events refund.completed --dry-run

O mesmo formato atende --payment-method-types em cobranças e links de pagamento e --identifiers na exclusão em lote de clientes. Cada ocorrência adiciona um item; vírgulas não separam valores. Os tipos, os valores aceitos, a quantidade de itens e a aceitação de duplicatas seguem o endpoint.

Omitir a flag preserva a omissão do campo. Nas listas que aceitam null, use o nome JSON com --body-null, por exemplo --body-null payment_method_types. As listas desses comandos exigem pelo menos um item quando informadas; enviar [] por arquivo também é inválido. Não combine valores e null para a mesma lista, nem flags de corpo com --data-file.

Enviar metadata por flags

Na criação e atualização de clientes e cobranças, repita --metadata CHAVE=VALOR para associar informações do seu sistema ao recurso:

raims customers update CUSTOMER_ID --metadata pedido=123 --metadata origem=site --dry-run

Substitua CUSTOMER_ID pelo ID do cliente. Os valores são sempre textos: pedido=123 envia "123", e observacao=null envia o texto "null". O primeiro = separa a chave do valor; os seguintes fazem parte do texto. --metadata observacao= envia uma string vazia. Pontos nas chaves são literais, sem criar objetos aninhados.

Omitir essas opções preserva a omissão de metadata. Não repita uma chave nem combine um valor com --metadata-null para a mesma chave. As opções de mapa vazio e de limpeza não podem ser combinadas com valores ou remoções individuais. Flags de corpo continuam exclusivas com --data-file.

O mapa aceita até 32 chaves, com 1 a 40 caracteres cada. Use letras sem acentos, números, ponto, hífen ou sublinhado. Os valores aceitam até 500 caracteres, e o conteúdo total do mapa tem limite de 8 KiB. Consulte os guias de clientes e cobranças para as regras do recurso.

Enviar logo e favicon

Use --upload-file CAMINHO nos comandos de preparação de logo ou favicon para obter os metadados da imagem e enviar seu conteúdo:

raims --profile sandbox accounts checkout-settings logo-uploads create --upload-file logo.png
raims --profile sandbox accounts checkout-settings favicon-uploads create --upload-file favicon.png

O arquivo deve ser PNG ou JPEG, com até 512 KiB. O logo aceita de 128 a 2048 pixels em cada dimensão. O favicon deve ser quadrado, com lados de 128 a 512 pixels. O CLI lê um arquivo local; essa opção não recebe stdin. Não combine --upload-file com --data-file ou flags dos campos do corpo: tipo, tamanho e dimensões vêm do próprio arquivo.

Para conferir a imagem e os metadados antes de preparar o envio:

raims accounts checkout-settings logo-uploads create --upload-file logo.png --dry-run

A prévia lê e valida a imagem sem usar perfil, chave ou rede. A execução real prepara o envio na API e faz o PUT dos bytes pela URL temporária, sem enviar a chave da Raims a esse destino. O prazo retornado em expires_at limita o envio; --timeout também vale para cada requisição. Não há repetição automática.

O resultado preserva os dados da API em data e acrescenta upload.bytes quando o arquivo é enviado. Para mudar a imagem do checkout, use o data.id retornado na flag --logo-upload-id ou --favicon-upload-id de raims accounts checkout-settings update. Consulte o resultado com raims accounts checkout-settings get; a aplicação pode continuar pendente. Enviar o arquivo sozinho não altera a aparência.

Se o envio dos bytes falhar, a imagem não será aplicada. Prepare um novo envio antes de tentar novamente. Sem --upload-file, os comandos continuam recebendo metadados JSON e retornando as instruções para você enviar o arquivo.

Salvar boletos e comprovantes

Acrescente --save CAMINHO para salvar o PDF retornado pela consulta de boleto, comprovante de pagamento ou comprovante de estorno:

raims --profile sandbox charges boleto CHARGE_ID --save boleto.pdf
raims --profile sandbox charges receipt CHARGE_ID --save pagamento.pdf
raims --profile sandbox refunds receipt REFUND_ID --save estorno.pdf

O diretório de destino deve existir. O CLI não sobrescreve um arquivo existente e só disponibiliza o destino depois de receber o arquivo inteiro e conferir seu formato. Sem --save, o comando continua retornando os dados e a URL temporária do documento.

Com a opção, o resultado acrescenta download, com path e bytes. O limite é 32 MiB. --timeout também limita a requisição de download. --save não pode ser combinado com --dry-run. Salvar um boleto não confirma seu pagamento; os documentos de Sandbox continuam identificando uma simulação.

Conferir uma requisição sem enviar

Acrescente --dry-run a um comando da API para validar e apresentar a requisição sem enviá-la:

raims --no-input --output json customers list --page-size 20 --dry-run

A prévia não lê a configuração, o perfil ou a chave, não consulta a API e não ativa atualizações. O resultado JSON informa dry_run, method, url, headers e, quando houver, body. Authorization não aparece na saída.

Em comandos com corpo, informe um arquivo ou as flags de campos aceitas pelo comando. A entrada passa pela mesma validação de campos e tipos. A prévia pode conter dados pessoais ou financeiros informados no corpo; proteja a saída como protegeria o arquivo original. Não combine --dry-run com --all, pois as páginas seguintes dependem dos cursores retornados pela API.

Percorrer páginas

Por padrão, uma listagem consulta uma página. Use --page-size para informar o tamanho e consulte --help para os filtros daquele comando. Flags de consulta usam hífen, como --page-size, preservando os nomes JSON da API nas respostas.

Para percorrer as páginas seguintes:

raims --no-input --profile sandbox --output json customers list --all --max-pages 100

Com --all --output json, stdout usa JSON Lines: cada linha é um objeto com status_code, request_id e data, que contém list e page daquela página. A saída não é um único array. O CLI preserva filtros, ordenação e tamanho da página e avança pelos cursores retornados pela API.

--max-pages exige --all, aceita de 1 a 10.000 e usa 100 por padrão. Se o limite for atingido com resultados restantes, o comando termina com API_PAGE_LIMIT_REACHED. Para continuar, copie data.page.next_after da última página para --after, preservando os filtros. Copie o cursor inteiro, sem calcular ou interpretar seu conteúdo. Não combine --after e --before. Uma consulta iniciada com --before percorre o sentido inverso e continua por data.page.previous_before.

Uma falha de rede, cancelamento ou limite pode ocorrer depois de páginas emitidas. Confira o código de saída e trate os resultados anteriores como parciais quando o percurso terminar com erro.

Tratar falhas

Confira o código de saída do processo antes de interpretar o resultado:

Com --output json, uma falha gera um objeto em stderr, em uma única linha:

{
  "error": {
    "code": "PROFILE_NOT_FOUND",
    "message": "The selected profile does not exist. Run 'raims profile list'.",
    "kind": "config"
  },
  "exit_code": 3
}

Use error.code e o código de saída para decidir a ação da automação. error.message serve ao diagnóstico humano e seu texto pode melhorar. Quando disponíveis, error.status_code e error.request_id identificam o status HTTP e a requisição. Validações podem incluir error.details, com field, code e message. Limites podem incluir error.retry_after_seconds e error.rate_limit_reason. Use os códigos e os campos para decidir a ação, preservando a espera informada antes de tentar outra vez. Com --output json e --debug juntos, cada linha de stderr é um objeto JSON separado. No modo texto, os eventos de debug continuam em JSON por linha, e a mensagem de erro segue o formato de texto.

Falhas antes do primeiro resultado deixam stdout vazio. doctor pode apresentar o relatório e terminar com 3; listagens com --all podem ter emitido páginas antes do erro.

--timeout usa 60 segundos por requisição, incluindo tentativas e esperas; por exemplo, --timeout 30s reduz esse prazo. Com --all, o prazo vale para cada página. Leituras podem repetir falhas transitórias até três tentativas, respeitando o prazo e Retry-After. Escritas não são repetidas automaticamente. Um timeout ou cancelamento local não desfaz uma requisição aceita pela API; consulte o recurso antes de enviar outra escrita.

Controlar a versão

Na etapa de instalação do pipeline, obtenha a versão atual pelo npm:

npm install -g @raimshq/cli@latest
raims --no-input --output json version

Execute a instalação com @latest em cada execução que deva usar a versão atual publicada. O comando version informa qual versão será usada. Uma instalação já concluída permanece na mesma versão até você atualizar pelo gerenciador; a tag não ativa atualizações automáticas futuras.

Em CI, a atualização fica a cargo dessa etapa de instalação. Se RAIMS_CLI_PIN_VERSION estiver definido, ele exige a versão indicada já instalada ou conservada pelo CLI e pode impedir o uso de uma atualização. Para acompanhar a versão atual, remova essa fixação da configuração da automação. A variável não baixa versões.

Selecionar uma versão disponível na instalação direta

O instalador direto 0.1.2 consulta o patch estável mais recente da linha 0.1; seu nome não fixa a versão instalada. Os exemplos de instalação por npm também usam @latest para resolver a versão atual.

A atualização automática exige uma instalação direta com pacote assinado e canal de distribuição configurado. Consulte raims update status para conferir a política da sua instalação.

Ambientes de CI desativam consultas e ativações automáticas. Para exigir a versão selecionada na sua instalação direta, derive RAIMS_CLI_PIN_VERSION da versão executada. Os exemplos usam o destino padrão; ajuste o caminho se instalou em outra pasta:

$cliExecutable = "$env:LOCALAPPDATA\Raims\CLI\raims.exe"
$cliBuild = & $cliExecutable --no-input --output json version | ConvertFrom-Json
if ($LASTEXITCODE -eq 0 -and $cliBuild.version) {
  $env:RAIMS_CLI_PIN_VERSION = $cliBuild.version
  & $cliExecutable --no-input --output json version
}

O pin exige uma versão já instalada ou conservada pelo CLI; ele não baixa outra versão. Se ela não estiver disponível, a execução termina com erro. Definir o pin não instala uma versão nem transforma @latest em uma instalação fixada para execuções futuras.

A fixação vale para comandos como version e os de perfis. Para investigar uma versão fixada ausente, doctor, update status, ajuda, autocompletar, open e prévias com --dry-run continuam acessíveis. Esses comandos de inspeção preservam a versão instalada, sem consultar, baixar ou ativar atualizações.

raims licenses também permanece acessível quando a versão fixada está ausente. Ele lê somente os textos incluídos no executável em uso.

RAIMS_CLI_NO_UPDATE=1 desativa a consulta e a ativação de atualizações pendentes, preservando a versão já ativa. Instalações mantidas por um gerenciador de pacotes seguem o mecanismo de atualização desse gerenciador.

Consulte a política da instalação com:

raims --output json update status

Na instalação direta, uma atualização pode ser baixada silenciosamente durante o uso e ativada na próxima execução elegível. O comando em andamento mantém sua versão. Preserve as versões em cache, a instalação original e os backups; não há limpeza automática desse histórico.