CLI Issues

This page covers common issues with the OpsSquad CLI tool and agent management.

Installation Issues

Installation Script Fails

Symptoms: The curl | bash installation fails with an error.

Solutions:

1. Check internet connectivity:

   curl -I https://install.opssquad.ai

   If this fails, check your network/proxy settings.

2. Try manual installation: Download the binary directly for your platform from the releases page.

3. Check disk space:

   df -h /usr/local/bin

   Ensure at least 50MB is available.

Permission Denied During Installation

Symptoms: "Permission denied" when installing to /usr/local/bin.

Solutions:

Option 1: Use sudo

curl -fsSL https://install.opssquad.ai/install.sh | sudo bash

Option 2: User Installation

mkdir -p ~/.local/bin
# Download and extract to ~/.local/bin
export PATH="$HOME/.local/bin:$PATH"

Command Not Found After Installation

Symptoms: opssquad: command not found after installation.

Solutions:

1. Restart your terminal or run:

   source ~/.bashrc  # or ~/.zshrc

2. Check PATH includes installation directory:

   echo $PATH | grep -E "(local/bin|\.local/bin)"

3. Add to PATH if missing:

   echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc

Agent Won't Start

Symptoms: opssquad agent start completes but agent shows as stopped.

Diagnostic Steps:

1. Run validation:

   opssquad agent validate

   This identifies specific issues.

2. Check logs for errors:

   opssquad agent logs --lines=50

   Look for ERROR or FATAL messages.

3. Verify configuration exists:

   # System installation
   cat /etc/opssquad/agent.yaml
   
   # User installation
   cat ~/.config/opssquad/agent.yaml

4. Check agent binary exists:

   # System installation
   ls -la /usr/local/lib/opssquad/
   
   # User installation
   ls -la ~/.local/lib/opssquad/

Connectivity Problems

Symptoms: Agent starts but shows "Disconnected" or connection errors.

Check Network Access

# Test TCP connectivity
nc -zv socket.opssquad.ai 9000

# Alternative using curl
curl -v telnet://socket.opssquad.ai:9000

# Check DNS resolution
nslookup socket.opssquad.ai

Firewall Configuration

Ensure outbound TCP on port 9000 is allowed:

UFW (Ubuntu):

# Check status
sudo ufw status

# Allow outbound (usually allowed by default)
sudo ufw allow out 9000/tcp

firewalld (RHEL/CentOS):

# Check status
sudo firewall-cmd --list-all

# Allow outbound
sudo firewall-cmd --permanent --add-port=9000/tcp
sudo firewall-cmd --reload

iptables:

# Check existing rules
sudo iptables -L -n | grep 9000

# Allow outbound
sudo iptables -A OUTPUT -p tcp --dport 9000 -j ACCEPT

Proxy Issues

If behind a corporate proxy:

# The agent's TCP connection doesn't work through HTTP proxies
# You need direct TCP access to socket.opssquad.ai:9000

# Temporarily disable proxy to test
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY
opssquad agent restart

Warning: OpsSquad agents require direct TCP access. HTTP proxies are not supported for the main connection.

Permission Errors

System Installation (Root)

If you installed with sudo, always use sudo for commands:

sudo opssquad agent status
sudo opssquad agent start
sudo opssquad agent logs

Fix permissions if needed:

sudo chown -R root:root /etc/opssquad/
sudo chmod 600 /etc/opssquad/agent.yaml

User Installation

If installed without root, never use sudo:

# Correct
opssquad agent status

# WRONG - will cause permission conflicts
sudo opssquad agent status

Fix permissions:

chmod 600 ~/.config/opssquad/agent.yaml

Configuration Issues

Invalid Configuration

Symptoms: Validation fails with "invalid configuration".

Check YAML syntax:

# Install yamllint
pip install yamllint

# Validate config
yamllint /etc/opssquad/agent.yaml

Common YAML issues:

• Tabs instead of spaces
• Missing quotes around special characters
• Incorrect indentation

Missing Credentials

Symptoms: "agent_id or api_key missing".

Verify configuration:

app:
  agent_id: "your-agent-id"    # Required
  api_key: "your-api-key"      # Required

Regenerate Configuration

If config is corrupted, reinstall:

opssquad agent uninstall --force
opssquad agent install --agent-id="your-id" --api-key="your-key"

macOS Specific Issues

Developer Cannot Be Verified

Symptoms: "opssquad cannot be opened because the developer cannot be verified"

Solutions:

Using System Preferences:

1. Open System Settings > Privacy & Security
2. Scroll down to find the blocked app message
3. Click "Open Anyway"

Using Command Line:

# Remove quarantine attribute
sudo xattr -d com.apple.quarantine /usr/local/bin/opssquad
sudo xattr -d com.apple.quarantine /usr/local/lib/opssquad/*

Permission Issues on macOS

macOS may require explicit permissions:

# Grant execute permission
chmod +x /usr/local/bin/opssquad
chmod +x /usr/local/lib/opssquad/opssquad-connectivity-layer

Service Issues (Linux)

Service Not Starting on Boot

Check if enabled:

sudo systemctl is-enabled opssquad-connectivity-layer

Enable it:

sudo systemctl enable opssquad-connectivity-layer

View Service Status

sudo systemctl status opssquad-connectivity-layer

View Service Logs

sudo journalctl -u opssquad-connectivity-layer -f

Restart Service

sudo systemctl restart opssquad-connectivity-layer

Agent Keeps Disconnecting

Symptoms: Frequent reconnection messages in logs.

Possible Causes:

1. Unstable network:

   ping -c 20 socket.opssquad.ai

   Look for packet loss or high latency.

2. Firewall killing idle connections: Some firewalls terminate idle TCP connections. Contact your network administrator.

3. Resource exhaustion:

   top -bn1 | head -20
   free -h

   Check CPU and memory usage.

4. Agent crashing:

   opssquad agent logs | grep -i "error\|panic\|fatal"

Upgrade Issues

Upgrade Command Fails

# Check current version
opssquad --version

# Try manual upgrade
curl -fsSL https://install.opssquad.ai/install.sh | bash

Agent Version Mismatch

After CLI upgrade, update the agent:

opssquad agent stop
opssquad agent upgrade
opssquad agent start

Getting More Help

If these solutions don't resolve your issue:

1. Run full diagnostics:

   opssquad agent validate > diagnostics.txt
   opssquad agent logs --lines=200 >> diagnostics.txt

2. Contact support with:

   • The diagnostics.txt file
   • Your OS: uname -a
   • Steps to reproduce

Support channels:

• Email: [email protected]
• Discord: discord.gg/opssquad
• GitHub: Issues