RunsOn CLI

The RunsOn CLI (roc) is a command line tool designed to help you manage and troubleshoot your RunsOn installation. It provides essential debugging and management capabilities for your self-hosted GitHub Actions runners.

Note: the CLI only works with RunsOn >= v2.6.3.

Installation

You can download the binaries for your platform (Linux, macOS) from the Releases ↗ page.

macOS (ARM64)

curl -Lo ./roc https://github.com/runs-on/cli/releases/download/v0.1.6/roc_0.1.6_darwin_arm64
chmod a+x ./roc
./roc --help

Linux (AMD64)

curl -Lo ./roc https://github.com/runs-on/cli/releases/download/v0.1.6/roc_0.1.6_linux_amd64
chmod a+x ./roc
./roc --help

Core Commands

roc connect

Connect to the instance running a specific job via SSM, by just pasting the GitHub Actions job URL or ID.

This feature requires the AWS Session Manager plugin ↗ to be installed on your local machine.

# Connect using job ID or URL
roc connect 12345678
roc connect https://github.com/owner/repo/actions/runs/123/job/456

# Connect with debug output
roc connect 12345678 --debug

# Wait for instance ID if not found
roc connect 12345678 --watch

Flags:

• --debug: Enable debug output
• --watch: Wait for instance ID if not found

Global Flags:

• --stack string: CloudFormation stack name (default “runs-on”)

roc logs

Fetch RunsOn server and instance logs for a specific job ID or URL. Use the --include flag to specify additional log types.

# Fetch logs for a specific job (default behavior)
roc logs 12345678
roc logs https://github.com/owner/repo/actions/runs/123/job/456

# Fetch all application logs for a run (all jobs in the run)
roc logs https://github.com/owner/repo/actions/runs/123/job/456 --include=run --watch

# Fetch EC2 instance console logs
roc logs 34661958899 --include=console

# Fetch both run logs and console logs
roc logs 34661958899 --include=run,console --watch

# Watch for new logs with custom interval
roc logs 12345678 --watch 2s --since 30m

Flags:

• -d, --debug: Enable debug output
• -f, --format string: Output format: long (default) or short
• --include strings: Include additional log types: ‘run’ (all logs from entire run), ‘console’ (EC2 instance console logs)
• --no-color: Disable color output
• -s, --since string: Show logs since duration (e.g. 30m, 2h) (default “2h”)
• -w, --watch string[="5s"]: Watch for new logs with optional interval (e.g. —watch 2s)

roc interrupt

Trigger a spot interruption on the instance running a specific job, simulating a spot instance interruption for testing purposes.

This command uses AWS Fault Injection Simulator (FIS) to send a spot interruption notification to the running instance.

# Trigger spot interruption
roc interrupt https://github.com/owner/repo/actions/runs/123/job/456

# Wait for instance if job hasn't started yet
roc interrupt 34661958899 --wait

# Custom delay before interruption (default is 5 seconds)
roc interrupt 34661958899 --delay 30s

Requirements:

• The target instance must be a running spot instance
• AWS FIS service must be available in your region

How it works:

1. Validates the instance is a running spot instance
2. Creates an IAM role for FIS if it doesn’t exist
3. Creates and starts a FIS experiment to send the interruption
4. Monitors the experiment progress
5. Automatically cleans up the experiment template when complete

Flags:

• --debug: Enable debug output
• --delay duration: Delay before interruption (e.g., 2m, 30s) (default 5s)
• -w, --wait: Wait for instance ID if not found

Stack Management

roc stack doctor

Diagnose RunsOn stack health and export troubleshooting information.

This command performs comprehensive health checks on your RunsOn CloudFormation stack:

• Verifies CloudFormation stack status
• Checks AppRunner service health and version
• Tests endpoint accessibility
• Validates service configuration
• Fetches application logs

Results are exported as a timestamped ZIP file containing checks.json and logs.

roc stack doctor

# Fetch logs for last 2 hours
roc stack doctor --since 2h

Flags:

• --since string: Fetch logs since duration (e.g. 30m, 2h, 24h) (default “24h”)

roc stack logs

Stream all RunsOn application logs from CloudWatch log streams.

This command streams all application logs from the RunsOn service, not filtered by specific jobs. Use this to monitor overall service activity and troubleshoot system-wide issues.

# Stream last 2 hours of application logs (default)
roc stack logs

# Stream last 24 hours of logs
roc stack logs --since 24h

# Stream logs with watch mode (refreshes every 5 seconds)
roc stack logs --watch

# Stream logs with custom watch interval
roc stack logs --watch 10s

# Stream logs in short format without color
roc stack logs --format short --no-color

Flags:

• -d, --debug: Enable debug output
• -f, --format string: Output format: long (default) or short
• --no-color: Disable color output
• -s, --since string: Show logs since duration (e.g. 30m, 2h) (default “2h”)
• -w, --watch string[="5s"]: Watch for new logs with optional interval (e.g. —watch 2s)

Use Cases

Debugging Job Failures

When a GitHub Actions job fails on your RunsOn infrastructure:

1. Get logs: Use roc logs JOB_ID to fetch detailed logs
2. Connect to instance: Use roc connect JOB_ID to SSH into the runner
3. Check stack health: Run roc stack doctor to ensure infrastructure is healthy
4. Test interruption handling: Use roc interrupt JOB_ID to simulate spot interruptions

Real-time Monitoring

# Monitor logs in real-time for active jobs
roc logs JOB_ID --watch

# Monitor all application logs
roc stack logs --watch

Health Checks

# Regular stack health verification
roc stack doctor

# Stream application logs for monitoring
roc stack logs --since 1h

Troubleshooting

Connection Issues

If roc connect fails:

• Ensure AWS Session Manager plugin is installed
• Verify your AWS credentials have appropriate permissions to access the RunsOn stack
• Check that you are targeting the correct stack (--stack flag) and region (AWS profile or AWS_REGION environment variable)
• Use --debug flag for detailed error information

Log Access Issues

If roc logs returns no results:

• Verify the job ID or URL is correct
• Check your AWS credentials and permissions
• Check that you are targeting the correct stack (--stack flag) and region (AWS profile or AWS_REGION environment variable)
• Try adjusting the --since timeframe

Interruption Testing Issues

If roc interrupt fails:

• Ensure the target instance is a running spot instance
• Verify AWS FIS service is available in your region
• Check that your AWS credentials have appropriate FIS permissions
• Use --debug flag for detailed error information

Support

For issues with the RunsOn CLI:

• Open an issue on GitHub ↗
• Contact support at [email protected]
• Include output from roc stack doctor when reporting problems

License

The RunsOn CLI is open source software licensed under the MIT License.