RiskOS™ CLI

Overview

The RiskOS™ CLI is a command-line tool for working with your RiskOS™ account from the terminal. Use it to:

• Authenticate once and store credentials securely.
• Discover the use cases and workflows configured for your account.
• Download integration guides, OpenAPI specifications, and test-case payloads.
• List and simulate webhooks.
• Run sandbox test cases against the Evaluation API.

The CLI works both interactively on your workstation and non-interactively in CI pipelines and containers.

Quick start

Get from zero to your first command in under five minutes.

1. Install the CLI for your platform. See Install.

2. Authenticate with your API key:

   Bash

   riskos auth login

3. Verify the CLI is configured:

   Bash

   riskos auth status

4. List your use cases to confirm everything works end to end:

   Bash

   riskos usecase list

A list of use cases confirms that the CLI is installed, authenticated, and connected to your account. Each step appears in detail in the following sections.

Install

The RiskOS™ CLI is currently installed by building it from source. Pre-built release binaries are coming soon.

Prerequisites

• Go 1.22 or later
• Git
• Access to the socure-inc/riskos-cli repository

These steps cover macOS and Linux.

1. Clone the repository and build the CLI:

   git clone https://github.com/socure-inc/riskos-cli.git
   cd riskos-cli
   make build

The build produces the binary at build/riskos.

2. Move the binary onto your PATH:

   sudo mv build/riskos /usr/local/bin/riskos

3. Verify the installation:

   riskos --version

• To upgrade, pull the latest changes and repeat the build and move steps:

  cd riskos-cli
  git pull
  make build
  sudo mv build/riskos /usr/local/bin/riskos

• To remove the CLI, run:

  sudo rm /usr/local/bin/riskos

Authenticate

The CLI uses two separate Bearer tokens. Create both in the RiskOS™ Dashboard under Developer Workbench > API & SDK Keys.

You only need the Evaluation API key to run test cases. All other commands work with the CLI/MCP key alone.

Interactive login (recommended)

On a workstation with keychain support, run riskos auth login to authenticate. The CLI will:

1. Prompt for your CLI/MCP API key. Input is hidden as you type.
2. Prompt for your Evaluation API key (optional, Enter to skip). Press Enter to skip it if you don't run test cases.
3. Verify the keys against the RiskOS™ API.
4. Store the keys in the OS keychain on success — macOS Keychain, GNOME Keyring, or Windows Credential Manager.

riskos auth login

The interactive prompts look like this:

$ riskos auth login
  CLI/MCP API key:
  Evaluation API key (optional, Enter to skip):

Check your status

Confirm which credentials are active and where they come from:

riskos auth status

Example output:

✔  Authenticated
   Source            keyring
   Namespace         acc-0pILroyxbW
   Base URL          https://riskos.sandbox.socure.com
   Eval key          ✔ set

Log out

Remove stored credentials from the keychain — for example, on a shared or decommissioned machine:

riskos auth logout

CI and headless environments

For CI runners, automation, Docker, and headless servers where no keychain is available, skip auth login and provide your keys as environment variables instead:

export RISKOS_API_KEY="YOUR_CLI_MCP_KEY"
export RISKOS_EVAL_KEY="YOUR_EVAL_KEY"   # only needed for testcase run

riskos usecase list

Environment variables take precedence over keychain credentials, so all commands work without the keychain.

Verify the installation

Confirm the binary is installed and on your PATH:

riskos --version
# → riskos version v1.0.4

Then confirm you are authenticated with riskos auth status. If the version prints and the status shows Authenticated, you are ready to run commands.

Run your first command

List the use cases configured for your account:

riskos usecase list

Example output:

consumer_onboarding
business_onboarding
login_authentication

Seeing your use cases confirms that the CLI is installed, authenticated, and connected to the correct account. If the command returns nothing or an error, see Troubleshooting.

Common tasks

Each task introduces the command you need. All commands run against the base URL described in Configuration, defaulting to Sandbox.

List your use cases

riskos usecase list

Browse workflows for a use case

Pass the use-case identifier as an argument:

riskos workflow list consumer_onboarding

Download an integration guide

Export a use-case integration guide as Markdown:

riskos asset guide consumer_onboarding ./guide.md

Download API specifications

Export the RiskOS™ API and Webhooks OpenAPI specifications for client generation or validation:

riskos asset openapi ./openapi.json        # RiskOS API OpenAPI spec
riskos asset webhook-spec ./webhooks.json  # Webhooks OpenAPI spec

Download test-case payloads

Export the request payloads for a use case's sandbox test cases:

riskos asset testcases consumer_onboarding ./testcases.json

Run a sandbox test case

List the available sandbox personas for a use case, inspect a payload, then post a fixed test case to the Sandbox Evaluation API. testcase run requires the Evaluation key (RISKOS_EVAL_KEY).

list and describe are scoped to a use case and return persona names specific to your account. run posts one of a fixed set of global sandbox test cases and does not take a use-case argument.

riskos testcase list consumer_onboarding                     # list personas
riskos testcase describe consumer_onboarding <persona_name>  # show payload
riskos testcase run Valid_Consumer_Accept                    # post to Sandbox

Manage webhooks

List configured webhooks, view available event names, and simulate delivery to a local endpoint:

riskos webhook list                                # list configured webhooks
riskos webhook events                              # list available event names
riskos webhook simulate --target http://localhost:3000/webhooks/riskos

To create or update webhook endpoints from the CLI, see Set up webhooks.

Configuration

By default, the CLI targets the Sandbox environment (https://riskos.sandbox.socure.com). Point it at Production (https://riskos.socure.com) with the --base-url flag or the RISKOS_BASE_URL environment variable.

Global flags

These flags apply to every command.

Use -o json for machine-readable output in scripts:

riskos usecase list -o json

Environment variables

Troubleshooting

Use the following table to resolve common issues. To see the full HTTP exchange for any failing command, add the --debug flag.

Security

Use with an AI coding agent

The socure-inc/riskos-cli repository also includes an agent skill at skill/SKILL.md that guides a coding agent (such as Claude Code) through a complete RiskOS™ integration using the CLI — authenticating, discovering a live workflow, downloading the integration guide and OpenAPI spec, and validating the integration with sandbox test cases and simulated webhooks.

Prerequisites

• The riskos CLI installed and on your PATH. See Install.
• Authenticated via riskos auth login (or environment variables in CI). An Evaluation API key is required if you want the agent to run testcase run.

Enable the skill

Download skill/SKILL.md from the repository and place it where your agent tooling discovers skills. Consult your agent tooling's own documentation for the equivalent location .

Next steps

• Set up your account and send your first request in Integrating with RiskOS™.
• Configure real-time notifications in Webhooks.
• Explore the RiskOS™ API Reference for endpoint details.
• Give AI development tools live access to the same account data with the RiskOS™ MCP Server — an optional companion to the CLI.
• Automate a full integration walkthrough with an AI coding agent — see Use with an AI coding agent.