Raia CLI

raia-cli is a command-line tool for executing workflows in the Raia backend via an authenticated request. It is designed to facilitate workflow execution without requiring a graphical interface.

Installation

To install raia-cli, follow these steps:

1. Clone the repository

git clone git@github.com:raia-live/raia-cli.git
cd raia-cli

2. Create a virtual environment (optional but recommended)

python -m venv venv
source venv/bin/activate  # On macOS/Linux
venv\Scripts\activate    # On Windows

3. Install with pip

pip install -e .

This will install raia-cli in editable mode, allowing you to make changes without reinstalling.

Configuration

Before running commands, you need to define some required environment variables. You can do this manually or by creating a .env file based on example.env.

Option 1: Export variables in terminal

Copy the contents of example.env and customize it with your credentials:

export BACKEND_URL=https://dev-backend-api.app.raia.live
export TOKEN_NAME=<YOUR_TOKEN_NAME>
export TOKEN_SECRET=<YOUR_TOKEN_SECRET>

Note: Instructions on how to obtain these values are provided in the next section.

Option 2: Set the same variables mentioned in previously as environment variables in your CI/CD worker.

This step will depend on your CI-CD provider.

How to obtain TOKEN_NAME, TOKEN_SECRET, and WORKFLOW_GUID

How to obtain TOKEN_NAME and TOKEN_SECRET

1. Go to Project Settings.

2. Move to the tab named CI/CD Tokens.

3. Name your new token and click on create, you'll see the new secret and name appear in the table below.

4. Copy the value of the Name and paste it in the .env file TOKEN_NAME=<NAME> and the value of the Secret column TOKEN_SECRET=<SECRET>

How to obtain WORKFLOW_GUID

1. Go to the Automate tab and configure the workflow with the variables you want to receive from the command. The variables need to be in $format, so if you want to pass --param question="Is my service up?" you'll need to write it as $question inside the prompt text box.

2. The workflow_guid will be on the url of your workflow

3. Copy it and paste it in your .env variable WORKFLOW_GUID=<WORKFLOW_GUID> or pass it throught the command line --workflow-guid <WORKFLOW_GUID>

Using raia-cli

Once configured, you can execute workflows using different argument combinations.

raia-cli run-workflow --workflow-guid <WORKFLOW_GUID> --version <VERSION> -p key1=value1 -p key2=value2

1. Execute a workflow

Example:

raia-cli run-workflow -p branch=main -p debug=true

2. Execute a workflow specifying workflow-guid

raia-cli run-workflow --workflow-guid 12345-abcdfg-66789-hijklm --version 2 -p branch=main -p debug=true

3. Execute a workflow without specifying version (the latest version will be used by default in the backend)

raia-cli run-workflow --workflow-guid 12345-abcdfg-66789-hijklm -p key1=value1

4. Execute a workflow with only workflow-guid

raia-cli run-workflow --workflow-guid 12345-abcdfg-66789-hijklm

Error Handling

If the required environment variables are not correctly set, the CLI will display an error message and prevent execution. Make sure BACKEND_URL, TOKEN_NAME, and TOKEN_SECRET are defined before running a command. If the WORKFLOW_GUID variable is set, and you pass the workflow-guid as an argument, the CLI will prioritize the argument over the .env variable.

Policy Management Commands

The raia-cli policies command group allows you to manage Rego policy files by syncing them from Git repositories to your Raia project.

Configuration

Before using policy commands, ensure these environment variables are set:

export BACKEND_URL=https://api.raia.live
export TOKEN_NAME=your-token-name
export TOKEN_SECRET=your-token-secret

# For private GitHub repositories
export GITHUB_TOKEN=ghp_your-github-token

GitHub Authentication

For private repositories, you need a GitHub Personal Access Token:

1. Go to GitHub → Settings → Developer settings → Personal access tokens → Generate new token
2. Select scope: repo (full control of private repositories)
3. Copy the token and set GITHUB_TOKEN environment variable

For public repositories, no authentication is required.

Commands

raia-cli policies sync

Sync Rego policy files from a Git repository to your Raia project.

raia-cli policies sync --repo REPO_URL [OPTIONS]

Required Arguments:

• --repo - Git repository URL (HTTPS or SSH)

Optional Arguments:

• --branch - Git branch to sync (default: main)
• --path - Path within repo containing .rego files (default: /raia/policies/)
• --commit - Specific commit SHA to sync (optional)
• --auto-assignment - Searches for tht tool_cred_guid variable in the policy to auto assign it (temporal functionality for testing purposes)

Examples:

# Sync from public repository
raia-cli policies sync --repo https://github.com/company/policies

# Sync from private repository with custom branch
raia-cli policies sync --repo https://github.com/company/private-policies --branch develop

# Sync from specific path and commit
raia-cli policies sync \
  --repo https://github.com/company/policies \
  --path /security/policies/ \
  --commit abc123def456

# Sync with explicit project GUID
raia-cli policies sync \
  --repo https://github.com/company/policies \
  --project-guid 550e8400-e29b-41d4-a716-446655440000

raia-cli policies list

List all policies currently in your Raia project.

raia-cli policies list [OPTIONS]

Example:

raia-cli policies list

Sample Output:

Found 5 policies:

• AWS Safe Operations (pre)
  File: aws_safe_ops_pre.rego
  Connectors: aws

• Generic Secret Scrub (post)
  File: generic_secret_scrub_post.rego
  Connectors: *

• Jira Scope Guard (post)
  File: jira_scope_guard_post.rego
  Connectors: jira

raia-cli policies test

Test policy parsing without uploading to the backend. Useful for validating your .rego files before syncing.

raia-cli policies test --repo REPO_URL [OPTIONS]

Required Arguments:

• --repo - Git repository URL

Optional Arguments:

• --branch - Git branch (default: main)
• --path - Path within repo (default: /raia/policies/)

Example:

raia-cli policies test --repo https://github.com/company/policies

Sample Output:

Testing policy parsing from https://github.com/company/policies
✅ Successfully parsed 5 policies:

• aws_safe_ops_pre.rego
  Path: aws/aws_safe_ops_pre.rego
  Phase: pre
  Connector: aws
  Size: 1247 characters

• generic_secret_scrub_post.rego
  Path: generic/generic_secret_scrub_post.rego
  Phase: post
  Connector: generic
  Size: 892 characters

Policy File Conventions

The CLI automatically detects policy metadata based on filename conventions:

Phase Detection

• Files ending with _pre.rego → pre-execution policies
• Files ending with _post.rego → post-execution policies
• Other files default to pre-execution

Connector Detection

• Files starting with connector name → applies to that connector
  • aws_*.rego → AWS connector
  • jira_*.rego → Jira connector
  • github_*.rego → GitHub connector
• Files starting with generic_ or universal_ → applies to all connectors (*)
• Other files default to all connectors (*)

Example Structure

/raia/policies/
├── aws/
│   ├── aws_safe_ops_pre.rego
│   └── aws_result_redaction_post.rego
├── jira/
│   └── jira_scope_guard_post.rego
└── generic/
    └── generic_secret_scrub_post.rego

Error Handling

Common errors and solutions:

Authentication Error:

Git error: fatal: Authentication failed

→ Set GITHUB_TOKEN for private repositories or check your SSH keys

No Policies Found:

Found 0 .rego files

→ Check the --path parameter and ensure .rego files exist in that directory

API Connection Error:

API error: Connection refused

→ Verify BACKEND_URL, TOKEN_NAME, and TOKEN_SECRET are correct

CI/CD Integration

For automated policy deployment in CI/CD pipelines:

# GitHub Actions example
name: Sync Policies

on:
  push:
    branches: [ rego ]
    paths: [ 'raia/policies/**/*.rego' ]
  workflow_dispatch:

jobs:
  sync:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v4
    
    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.11'
    
    - name: Install and sync policies
      env:
        BACKEND_URL: ${{ secrets.RAIA_BACKEND_URL }}
        TOKEN_NAME: ${{ secrets.RAIA_TOKEN_NAME }}
        TOKEN_SECRET: ${{ secrets.RAIA_TOKEN_SECRET }}
      run: |
        pip install git+https://github.com/raia-live/raia-cli.git
        raia-cli policies sync \
          --repo ${{ github.server_url }}/${{ github.repository }} \
          --branch ${{ github.ref_name }} \
          --path /raia/policies/ \
          --auto-assign