Troubleshooting

Common issues, error messages, and solutions for the Ellygent CLI.

Quick Diagnostic

Run these commands to gather diagnostic information:

# Check CLI version
ellygent --version

# Check Node.js version
node --version

# View current configuration
ellygent config

# Test API connectivity
curl https://api.ellygent.com/health

# Check environment variables
env | grep ELLYGENT

Common Issues & Solutions

Symptoms:

Error: 401 Unauthorized or Login failed

Common Causes:

Incorrect email or password
Invalid or expired Personal Access Token
Wrong API URL

Solutions:

1. Verify credentials

# Check your email and password
# Or verify PAT starts with elly_pat_

2. Check API URL

ellygent config
# Verify api-url is correct

3. Regenerate PAT

# Go to Account → Personal Access Tokens in web UI
# Revoke old token and create a new one

4. Test login interactively

ellygent auth login
# Follow prompts to verify credentials work

Symptoms:

ellygent: command not found or 'ellygent' is not recognized

Common Causes:

CLI not installed globally
npm global bin directory not in PATH
Node.js not installed or outdated

Solutions:

1. Install CLI globally

npm install -g @ellygent/cli

2. Verify installation

npm list -g @ellygent/cli

3. Check PATH (Unix/macOS)

echo $PATH
npm config get prefix
# Ensure npm global bin is in PATH

4. Check PATH (Windows)

echo %PATH%
npm config get prefix
# Add npm global path to system PATH

Symptoms:

ECONNREFUSED, ETIMEDOUT, or Unable to reach API

Common Causes:

Firewall or proxy blocking connections
Incorrect API URL
API service is down

Solutions:

1. Check API URL

ellygent config
# Verify api-url is correct and accessible

2. Test connectivity

curl https://api.ellygent.com/health
# Should return 200 OK

3. Configure proxy (if needed)

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

4. Check firewall

# Ensure outbound HTTPS (443) is allowed
# Contact IT if behind corporate firewall

Symptoms:

EACCES: permission denied or Access denied writing config

Common Causes:

Insufficient file system permissions
Config directory not writable
npm global install requires sudo

Solutions:

1. Fix npm permissions (recommended)

# Configure npm to use a directory in your home folder
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

2. Install with user permissions

npm install -g @ellygent/cli --unsafe-perm

3. Check config directory permissions

ls -la ~/.ellygent/
# Should be owned by your user
chmod 755 ~/.ellygent/
chmod 600 ~/.ellygent/config.json

Symptoms:

Sync command fails, ZIP extraction errors, or missing files

Common Causes:

Network interruption during download
Insufficient disk space
Corrupt ZIP package
Project or version not found

Solutions:

1. Verify project and version exist

ellygent context projects --org <org-name>
ellygent context versions --project <project-id>

2. Check disk space

df -h .  # Unix/macOS
# Ensure sufficient free space

3. Retry sync

ellygent context pull --project <project-id> --version <version>

4. Clean and retry

rm -rf .ellygent/
ellygent context pull --project <project-id> --version <version>

Symptoms:

Unexpected token, invalid JSON, or parse errors

Common Causes:

Mixing output formats
Piping non-JSON output to jq
Corrupt API response

Solutions:

1. Explicitly request JSON

ellygent context projects --org <org-name> --format json

2. Validate JSON before parsing

ellygent context projects --org <org-name> -f json | jq . > /dev/null
# Check for errors before processing

3. Check for error messages

# Read the full output before piping to jq
ellygent context projects --org <org-name> -f json

Symptoms:

Token expired or Invalid token errors

Common Causes:

Access token has expired
PAT was revoked
Refresh token is invalid

Solutions:

1. Re-authenticate

ellygent auth login

2. Generate new PAT

# Go to Account → Personal Access Tokens
# Create new token and update environment

3. Clear and re-login

rm ~/.ellygent/config.json
ellygent auth login

Platform-Specific Issues

Windows

Execution Policy Errors
PowerShell may block script execution.
```
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

Path Issues

Ensure npm global bin is in system PATH.

npm config get prefix\n# Add this path to System Environment Variables

macOS

Command Line Tools Missing
```
xcode-select --install
```
Node.js Installation
If you don't have Node.js installed, download it from nodejs.org or use Homebrew:
```
brew install node\nnpm install -g @ellygent/cli
```

Linux

Permission Issues

# Use node version manager (nvm) instead of system Node.js\ncurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash\nnvm install 18\nnpm install -g @ellygent/cli

Getting Help

If you're still experiencing issues, contact support with diagnostic information.

Gather Diagnostic Info

# System information
ellygent --version
node --version
npm --version

# Current configuration
ellygent config

# Environment variables
env | grep ELLYGENT

# Recent error messages
ellygent <command> 2>&1 | tee error.log

Contact Support

Previous: CI/CD Integration Next: Reference

Troubleshooting

Common issues, error messages, and solutions for the Ellygent CLI.

Quick Diagnostic

Common Issues & Solutions

Authentication Failed

Symptoms:

Common Causes:

Solutions:

Command Not Found

Symptoms:

Common Causes:

Solutions:

Network/Connection Errors

Symptoms:

Common Causes:

Solutions:

Permission Denied Errors

Symptoms:

Common Causes:

Solutions:

Sync Fails or Incomplete Download

Symptoms:

Common Causes:

Solutions:

JSON Parsing Errors

Symptoms:

Common Causes:

Solutions:

Expired or Invalid Tokens

Symptoms:

Common Causes:

Solutions:

Platform-Specific Issues

Windows

macOS

Linux

Getting Help

Gather Diagnostic Info

Contact Support