Skip to content

CLI Troubleshooting

Common issues when using AnkaSecure CLI and their solutions.

Configuration Issues

Command Not Found

Symptom: 

bash: ankasecure-cli: command not found

Solutions:

  1. Verify installation: 

    which ankasecure-cli
# Should return: /usr/local/bin/ankasecure-cli (or similar)

  2. Add to PATH (if not found): 

    # Linux/macOS
export PATH=$PATH:/usr/local/bin

# Add to ~/.bashrc or ~/.zshrc for persistence
echo 'export PATH=$PATH:/usr/local/bin' >> ~/.bashrc

  3. Reinstall CLI: Download installer

Configuration File Not Found

Symptom: 

Error: Configuration file not found: ~/.ankasecure/config.properties

Solutions:

  1. Initialize configuration: 

    ankasecure-cli config init

# Follow prompts to enter:
# - API Endpoint
# - API Key
# - Tenant ID

  2. Manually create config (if init fails): 

    mkdir -p ~/.ankasecure
cat > ~/.ankasecure/config.properties <<EOF
api.url=https://api.ankasecure.com
api.key=YOUR_API_KEY
tenant.id=YOUR_TENANT_ID
EOF

Authentication Issues

401 Unauthorized

Symptom: 

Error: Authentication failed (401)
Message: Token validation failed

Solutions:

  1. Verify API key: 

    ankasecure-cli config show
# Check api.key value

# Update if incorrect
ankasecure-cli config set api-key "ask_correct_key_here"

  2. Test authentication: 

    ankasecure-cli key list
# Should return list of keys (or empty array)

  3. Regenerate API key: Via Admin Console if key invalid

Operation Errors

Key Not Found (404)

Symptom: 

Error: Key not found (404)
Key ID: my-key-123

Solutions:

  1. List available keys: 

    ankasecure-cli key list
# Shows all keys in your tenant

  2. Check key ID (case-sensitive): 

    # ❌ WRONG
--key-id My-Key-123

# ✅ CORRECT
--key-id my-key-123

  3. Generate missing key: 

    ankasecure-cli key generate \
    --algorithm ML-KEM-768 \
    --key-id my-key-123

Rate Limit Exceeded (429)

Symptom: 

Error: Rate limit exceeded (429)
Retry after: 60 seconds

Solutions:

  1. Wait and retry: 

    # Wait 60 seconds, then retry
sleep 60
ankasecure-cli encrypt --key-id my-key --input data.txt --output data.enc

  2. Implement retry in script: 

    #!/bin/bash
retry_count=0
max_retries=3

while [ $retry_count -lt $max_retries ]; do
    ankasecure-cli encrypt --key-id my-key --input data.txt --output data.enc

    if [ $? -eq 0 ]; then
        exit 0  # Success
    fi

    retry_count=$((retry_count + 1))
    sleep $((retry_count * 30))  # Exponential: 30s, 60s, 90s
done

echo "Failed after $max_retries retries" >&2
exit 1

  3. Reduce request rate: Add delays between CLI calls

  4. Request quota increase: sales@ankatech.co

File Operation Errors

File Not Found

Symptom: 

Error: Input file not found: /path/to/data.txt

Solutions:

  1. Verify file exists: 

    ls -lh /path/to/data.txt
# Check file exists and is readable

  2. Check file permissions: 

    chmod 644 /path/to/data.txt  # Make readable

  3. Use absolute path: 

    # ✅ GOOD: Absolute path
ankasecure-cli encrypt --input /home/user/data.txt --output data.enc

# ⚠️ Be careful with relative paths
ankasecure-cli encrypt --input ./data.txt --output ./data.enc

Permission Denied (Output File)

Symptom: 

Error: Cannot write to output file: /protected/data.enc
Permission denied

Solutions:

  1. Check output directory permissions: 

    ls -ld /protected/
# Ensure directory is writable

  2. Change output location: 

    # Write to home directory instead
ankasecure-cli encrypt \
    --key-id my-key \
    --input data.txt \
    --output ~/data.enc  # User's home directory

Network Issues

Connection Timeout

Symptom: 

Error: Connection timeout after 30 seconds

Causes: - High network latency - Firewall blocking HTTPS (port 443) - Proxy required but not configured

Solutions:

  1. Test connectivity: 

    curl -I https://api.ankasecure.com/api/v1/public/health
# Expected: HTTP/2 200 (within 2 seconds)

  2. Configure proxy (if behind corporate firewall): 

    export HTTPS_PROXY=http://proxy.example.com:8080
ankasecure-cli key list

  3. Increase timeout: 

    ankasecure-cli config set timeout 60000  # 60 seconds

Debugging

Enable Debug Output

Verbose mode:

ankasecure-cli --verbose encrypt --key-id my-key --input data.txt --output data.enc

# Output includes:
# - HTTP request/response details
# - Timing information
# - Correlation IDs

Debug logs: 

ankasecure-cli --debug key list > debug.log 2>&1

# Review debug.log for detailed diagnostics

Check CLI Version

Ensure latest version:

ankasecure-cli version
# AnkaSecure CLI v3.0.0

# Update CLI
ankasecure-cli update  # Auto-update to latest version

Common Error Messages

Error Code Message Cause Solution
AUTH_001 Authentication failed Invalid API key Verify API key in config
KEY_001 Key not found Invalid key ID List keys, verify key ID
CRYPTO_001 Ciphertext integrity failed Corrupted ciphertext Re-encrypt from source
RATE_001 Rate limit exceeded Too many requests Wait and retry
QUOTA_001 Monthly quota exceeded Usage limit reached Upgrade plan

See complete error catalog →

Need Help?

Documentation Version: 3.0.0 Last Updated: 2025-12-26