CLI Troubleshooting

Common issues and solutions when using OptixLog CLI.

Installation Issues

Command Not Found

Symptoms:

$ optixlog --help
zsh: command not found: optixlog

Solutions:

1. Check if installed:

   npm list -g optixlog-cli

2. Re-link (if development install):

   cd /path/to/optixlog-cli
   npm link

3. Check PATH:

   echo $PATH  # Linux/macOS
   echo %PATH%  # Windows

4. Install globally:

   npm install -g optixlog-cli

Permission Denied

Symptoms:

$ optixlog --version
Permission denied

Solutions:

1. Make executable:

   chmod +x optixlog

2. Use sudo (if needed):

   sudo chmod +x /usr/local/bin/optixlog

3. Check file permissions:

   ls -l $(which optixlog)

Configuration Issues

Config File Not Found

Symptoms:

$ optixlog config
No configuration found

Solutions:

1. Initialize config:

   optixlog init --project "MyProject" --api-key "proj_xxx"

2. Check config location:

   # Local config
   ls -la .optixlog.json
   
   # Global config
   ls -la ~/.optixlog.json

3. Create manually:

   {
     "api_key": "proj_your_key",
     "api_url": "https://optixlog.com",
     "project": "MyProject"
   }

API Key Not Working

Symptoms:

$ optixlog runs
✗ No API key configured

Solutions:

1. Set API key:

   optixlog config set api_key "proj_YOUR_KEY"

2. Check config:

   optixlog config get api_key

3. Verify key format:

   # Should start with "proj_"
   optixlog config get api_key | grep "^proj_"

4. Use environment variable:

   export OPTIX_API_KEY="proj_your_key"

SDK Issues

SDK Not Found

Symptoms:

$ optixlog add-logging script.py
⚠  OptixLog SDK not found in Python environment

Solutions:

1. Check SDK:

   optixlog check-sdk

2. Install SDK:

   optixlog install-sdk

3. Manual install:

   pip install optixlog

4. Check Python:

   python --version
   which python

Wrong Python Environment

Symptoms: SDK installed but CLI can't find it

Solutions:

1. Check which Python:

   which python
   python --version

2. Use specific Python:

   /path/to/python -m pip install optixlog

3. Virtual environment:

   source venv/bin/activate  # Linux/macOS
   venv\Scripts\activate  # Windows
   pip install optixlog

Transformation Issues

File Not Found

Symptoms:

$ optixlog add-logging script.py
✗ File not found: script.py

Solutions:

1. Check file exists:

   ls -la script.py

2. Use absolute path:

   optixlog add-logging /full/path/to/script.py

3. Check file extension:

   # Only .py and .ipynb supported
   optixlog add-logging script.py
   optixlog add-logging notebook.ipynb

Transformation Failed

Symptoms:

$ optixlog add-logging script.py
✗ Transformation failed

Solutions:

1. Check file syntax:

   python -m py_compile script.py

2. Try smart mode:

   optixlog add-logging script.py --smart

3. Check backend connection:

   # Smart mode doesn't need backend
   optixlog add-logging script.py --smart

4. Check file encoding:

   file script.py  # Should be UTF-8

Backup Not Created

Symptoms: No backup file after transformation

Solutions:

1. Check if backup exists:

   ls -la *_backup.py

2. Backup is created by default (unless --no-backup used)

3. Restore from backup:

   cp script_backup.py script.py

Platform-Specific Issues

macOS Security

Symptoms: Binary blocked by Gatekeeper

Solutions:

1. Allow in System Preferences:

   • System Preferences → Security & Privacy
   • Click "Open Anyway"

2. Remove quarantine:

   xattr -d com.apple.quarantine optixlog

Windows Path Issues

Symptoms: Path not found errors

Solutions:

1. Use forward slashes or double backslashes:

   optixlog add-logging C:/path/to/script.py
   # or
   optixlog add-logging C:\\path\\to\\script.py

2. Check path length (Windows has 260 char limit)

3. Use relative paths:

   cd C:\path\to
   optixlog add-logging script.py

Linux Permission Issues

Symptoms: Permission denied errors

Solutions:

1. Check file permissions:

   ls -l script.py
   chmod +r script.py  # Make readable

2. Check directory permissions:

   ls -ld .
   chmod +w .  # Make writable (for backup)

Network Issues

Backend Connection Failed

Symptoms:

$ optixlog runs
✗ Failed to fetch runs
Cannot connect to server

Solutions:

1. Check internet connection:

   ping optixlog.com

2. Check API URL:

   optixlog config get api_url

3. Use smart mode (doesn't need backend):

   optixlog add-logging script.py --smart

4. Check firewall/proxy:

   • Ensure port 443 (HTTPS) is open
   • Configure proxy if needed

Common Error Messages

"Invalid API key"

Cause: API key is incorrect or expired

Solutions:

1. Get new key from https://optixlog.com
2. Update config: optixlog config set api_key "proj_NEW_KEY"
3. Verify key format (should start with proj_)

"Project not found"

Cause: Project doesn't exist

Solutions:

1. Use create_project_if_not_exists=True in code
2. Create project via web UI
3. List projects: optixlog runs (shows available projects)

"SDK installation failed"

Cause: pip install failed

Solutions:

1. Check Python version: python --version (need 3.8+)
2. Update pip: pip install --upgrade pip
3. Install manually: pip install optixlog
4. Check pip permissions

Getting Help

If you encounter an issue not covered here:

1. Check CLI version:

   optixlog --version

2. Check SDK version:

   optixlog check-sdk

3. Update CLI:

   npm install -g optixlog-cli@latest

4. Update SDK:

   optixlog install-sdk
   # or
   pip install --upgrade optixlog

5. Report the issue with:

   • CLI version
   • SDK version
   • Python version
   • Node.js version
   • Error message
   • Steps to reproduce

Next Steps

• Advanced Usage
• Commands Reference
• Examples