Diagnostics

Use raims doctor to inspect your CLI configuration and identify what needs to be corrected in your installation.

Run the diagnostic

raims doctor

Checks cover configuration and selected profile access, local file permissions, executable identity, and the update policy. Each check reports the condition found and the applicable guidance.

A check with error makes the command exit with code 3. Warnings allow the diagnostic to complete with code 0.

To select another profile or capture the result in an automation:

raims --profile sandbox --output json doctor

The JSON includes status, build, interactive, the selected profile when present, and the checks list. Each check contains name, status, and message. The names are configuration, profile, permissions, installation, and updates.

The diagnostic does not send API requests or confirm credential validity, company permissions, or service connectivity. See Authentication and API keys for those conditions.

Check the architecture

To inspect the operating system and architecture of the executable in use:

raims --output json version

For the native Windows ARM64 CLI, the result contains os: "windows" and arch: "arm64". This local read does not require a profile, key, or network.

If you installed through npm, also check Node.js in the same terminal:

node -p "process.platform + '/' + process.arch"

To use the native package on Windows ARM64, have Node.js 22 or later for ARM64. The command above must return win32/arm64. x64 Node.js selects the x64 package even when Windows is ARM64. Once ARM64 Node.js is available, install or update with npm install -g @raimshq/cli@latest and check the CLI version again.

For direct installation, choose the installer for the desired architecture and check the executable by its full path. The installer does not replace an installation of another version or architecture. To keep both, select another user directory with -directory PATH, preserve the existing installation, and use the new executable's full path. See Direct installation.

Check API access

raims --profile sandbox --output json auth check --timeout 30s

This command sends GET /v1/accounts/fees to https://api.raims.com with the profile's OAuth session or API key. It does not change the account. A successful result contains data.authenticated: true and the profile name, confirming access to this read. Other endpoints remain subject to their own permissions and conditions.

Sandbox and Production keys use the same address. For an API-key profile, the API determines the environment from the validated key. For an OAuth profile, use the environment chosen at sign-in or supply --environment sandbox|production. To check access to another resource, use its read command and inspect the HTTP status and error.code if access is rejected. auth check does not grant permissions or perform test writes.

To inspect only an OAuth session's local metadata without accessing the secure store or network, run raims --profile pessoal auth status. This inspection does not replace server-side access verification.

Sign in again with the same CLI profile

Run raims login --profile pessoal --environment sandbox. The CLI checks the authorization with the server and reuses a valid session. If it has expired or been revoked, it opens a new consent flow in the browser. Check the profile name, account, and permissions before authorizing. Use another profile for a different account.

Temporarily unavailable CLI session refresh

If you receive OAUTH_SERVICE_UNAVAILABLE, wait and run the command again. This temporary rejection of a session refresh preserves the session for another attempt, without requiring new consent. If the error says that the refresh could not be confirmed, follow the displayed guidance before trying again.

CLI cancellation and exit code

Interrupting a command with Ctrl+C returns CANCELLED and exit code 130, including during sign-in or session refresh. Cancelling a request does not undo what the API has already accepted. If the request changed a resource, check its result before repeating it.

Investigate a failure

When you type a name close to a known command, the CLI suggests the correct spelling and shows how to open the group's help. For example, raims customers creat may suggest raims customers create. The suggestion is not executed. The error keeps the code UNKNOWN_COMMAND and exit code 2.

When an option is spelled close to a known option, the CLI may suggest a correction, such as --full-name for --full_name. If a value is missing or has the wrong format, the message shows the expected type or accepted values and the command's help, such as raims charges create --help. Ambiguous suggestions are omitted.

For metadata, use --metadata key=value; dots are part of the key's name and do not create nested options. Option errors keep INVALID_ARGUMENT, the usage category, and exit code 2, without repeating supplied values. These errors do not execute the request.

OAUTH_TOKEN_LIFETIME_INSUFFICIENT means that the CLI could not obtain a token valid for the entire request deadline, even after trying to refresh it. The API request was not sent. Use a shorter --timeout that is still appropriate for the command, or run raims logout and raims login to renew the authorization. This error uses exit code 4.

Share a diagnostic

Add --debug to obtain execution details on stderr:

raims --debug --output json doctor

Diagnostics keep the command result on stdout and hide credential values. Review paths, profile names, and other local information before sharing files. Never include API keys, tokens, or the full address of a sign-in in progress in a problem report. For API requests, include the exit code, error.code, and, when available, error.status_code and error.request_id. Also review any response captured from stdout, as it can contain account data or secrets from the requested resource.

To identify the legal texts included in the running version, use raims licenses --output json. This local read does not require a profile or network access; see Notices and licenses.