Operations

Troubleshooting

Use this runbook to quickly isolate CLI, authentication, and hosted platform connectivity issues for external developers.

Time: 10 minAudience: Developers and support maintainers

Common failure patterns

SymptomMost likely causeFirst check

Not authenticatedMissing, expired, or revoked developer keyRun refactor whoami and re-login

CLI command fails immediatelyCLI missing or broken Python environmentCheck pip install and refactor --help

No runs appear in dashboardRepository not connected or integration misconfiguredReview project integrations in ReactorAI

Publish blockedGate failure or required approval missingCheck run details and policy settings

Account and authentication diagnostics

Auth and environment checks

refactor whoami
refactor doctor

CLI environment diagnostics

CLI installation and runtime checks

python -m pip show refactorai-cli
refactor --help

Hosted platform connectivity diagnostics

Network reachability checks

curl -I https://reactorai.codes

# If this fails:
# - check corporate proxy/VPN rules
# - verify TLS inspection policy
# - retry from an unrestricted network

If issues persist after these checks, capture your command output and account email, then contact support through the ReactorAI dashboard help channel.