Metadata-Version: 2.4
Name: roboticks-cli
Version: 0.3.0
Summary: Roboticks CLI - Verify ROS2 robots against requirements from the command line
Project-URL: Homepage, https://roboticks.io
Project-URL: Documentation, https://docs.roboticks.io/cli
Project-URL: Repository, https://github.com/roboticks/roboticks-cli
Author-email: Roboticks <support@roboticks.io>
License-Expression: MIT
Keywords: cli,requirements,robotics,ros2,traceability,validation,verification
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: keyring>=25.7.0
Requires-Dist: packaging>=25.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: rich>=14.2.0
Requires-Dist: sentry-sdk>=2.48.0
Requires-Dist: websockets>=15.0.1
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.15.0; extra == 'dev'
Requires-Dist: pytest>=9.0.2; extra == 'dev'
Requires-Dist: respx>=0.22.0; extra == 'dev'
Requires-Dist: ruff>=0.14.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
Provides-Extra: local-tests
Requires-Dist: roboticks>=0.1.0; extra == 'local-tests'
Description-Content-Type: text/markdown

# 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

```bash
# 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

```bash
# 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

```bash
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:

```yaml
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
```bash
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
```bash
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
```bash
rbtk org list
rbtk org get [SLUG]
rbtk org limits
rbtk project list
rbtk project get [SLUG]
```

### Tests
```bash
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
```bash
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
```bash
rbtk github link <owner/repo> [--project PROJECT]
rbtk github status
```

### Runner Pools
```bash
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
```bash
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
```bash
rbtk completion bash >> ~/.bashrc
rbtk completion install
```

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `ROBOTICKS_API_KEY` | API key for authentication | - |
| `ROBOTICKS_ORG` | Default organization slug | - |
| `ROBOTICKS_PROJECT` | Default project slug | - |
| `ROBOTICKS_API_URL` | API base URL | `https://api.roboticks.io` |
| `ROBOTICKS_OUTPUT` | Output format (table/json/yaml/ids) | `table` |
| `ROBOTICKS_NO_INTERACTIVE` | Disable interactive prompts | `false` |
| `ROBOTICKS_DEBUG` | Enable debug output | `false` |
| `NO_COLOR` | Disable colored output | - |

## Output Formats

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

## Configuration Files

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

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

## Development

```bash
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.
