Roboticks CLI

Command-line interface for the Roboticks ROS2 verification & validation platform. Drive local pytest runs, trigger cloud test runs, manage requirements, link GitHub repositories, and pull evidence packs — from the same shell you write tests in.

Installation

# Using pip
pip install roboticks-cli

# Using pipx (recommended for isolated install)
pipx install roboticks-cli

# With the local-test SDK (drives @confirms-decorated pytest)
pip install "roboticks-cli[local-tests]"

# From source
pip install -e ".[dev]"

Quick Start

# Login (opens browser)
rbtk login

# Set the org/project context once
rbtk context set --org acme --project warehouse

# Link a GitHub repo to this project (uses the Roboticks GitHub App)
rbtk github link acme/perception

# Upload requirements (ReqIF, PDF, YAML — auto-detected)
rbtk requirements upload ./safety-requirements.reqif

# Run tests locally with traceability
rbtk test run --package ./src/perception_tests

# Run the same tests on a Roboticks cloud runner
rbtk test cloud --branch main --watch

# Inspect results + grab the evidence pack
rbtk test results <test-run-id>
rbtk test evidence-pack <test-run-id> --format pdf -o evidence.pdf

CI/CD Usage

export ROBOTICKS_API_KEY=rbtk_xxx
export ROBOTICKS_ORG=acme
export ROBOTICKS_PROJECT=warehouse

rbtk test cloud --commit "$GITHUB_SHA" --branch "$GITHUB_REF_NAME" --watch

Inside GitHub Actions, use OIDC instead of long-lived API keys:

permissions:
  id-token: write
steps:
  - uses: actions/checkout@v4
  - run: pip install roboticks-cli
  - run: rbtk auth oidc-from-github
  - run: rbtk test cloud --watch

rbtk auth oidc-from-github exchanges the GitHub Actions OIDC token for a short-lived Roboticks token and stores it in the keyring for the run.

Commands

Authentication

rbtk login                       # Login via browser
rbtk logout                      # Clear credentials
rbtk auth status                 # Check auth status
rbtk auth whoami                 # Same as auth status
rbtk auth oidc-from-github       # Exchange GitHub Actions OIDC token (CI only)

Context

rbtk context                                # Show current context
rbtk context set --org acme --project robots
rbtk context list                           # List available orgs/projects
rbtk context clear                          # Clear saved context

Organizations / Projects

rbtk org list
rbtk org get [SLUG]
rbtk org limits
rbtk project list
rbtk project get [SLUG]

Tests

rbtk test run [--package PATH] [--filter PATTERN]    # Local pytest/colcon run
rbtk test cloud [--branch BRANCH] [--commit SHA] [--watch]
rbtk test list [--limit N] [--status STATUS]
rbtk test results <test-run-id>
rbtk test logs <test-run-id> [--follow]
rbtk test artifacts <test-run-id> [--download PATH]
rbtk test evidence-pack <test-run-id> [--format pdf|reqif|zip] [-o FILE]

Requirements

rbtk requirements upload <file.reqif | file.pdf | file.yaml>
rbtk requirements list [--type safety] [--gap-only]
rbtk requirements show <REQ-ID>
rbtk requirements coverage
rbtk requirements export --format reqif -o requirements.reqif

GitHub Integration

rbtk github link <owner/repo> [--project PROJECT]
rbtk github status

Runner Pools

rbtk runner-pool list
rbtk runner-pool create --type self-hosted --name lab-gpus \
    --flavors ros2_test,gazebo
rbtk runner-pool register-runner --pool lab-gpus
rbtk runner-pool runners <pool>
rbtk runner-pool delete <pool>

Logs

rbtk log list --test-run <id> --level error
rbtk log list --ros-node /perception_node
rbtk log stream --test-run <id>
rbtk log export --test-run <id> --since 24h -o logs.json

Shell Completions

rbtk completion bash >> ~/.bashrc
rbtk completion install

Environment Variables

Output Formats

rbtk test list --output json
rbtk requirements coverage --output yaml
rbtk runner-pool list --output ids

Configuration Files

User Config

# ~/.config/roboticks/config.yaml
version: 1
context:
  organization: acme
  project: warehouse
api:
  base_url: https://api.roboticks.io
output:
  format: table

Project Config

# .roboticks.yaml (in repo root)
organization: acme
project: warehouse
defaults:
  test:
    package: src/perception_tests

Development

python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

pytest                                  # 90% coverage enforced
ruff check src/ tests/
ruff format --check src/ tests/
mypy src/

Releases

Tag a version on the main branch — CI publishes to PyPI via the publish.yml workflow. 0.2.0aN tags publish to TestPyPI; 0.2.0 and above publish to PyPI.