Skip to Content

Troubleshooting

TL;DR

CMDOP troubleshooting covers connection failures, authentication errors, performance bottlenecks, and self-hosted deployment issues. Run cmdop doctor for an all-in-one diagnostic check, cmdop status to verify agent health, or cmdop auth status to confirm authentication. Most issues resolve by restarting the agent, re-authenticating, or checking firewall rules for outbound port 443.

Quick guides for diagnosing and fixing common issues.

How do I run quick diagnostics?

How do I check agent status?

cmdop status

Expected output:

Agent: running (pid 12345)
Status: connected
Server: grpc.cmdop.com:443
Workspace: acme-corp
Uptime: 3 days, 2 hours

How do I check my connection?

cmdop auth status

How do I view agent logs?

# macOS/Linux
tail -f ~/.cmdop/agent.log
 
# Verbose mode
cmdop connect --debug

What are the common issues by category?

Connection Issues

  • Agent won’t connect
  • Connection drops frequently
  • Firewall blocking
  • Session stuck in GRACE_PERIOD

Authentication

  • Invalid API key
  • Token expired
  • Permission denied
  • OAuth failures

Performance

  • Slow command execution
  • File transfer speed
  • High latency
  • Memory issues

Self-Hosted

  • Database connection
  • Certificate errors
  • Upgrade failures
  • Redis issues

What are the quick fixes for common problems?

What do I do if the agent won’t start?

# Kill stale process
pkill -f "cmdop connect"
 
# Remove stale discovery file
rm -f ~/.cmdop/agent.info
 
# Restart
cmdop connect

How do I fix an expired token?

cmdop logout
cmdop login

How do I resolve permission denied errors?

# Check workspace
cmdop workspace current
 
# Switch if needed
cmdop workspace use <name>

What do I do when a session is not found?

Sessions close after 30-second grace period. Create new session:

cmdop terminal <hostname>

What diagnostic commands are available?

How do I run a full system check?

# All-in-one diagnostic
cmdop doctor

Output:

Checking agent... OK
Checking auth... OK
Checking network... OK
Checking server... OK
All checks passed!

How do I test network connectivity?

# Test gRPC connection
curl -v https://grpc.cmdop.com:443
 
# Test API
curl -H "Authorization: Bearer $CMDOP_API_KEY" \
  https://api.cmdop.com/v1/health

How do I enable debug mode?

# Agent with verbose logging
cmdop connect --debug
 
# CLI with verbose output
cmdop --debug machines

How do I get help?

What information should I collect when reporting issues?

When reporting issues, include:

  1. Agent version:

    cmdop version

  2. OS and version:

    uname -a

  3. Logs:

    tail -100 ~/.cmdop/agent.log

  4. Network info:

    curl -I https://api.cmdop.com/v1/health

What are the support channels?

Last updated on
Overview