CI and automation

In scripts and pipelines, select a profile explicitly and use JSON output to interpret results. Inject credentials through your environment's secret manager and keep their values out of logs.

Use API-key profiles in pipelines: set the key variable through your secret manager and associate its name with raims profile set. OAuth sign-in needs a person in the browser and an available secure store. A request or --no-input does not start sign-in automatically.

Run without interaction

Use --no-input to prevent prompts during execution:

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

The CLI also uses non-interactive execution when it detects a CI environment or when its input is not a terminal. A command that requires missing input returns an error instead of waiting for an answer in the terminal.

The profile must exist in the configuration of the user running the process. See Configuration and profiles to prepare that configuration and the variable associated with the key.

Capture output

--output json, or -o json, selects JSON for commands that return data. Standard output (stdout) contains the result; errors and diagnostic output use standard error (stderr). Help and completion scripts keep their own formats.

raims --no-input --output json version

API commands return an object with status_code, request_id and data. The first two fields preserve the HTTP status and attempt identifier; data contains the JSON response. HTTP 204 returns data: null. HTTP 202 indicates a pending result: the command does not wait for completion. Query the resource identified in the response before repeating a create, update, cancellation, or refund request.

Use --debug to investigate an invocation. It adds diagnostic output to stderr as one JSON event per line, keeping the result on stdout. Events omit free-form arguments and credential values. Before sharing a captured file, review local paths and names that may identify your environment.

API responses can contain account data and secrets, such as those returned when creating or rotating a webhook. Protect files and logs that capture stdout; hiding credentials in debug events does not remove data from the requested response.

Inspect response headers

Use --show-headers on API commands to include the public headers available in the response:

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

On success, JSON adds response_headers; on failure, it adds error.response_headers. Without the option, the default format stays the same. With --all, each page keeps its own headers. The property is omitted when no allowed metadata is available.

The selection contains Request-Id, X-Request-Id, Idempotency-Replayed, Retry-After, and Raims-Rate-Limited-Reason when present and valid. This lets you check an idempotent replay or the wait time provided by the API. Credentials, cookies, and other headers are excluded. The option does not change the request result or retry policy.

Text errors also show the attempt identifier, field details, wait time, and rate limit reason when available. Exit codes remain the same.

Control terminal colors

In text mode, the CLI uses colors for help, JSON fields, statuses, and error messages. --color auto is the default: each output uses colors when connected to a compatible terminal and allowed by the environment.

To disable colors for an invocation:

raims --color off doctor

--color on forces colors in text output, including files and pipes. on and off take precedence over environment variables. In auto, a non-empty NO_COLOR disables colors. Next, a non-empty CLICOLOR_FORCE other than 0 forces colors. Otherwise, CLICOLOR=0, CI, or TERM=dumb disable colors. The CLI evaluates stdout and stderr separately.

--output json, JSONL events from --debug, and completion scripts always exclude ANSI codes, even with --color on. Colors do not change values, HTTP statuses, or exit codes.

Send a JSON body

Use --data-file PATH for commands that accept a body. Prepare a UTF-8 file with the fields described in the API reference. For example, to edit a charge's text fields:

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

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

Replace CHARGE_ID with a charge ID in the key's company and environment. In this PATCH, description: null clears the description, while omitting a field preserves its value. The CLI validates the input and sends the JSON without converting integers or replacing omission with null. Each field follows its endpoint's rules. The CLI body limit is 8 MiB.

--data-file - reads JSON from stdin, including in CI and with --no-input. This option receives pipeline data without prompting in the terminal.

Use flags for simple fields

Commands with a body offer flags for top-level scalar fields, derived from API names. For example, tax_id becomes --tax-id:

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

Check --help for the flags supported by each command. Strings, integers, numbers, and booleans keep their types; 0, false, and empty strings are sent when explicitly supplied. An omitted flag does not send the field or apply the default value shown in help.

Use --body-null FIELD to send null for a field with a flag that accepts it. Supply the JSON field name and repeat the option for additional fields:

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

Do not supply both a value and --body-null for the same field. Body flags cannot be combined with --data-file, including when it reads stdin. Objects without dedicated options, arrays of objects, and fields without a flag still use a JSON file or stdin. Endpoint validation and rules remain the same.

Send lists with flags

Repeat a list flag to send its items in the supplied order. For example, to preview a webhook registration with two event types:

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

The same format supports --payment-method-types for charges and payment links and --identifiers for batch customer deletion. Each occurrence adds one item; commas do not separate values. Types, accepted values, item counts, and duplicate handling follow the endpoint.

Omitting the flag keeps the field omitted. For lists that accept null, use the JSON name with --body-null, such as --body-null payment_method_types. These commands require at least one item in a supplied list; sending [] through a file is also invalid. Do not supply both values and null for the same list, or combine body flags with --data-file.

Send metadata with flags

When creating or updating customers and charges, repeat --metadata KEY=VALUE to associate information from your system with the resource:

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

Replace CUSTOMER_ID with the customer ID. Values are always strings: pedido=123 sends "123", and observacao=null sends the string "null". The first = separates the key from its value; subsequent ones are part of the string. --metadata observacao= sends an empty string. Dots in keys are literal and do not create nested objects.

Omitting these options keeps metadata omitted. Do not repeat a key or combine a value with --metadata-null for the same key. Empty-map and clear-map options cannot be combined with values or individual removals. Body flags remain mutually exclusive with --data-file.

The map accepts up to 32 keys, each with 1 to 40 characters. Use unaccented letters, numbers, dots, hyphens, or underscores. Values accept up to 500 characters, and the entire map has an 8 KiB limit. See the customer and charge guides for resource rules.

Upload a logo and favicon

Use --upload-file PATH with a logo or favicon preparation command to read the image metadata and upload its contents:

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

The file must be PNG or JPEG, up to 512 KiB. Logos accept 128 to 2048 pixels in each dimension. Favicons must be square, with sides of 128 to 512 pixels. The CLI reads a local file; this option does not accept stdin. Do not combine --upload-file with --data-file or body field flags: the type, size, and dimensions come from the file itself.

To check the image and metadata before preparing an upload:

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

The preview reads and validates the image without using a profile, key, or network. A real execution prepares the upload through the API and sends the bytes with PUT to the temporary URL, without sending the Raims key to that destination. The returned expires_at limits the upload; --timeout also applies to each request. Requests are not retried automatically.

The result keeps the API data in data and adds upload.bytes when the file is uploaded. To change the checkout image, use the returned data.id with --logo-upload-id or --favicon-upload-id on raims accounts checkout-settings update. Check the result with raims accounts checkout-settings get; application may still be pending. Uploading the file alone does not change the appearance.

If sending the bytes fails, the image will not be applied. Prepare a new upload before trying again. Without --upload-file, the commands keep accepting JSON metadata and returning instructions for you to send the file.

Save boletos and receipts

Add --save PATH to save the PDF returned by a boleto, payment receipt, or refund receipt lookup:

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

The destination directory must exist. The CLI does not overwrite an existing file and only makes the destination available after receiving the entire file and checking its format. Without --save, the command keeps returning the document's metadata and temporary URL.

With the option, the result adds download, containing path and bytes. The limit is 32 MiB. --timeout also limits the download request. --save cannot be combined with --dry-run. Saving a boleto does not confirm payment; Sandbox documents still identify a simulation.

Preview a request without sending it

Add --dry-run to an API command to validate and display the request without sending it:

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

The preview does not read configuration, a profile, or a key. It does not call the API or activate updates. The JSON result contains dry_run, method, url, headers, and body when present. Authorization is not included.

For commands with a body, supply a file or the field flags supported by the command. Input goes through the same field and type validation. The preview can contain personal or financial data from the body; protect its output as you would protect the original file. Do not combine --dry-run with --all, because later pages depend on cursors returned by the API.

Read multiple pages

By default, a list command reads one page. Use --page-size to request a size and check --help for the command's filters. Query options use hyphens, such as --page-size, while responses keep the API's JSON field names.

To read the following pages:

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

With --all --output json, stdout uses JSON Lines: each line is an object with status_code, request_id and data, containing list and page for that page. The output is not a single array. The CLI preserves filters, sorting, and page size while advancing through the cursors returned by the API.

--max-pages requires --all, accepts 1 to 10,000, and defaults to 100. If the limit is reached with more results available, the command returns API_PAGE_LIMIT_REACHED. To continue, copy data.page.next_after from the last page into --after, keeping the same filters. Copy the whole cursor without calculating or interpreting its content. Do not combine --after and --before. A query started with --before traverses backward and continues through data.page.previous_before.

A network failure, cancellation, or page limit can occur after pages have been emitted. Check the exit code and treat earlier results as partial when the traversal ends with an error.

Handle failures

Check the process exit code before interpreting the result:

With --output json, a failure produces one object on a single line in stderr:

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

Use error.code and the exit code to decide how the automation should proceed. error.message is for human diagnosis and its wording may improve. When available, error.status_code and error.request_id identify the HTTP status and request. Validation errors can include error.details, with field, code, and message. Limits can include error.retry_after_seconds and error.rate_limit_reason. Use codes and fields to decide what to do, respecting the reported wait before trying again. With --output json and --debug together, each line in stderr is a separate JSON object. In text mode, debug events remain JSON lines and the error message uses text formatting.

Failures before the first result leave stdout empty. doctor can print its report and exit with 3; list commands using --all can emit pages before an error.

--timeout defaults to 60 seconds per request, including retries and waits; for example, --timeout 30s reduces that deadline. With --all, the deadline applies to each page. Reads can retry transient failures up to three attempts, respecting the deadline and Retry-After. Writes are not retried automatically. A local timeout or cancellation does not undo a request accepted by the API; query the resource before sending another write.

Control the version

Fetch the current version through npm during the pipeline's installation step:

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

Run the installation with @latest on each run that should use the current published version. The version command reports which version will be used. A completed installation stays on the same version until you update through the package manager; the tag does not enable future automatic updates.

In CI, that installation step handles updates. If RAIMS_CLI_PIN_VERSION is set, it requires the specified version to be already installed or retained by the CLI and can prevent an update from being used. To follow the current version, remove that pin from the automation configuration. The variable does not download versions.

Select an available direct-installation version

The 0.1.2 direct installer selects the latest stable patch in the 0.1 line; its name does not pin the installed version. npm installation examples also use @latest to resolve the current version.

Automatic updates require a direct installation with a signed package and a configured distribution channel. Run raims update status to check your installation's policy.

CI environments disable automatic checks and activation. To require the version selected in your direct installation, derive RAIMS_CLI_PIN_VERSION from the running version. These examples use the default destination; adjust the path if you installed elsewhere:

$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
}

The pin requires a version already installed or retained by the CLI; it does not download another version. If that version is unavailable, execution returns an error. Setting the pin does not install a version or turn @latest into a pinned installation for future runs.

The pin applies to commands such as version and profile commands. To investigate an unavailable pinned version, doctor, update status, help, completion, open, and previews using --dry-run remain accessible. These inspection commands preserve the installed version without checking for, downloading, or activating updates.

raims licenses also remains accessible when the pinned version is unavailable. It only reads the texts included in the executable being used.

RAIMS_CLI_NO_UPDATE=1 disables checks and activation of pending updates, preserving the version already active. Installations maintained by a package manager follow that manager's update mechanism.

Inspect your installation's policy with:

raims --output json update status

In a direct installation, an update can be downloaded silently during use and activated on the next eligible invocation. The running command keeps its version. Preserve cached versions, the original installation, and backups; that history is not automatically cleaned up.