Plugin System¶

RAPS CLI supports a plugin system for extending functionality with external commands, workflow hooks, and command aliases.

Overview¶

The plugin system provides three extension mechanisms:

External Command Plugins: Executables that extend RAPS with new commands
Workflow Hooks: Pre/post command hooks for automation
Command Aliases: Shortcuts for frequently used command patterns

External Command Plugins¶

Plugin Discovery¶

RAPS automatically discovers plugins by searching your system PATH for executables matching the pattern:

Windows: raps-<name>.exe
macOS/Linux: raps-<name>

For example, if you have an executable named raps-report in your PATH, you can invoke it as:

raps report [arguments]

Creating a Plugin¶

A plugin can be written in any language. It receives command-line arguments directly.

Example: Simple Bash Plugin

#!/bin/bash
# Save as: raps-hello (make executable with chmod +x)

echo "Hello from RAPS plugin!"
echo "Arguments: $@"

Example: Python Plugin

#!/usr/bin/env python3
# Save as: raps-stats

import sys
import json

def main():
    print("RAPS Statistics Plugin")
    # Your plugin logic here

if __name__ == "__main__":
    main()

Plugin Best Practices¶

Exit Codes: Use standard exit codes (0 for success, non-zero for errors)
Output Format: Support --output json for machine-readable output
Help Text: Implement --help for usage information
Error Handling: Print errors to stderr, not stdout

Configuration File¶

Plugins and hooks are configured in ~/.config/raps/plugins.json (Linux/macOS) or %APPDATA%\raps\plugins.json (Windows).

Configuration Structure¶

{
  "plugins": {
    "my-plugin": {
      "enabled": true,
      "path": "/path/to/raps-my-plugin",
      "description": "My custom plugin"
    }
  },
  "hooks": {
    "pre_upload": ["echo 'Starting upload...'"],
    "post_translate": ["notify-send 'Translation complete'"]
  },
  "aliases": {
    "quick-upload": "object upload --resume",
    "dev-bucket": "bucket list --output json"
  }
}

Plugin Entry Fields¶

Field	Type	Description
`enabled`	boolean	Whether the plugin is active (default: true)
`path`	string	Optional explicit path to the plugin executable
`description`	string	Optional description for `raps plugin list`

Workflow Hooks¶

Hooks allow you to run commands before or after RAPS operations.

Hook Names¶

Hooks follow the pattern pre_<command> or post_<command>:

Hook	Triggered
`pre_upload`	Before any upload operation
`post_upload`	After successful upload
`pre_translate`	Before starting translation
`post_translate`	After translation completes
`pre_login`	Before authentication
`post_login`	After successful login

Hook Examples¶

Notification on Translation Complete

{
  "hooks": {
    "post_translate": [
      "notify-send 'RAPS' 'Translation finished!'",
      "echo 'Translation completed at $(date)' >> ~/raps.log"
    ]
  }
}

Validation Before Upload

{
  "hooks": {
    "pre_upload": [
      "echo 'Validating file...'",
      "/path/to/validate-script.sh"
    ]
  }
}

Hook Behavior¶

Hooks run in order defined in the array
Hook failures are logged but don't stop the main command
Hooks receive no arguments (use environment variables for context)
On Windows, hooks run via cmd /C; on Unix, via sh -c

Command Aliases¶

Aliases provide shortcuts for common command patterns.

Defining Aliases¶

{
  "aliases": {
    "up": "object upload --resume",
    "ls": "bucket list --output table",
    "translate-svf": "translate start --format svf2 --wait"
  }
}

Using Aliases¶

# Instead of:
raps object upload --resume mybucket file.dwg

# Use:
raps up mybucket file.dwg

Alias with Variables¶

Aliases support argument passing:

# Alias: "quick-translate": "translate start --format svf2"
raps quick-translate urn:adsk:... --wait
# Expands to: raps translate start --format svf2 urn:adsk:... --wait

Plugin Management Commands¶

List Plugins¶

# List all discovered and configured plugins
raps plugin list

Output:

Discovered Plugins:
  raps-report    /usr/local/bin/raps-report    ✓ enabled
  raps-stats     /usr/local/bin/raps-stats     ✓ enabled
  raps-export    /home/user/bin/raps-export    ✗ disabled

Enable/Disable Plugins¶

# Disable a plugin
raps plugin disable export

# Enable a plugin
raps plugin enable export

List Aliases¶

# Show all configured aliases
raps alias list

Security Considerations¶

Plugin Security¶

Trust: Only install plugins from trusted sources
Permissions: Plugins run with your user permissions
PATH Security: Ensure your PATH doesn't include untrusted directories
Review Code: Inspect plugin source before installation

Hook Security¶

Command Injection: Be careful with dynamic content in hooks
Sensitive Data: Don't log credentials in hook scripts
Error Handling: Hook failures are logged; don't expose secrets in error messages

Best Practices¶

{
  "hooks": {
    "pre_upload": [
      "/path/to/vetted-script.sh"
    ]
  }
}

Prefer calling dedicated scripts over inline shell commands for better security auditing.

Troubleshooting¶

Plugin Not Found¶

Verify the plugin is in your PATH: which raps-pluginname
Check file permissions (must be executable)
On Windows, ensure .exe extension

Hooks Not Running¶

Check hook names match the pattern pre_<command> or post_<command>
Verify plugins.json is valid JSON
Run with --debug to see hook execution logs

Debug Mode¶

# See detailed plugin/hook execution
raps --debug plugin list
raps --debug object upload mybucket file.dwg

Examples¶

Complete Configuration¶

{
  "plugins": {
    "report": {
      "enabled": true,
      "description": "Generate project reports"
    },
    "backup": {
      "enabled": true,
      "path": "/opt/raps-plugins/raps-backup",
      "description": "Backup bucket contents"
    }
  },
  "hooks": {
    "pre_upload": [
      "echo 'Upload starting...'"
    ],
    "post_upload": [
      "echo 'Upload complete!'",
      "/usr/local/bin/notify-team.sh"
    ],
    "post_translate": [
      "curl -X POST https://webhook.site/xxx -d 'Translation done'"
    ]
  },
  "aliases": {
    "up": "object upload --resume",
    "down": "object download",
    "trans": "translate start --format svf2",
    "status": "translate status --wait"
  }
}

CI/CD Integration¶

{
  "hooks": {
    "post_translate": [
      "echo '::set-output name=status::complete'"
    ]
  },
  "aliases": {
    "ci-upload": "object upload --non-interactive --output json",
    "ci-translate": "translate start --non-interactive --output json --wait"
  }
}