Skip to main content

cli

CLI Reference

The IOA Command Line Interface provides comprehensive tools for managing AI governance and compliance.

Installation​

pip install ioa-core

Global Options​

All commands support these global options:

--verbose, -v          Increase verbosity
--quiet, -q            Suppress output
--config FILE          Use specific config file
--help, -h             Show help message

Core Commands​

ioa init​

Initialize a new IOA project.

ioa init [PROJECT_NAME] [OPTIONS]

Options:

  • --template TEMPLATE - Use specific project template
  • --cartridge CARTRIDGE - Pre-install cartridges
  • --force - Overwrite existing project

Examples:

# Basic initialization
ioa init my-ai-project

# With GDPR cartridge
ioa init my-project --cartridge gdpr

# Using template
ioa init my-project --template enterprise

ioa cartridge​

Manage compliance cartridges.

ioa cartridge <COMMAND> [OPTIONS]

Subcommands:

  • add CARTRIDGE - Install a cartridge
  • remove CARTRIDGE - Remove a cartridge
  • list - List installed cartridges
  • update - Update all cartridges
  • info CARTRIDGE - Show cartridge information

Examples:

# List available cartridges
ioa cartridge list

# Install GDPR cartridge
ioa cartridge add gdpr

# Update all cartridges
ioa cartridge update

ioa score​

Calculate assurance score for a system.

ioa score [OPTIONS] [INPUT_FILE]

Options:

  • --format FORMAT - Output format (json, yaml, table)
  • --output FILE - Save output to file
  • --threshold SCORE - Set minimum score threshold
  • --verbose - Show detailed scoring breakdown

Examples:

# Score from file
ioa score --format json system-config.json

# Score with threshold
ioa score --threshold 0.8 --verbose

# Save to file
ioa score --output score-report.json

ioa report​

Generate compliance reports.

ioa report [OPTIONS] [OUTPUT_FILE]

Options:

  • --format FORMAT - Report format (pdf, html, json)
  • --template TEMPLATE - Use specific template
  • --include INCLUDE - Include specific sections
  • --exclude EXCLUDE - Exclude specific sections

Examples:

# Generate PDF report
ioa report --format pdf compliance-report.pdf

# HTML report with specific sections
ioa report --format html --include gdpr,security

ioa test​

Run test harness for validation.

ioa test [OPTIONS] [TEST_PATTERN]

Options:

  • --suite SUITE - Run specific test suite
  • --parallel N - Run tests in parallel
  • --coverage - Generate coverage report
  • --verbose - Show detailed test output

Examples:

# Run all tests
ioa test

# Run specific test suite
ioa test --suite compliance

# Generate coverage report
ioa test --coverage --verbose

ioa scan​

Perform security and compliance scanning.

ioa scan [OPTIONS] [TARGET]

Options:

  • --type TYPE - Scan type (security, compliance, performance)
  • --output FORMAT - Output format (json, yaml, table)
  • --fix - Automatically fix issues where possible
  • --exclude PATTERN - Exclude files matching pattern

Examples:

# Security scan
ioa scan --type security

# Compliance scan with auto-fix
ioa scan --type compliance --fix

# Scan specific directory
ioa scan ./src --type security

Configuration​

Config File​

IOA uses a configuration file (ioa.yaml) for project settings:

project:
  name: "my-ai-project"
  version: "1.0.0"
  description: "AI governance project"

cartridges:
  - gdpr
  - security

scoring:
  threshold: 0.8
  components:
    transparency: 0.25
    security: 0.20
    compliance: 0.20
    reliability: 0.15
    ethics: 0.10
    sustainability: 0.10

reporting:
  format: "pdf"
  template: "default"
  output_dir: "./reports"

Environment Variables​

  • IOA_CONFIG_FILE - Path to config file
  • IOA_LOG_LEVEL - Logging level (DEBUG, INFO, WARNING, ERROR)
  • IOA_CACHE_DIR - Cache directory path
  • IOA_API_URL - API endpoint URL

Examples​

Complete Workflow​

# 1. Initialize project
ioa init my-ai-project --cartridge gdpr

# 2. Navigate to project
cd my-ai-project

# 3. Add more cartridges
ioa cartridge add security
ioa cartridge add performance

# 4. Run tests
ioa test --coverage

# 5. Perform security scan
ioa scan --type security --fix

# 6. Calculate assurance score
ioa score --verbose

# 7. Generate compliance report
ioa report --format pdf --include gdpr,security

CI/CD Integration​

# In your CI pipeline
ioa test --suite integration
ioa scan --type security --output json security-report.json
ioa score --threshold 0.8 --format json score.json

# Fail if score below threshold
if [ $(jq '.score' score.json) -lt 0.8 ]; then
  echo "Assurance score below threshold"
  exit 1
fi

Troubleshooting​

Common Issues​

Command not found:

# Ensure IOA is in PATH
export PATH="$HOME/.local/bin:$PATH"

Permission denied:

# Install with user flag
pip install --user ioa-core

Config file not found:

# Initialize project first
ioa init my-project

Debug Mode​

Enable debug logging for troubleshooting:

export IOA_LOG_LEVEL=DEBUG
ioa --verbose <command>

Getting Help​

  • ioa --help - Show general help
  • ioa <command> --help - Show command-specific help
  • GitHub Issues - Report bugs
  • Documentation - Full documentation