Configuration and profiles

Use a profile for each account or integration. You can sign in through your browser with OAuth or associate an API key with an environment variable. The configuration stores the required references; secrets stay outside the profile file.

Sign in with your browser

To use your account in the terminal, choose a profile name and environment:

raims login --profile pessoal --environment sandbox
raims profile use pessoal

The CLI opens the Raims sign-in page. Check the account and the Raims CLI application, choose permissions, review the authorized environments, and complete the security confirmation. Return to the terminal when authorization finishes. You do not need to copy an API key or give the CLI your password.

Running login again checks the authorization with the server. If the session is still valid, the CLI reuses the connection. If it has expired or been revoked, the CLI opens a new consent flow. A temporary outage does not create another connection: wait and try again. Choose another profile name to connect a different account.

Access remains limited to the granted permissions and the current access of the person who authorized the connection. The session refreshes automatically while the connection remains valid. Credentials are protected by the operating system's secure store. If it is unavailable, restore access or use an API-key profile; the CLI does not save the session as plain text.

Before each request, the CLI checks that the token will remain valid for the period set by --timeout and refreshes it when needed. If its lifetime is still insufficient, the request is not sent. See the guidance for OAUTH_TOKEN_LIFETIME_INSUFFICIENT in Diagnostics.

To inspect local session metadata without a network request:

raims --profile pessoal auth status

This inspection does not confirm current server access. Use auth check to make an authenticated read.

To open the browser yourself, run:

raims login --profile pessoal --environment sandbox --no-browser

Open the displayed address and keep the command running until you finish. The browser must be able to reach the local callback on the machine running the CLI. This option does not provide a code-based sign-in flow for another device. Sign-in requires an interactive terminal; use an API key for pipelines.

Select the environment

During OAuth sign-in, --environment sandbox or --environment production sets the profile's initial environment. Subsequent commands use that choice. To run a command in another authorized environment, supply the option:

raims --profile pessoal --environment sandbox customers list
raims --profile pessoal --environment production accounts fees

The option only selects an already authorized environment. It does not expand access or change the connection's environments. Check the account and environment before sending a Production write.

For API-key profiles, the key determines the environment. Use a key for the environment you need; an environment option does not convert the credential.

Sign out

To revoke the profile's OAuth connection:

raims logout --profile pessoal

After revocation succeeds, the CLI removes the local session and profile. If revocation fails, it keeps them so you can try again.

You can also revoke access in

Integration, Authorized applications. Signing out of the Dashboard does not close the CLI connection. To connect again, run raims login and review the permissions.

Create a profile

For scripts and integrations that use an API key:

The name sandbox does not determine a request's environment. The API determines the environment and company from the validated key, as described in Authentication.

For a Production credential, you can create another profile with a separate variable:

raims profile set production --api-key-env RAIMS_PRODUCTION_API_KEY

Make the key value available in that variable to the CLI process. Requests from both profiles use https://api.raims.com. The CLI does not accept another address through an option, environment variable, or profile setting.

Check API access

raims --profile sandbox --output json auth check

The command reads GET /v1/accounts/fees at https://api.raims.com with the selected profile's credential, without changing the account. It accepts both OAuth and API-key profiles. On success, it returns:

{
  "status_code": 200,
  "data": {
    "authenticated": true,
    "profile": "sandbox"
  }
}

This result confirms access to the account fees endpoint. Every other endpoint validates its own permissions and conditions. A rejection can also mean the key lacks permission for this read; it does not, by itself, prove the credential is invalid. Check the returned HTTP status and error.code.

For an API-key profile, a missing or empty variable prevents the request. The CLI does not read the key from an argument or store its value in the profile.

Choose a profile for the invocation

The CLI selects the profile in this order:

To select a profile for this invocation only:

raims --profile sandbox profile show

The flag does not change the saved default. A profile supplied through --profile takes precedence over RAIMS_PROFILE.

raims profile show NAME inspects the profile supplied as an argument even when another profile is selected. The list keeps identifying the saved default and also reports the invocation's selection in JSON output.

$env:RAIMS_PROFILE = 'sandbox'
raims profile show

Remove a profile

To remove an old profile from local configuration:

raims profile remove old-project

OAuth profiles require raims logout before removal or replacement with an API-key profile.

Supply the exact API-key profile name. Removal does not revoke the API key or change the environment variable containing it. If the removed profile was the saved default, the CLI clears that selection without choosing another profile. Run raims profile use NAME to save a new default.

Repeating the command for an already absent profile succeeds. With --output json, the result contains name and configured: false. If RAIMS_PROFILE still points to the removed profile, update or clear that selection in your terminal before running another command that uses a profile.

Set up autocompletion

Use the assistant to detect your shell and see activation instructions:

raims completion setup

Without --save, the command shows its plan without creating files. If detection does not identify a supported shell, supply --shell powershell|bash|zsh|fish. To preview the write plan and then save the PowerShell script:

raims completion setup --shell powershell --save ./raims-completion.ps1 --dry-run
raims completion setup --shell powershell --save ./raims-completion.ps1

The directory must exist and the file must be new. The CLI does not overwrite files or change your shell profile or startup file. After saving, follow the displayed instructions to activate autocompletion in the desired session, following your terminal's policy.

The assistant works without a profile, key, or network and does not activate updates. With --output json, it returns the selected shell, the source of that choice, the path when supplied, write and preview indicators, and instructions. Existing commands, such as raims completion powershell, still write the script to stdout for manual setup.

Configuration location

Check which path the CLI uses:

raims config path

By default, the file is in the raims folder inside the user's configuration directory. Set RAIMS_CONFIG_DIR to an absolute path to use another folder, such as an isolated configuration for an automation.

Keep this folder protected by the permissions of the user running the CLI. The profile file contains authentication references and metadata, without plain-text secrets. The OAuth session remains encrypted and requires access to the operating system's secure store.