Luciq CLI

Features

• 🔐 Authentication & Configuration - Secure token-based authentication with multiple profile support
• 📦 Release Management - Create releases, upload source maps, and manage deployments
• 🐛 Event & Error Tracking - Send custom events and errors directly from CLI
• 📊 Log Viewing - View and stream application logs in real-time
• ⏰ Cron Monitoring - Set up and manage cron job monitors
• 🔍 Debug Files - Upload and manage debug symbols (dSYMs, Proguard, source maps)
• 🎯 Project Management - Create and manage projects across organizations

Installation

NPM (Recommended)

npm install -g luciq-cli

From Source

git clone https://github.com/your-org/luciq-cli.git
cd luciq-cli
npm install
npm link

Verify Installation

luciq-cli --version
luciq-cli --help

Quick Start

1. Authenticate with Instabug:

# Using email and password (recommended)
luciq-cli auth login

# OR using an API token
luciq-cli auth login-token

Email/Password: Use your Instabug developer account credentials.
API Token: Get your token from Instabug Dashboard → Settings → API Tokens.

2. Verify authentication:

luciq-cli auth whoami

3. Create your first release:

luciq-cli releases new 1.0.0 --org myorg --project myapp

Commands

Authentication

# Login with email and password (recommended)
luciq-cli auth login

# Login with API token
luciq-cli auth login-token

# Check current authentication status
luciq-cli auth whoami

# Logout and clear credentials
luciq-cli auth logout

# Manage configuration
luciq-cli auth config --list
luciq-cli auth config --set defaultOrg=myorg

Login Methods

Method 1: Email & Password (Interactive)

luciq-cli auth login
# You'll be prompted for:
# - Email address
# - Password (hidden input)

Method 2: Email & Password (Command Line)

luciq-cli auth login --email [email protected] --password yourpassword

Method 3: API Token (Interactive)

luciq-cli auth login-token
# You'll be prompted for your API token

Method 4: API Token (Command Line)

luciq-cli auth login-token --token your-api-token

Releases

# Create a new release
luciq-cli releases new 1.0.0 --org myorg --project myapp

# Auto-detect version from package.json
luciq-cli releases new --auto --org myorg --project myapp

# Create and finalize immediately
luciq-cli releases new 1.0.0 --finalize

# List all releases
luciq-cli releases list

# Upload source maps and files
luciq-cli releases upload-files 1.0.0 dist/**/*.map --org myorg --project myapp

# Finalize a release
luciq-cli releases finalize 1.0.0

# Delete a release
luciq-cli releases delete 1.0.0

Events

# Send a custom event
luciq-cli events send --message "Deployment completed" --level info

# Send an error event
luciq-cli events send-error --message "Database connection failed" --type ConnectionError

# Send event from JSON file
luciq-cli events send --json event.json

# Include tags and extra data
luciq-cli events send \
  --message "Payment processed" \
  --tags environment:production user:123 \
  --extra amount:99.99 currency:USD

Logs

# View recent logs
luciq-cli logs view --limit 100

# Filter by log level
luciq-cli logs view --level error

# View logs from last hour
luciq-cli logs view --since 1h

# Stream logs in real-time
luciq-cli logs stream

# Export as JSON
luciq-cli logs view --format json > logs.json

Monitors (Cron Jobs)

# Create a new monitor
luciq-cli monitors create \
  --name "Daily Backup" \
  --schedule "0 2 * * *" \
  --threshold 15

# List all monitors
luciq-cli monitors list

# Send a check-in
luciq-cli monitors checkin <monitor-id> --status ok

# Send a check-in with duration
luciq-cli monitors checkin <monitor-id> --status ok --duration 5000

# Delete a monitor
luciq-cli monitors delete <monitor-id>

Debug Files

# Upload debug symbols
luciq-cli debug-files upload path/to/symbols.dsym --type dsym

# Upload source maps
luciq-cli debug-files upload dist/**/*.map --type sourcemap --release 1.0.0

# Upload using pattern matching
luciq-cli debug-files upload --pattern "build/**/*.map" --release 1.0.0

# List uploaded debug files
luciq-cli debug-files list

# Delete a debug file
luciq-cli debug-files delete <file-id>

Projects

# List all projects
luciq-cli projects list --org myorg

# Create a new project
luciq-cli projects create --name "My App" --slug my-app --platform javascript

# Get project information
luciq-cli projects info my-app

# Set default project
luciq-cli projects set-default my-app

Configuration

Configuration Precedence

The CLI uses the following configuration precedence (highest to lowest):

1. CLI flags - --org myorg --project myapp
2. Environment variables - LUCIQ_ORG=myorg LUCIQ_PROJECT=myapp
3. Project .luciqrc file - .luciqrc in current directory
4. Global configuration - Stored in ~/.config/luciq-cli/

Environment Variables

export LUCIQ_AUTH_TOKEN="your-auth-token"
export LUCIQ_API_URL="https://api.luciq.io"
export LUCIQ_ORG="myorg"
export LUCIQ_PROJECT="myapp"

.luciqrc File

Create a .luciqrc file in your project root:

{
  "org": "myorg",
  "project": "myapp",
  "release": "1.0.0"
}

Global Configuration

# View all configuration
luciq-cli auth config --list

# Set configuration values
luciq-cli auth config --set defaultOrg=myorg
luciq-cli auth config --set defaultProject=myapp

# Get a configuration value
luciq-cli auth config --get defaultOrg

# Delete a configuration value
luciq-cli auth config --delete defaultProject

Examples

CI/CD Integration

GitHub Actions

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Luciq CLI
        run: npm install -g luciq-cli
      
      - name: Create Release
        env:
          LUCIQ_AUTH_TOKEN: ${{ secrets.LUCIQ_AUTH_TOKEN }}
        run: |
          VERSION=$(node -p "require('./package.json').version")
          luciq-cli releases new $VERSION --org myorg --project myapp --auto-commit
      
      - name: Upload Source Maps
        env:
          LUCIQ_AUTH_TOKEN: ${{ secrets.LUCIQ_AUTH_TOKEN }}
        run: |
          VERSION=$(node -p "require('./package.json').version")
          luciq-cli releases upload-files $VERSION dist/**/*.map
      
      - name: Finalize Release
        env:
          LUCIQ_AUTH_TOKEN: ${{ secrets.LUCIQ_AUTH_TOKEN }}
        run: |
          VERSION=$(node -p "require('./package.json').version")
          luciq-cli releases finalize $VERSION

GitLab CI

deploy:
  stage: deploy
  script:
    - npm install -g luciq-cli
    - export VERSION=$(node -p "require('./package.json').version")
    - luciq-cli releases new $VERSION --org myorg --project myapp
    - luciq-cli releases upload-files $VERSION dist/**/*.map
    - luciq-cli releases finalize $VERSION
  only:
    - main
  variables:
    LUCIQ_AUTH_TOKEN: $CI_LUCIQ_TOKEN

Cron Job Monitoring

Wrap your cron jobs to automatically send check-ins:

#!/bin/bash

MONITOR_ID="your-monitor-id"

# Start time
START=$(date +%s%3N)

# Run your job
if your-cron-job.sh; then
  STATUS="ok"
else
  STATUS="error"
fi

# Calculate duration
END=$(date +%s%3N)
DURATION=$((END - START))

# Send check-in
luciq-cli monitors checkin $MONITOR_ID --status $STATUS --duration $DURATION

Local Development

# Send test events during development
luciq-cli events send \
  --message "Testing new feature" \
  --level info \
  --tags environment:development feature:new-ui \
  --extra user:developer timestamp:$(date -u +%s)

# Stream logs while debugging
luciq-cli logs stream --level error --source backend

Automated Error Reporting

// In your Node.js application
const { exec } = require('child_process');

process.on('uncaughtException', (error) => {
  const command = `luciq-cli events send-error --message "${error.message}" --type "${error.name}"`;
  exec(command, (err) => {
    if (err) console.error('Failed to send error to Luciq:', err);
    process.exit(1);
  });
});

Global Options

All commands support these global options:

--api-url <url>         # Override API URL
--auth-token <token>    # Authentication token (overrides config)
--org <org>             # Organization identifier
--project <project>     # Project identifier
--silent                # Suppress output
--debug                 # Enable debug output
-v, --version           # Display version
-h, --help              # Display help

Troubleshooting

Authentication Issues

If you're getting authentication errors, enable debug mode to see detailed logs:

# Run with debug flag to see full API request/response
luciq-cli --debug auth login

# This will show:
# - Request URL
# - Request payload (password hidden)
# - Response status and data
# - Detailed error information

Quick Debug Steps:

1. Use the test script to verify API directly:

   ./test-auth.sh

2. Check with curl:

   curl -X POST https://dashboard-api.instabug.com/api/web/developer/sign_in \
     -H "Content-Type: application/json" \
     -d '{"developer":{"email":"[email protected]","password":"yourpass"}}' \
     -v

3. Try token authentication instead:

   luciq-cli auth login-token

4. Read the debug guide:

   cat DEBUG_AUTH.md

Common Errors

"The email or password you entered is incorrect"

• Verify your credentials are correct
• Check if you're using the right Instabug account
• Try the test-auth.sh script to see the raw API response
• Enable --debug mode to see what the API returns

"Network error: Unable to reach Instabug API"

• Check your internet connection
• Verify firewall settings
• Test: curl -I https://dashboard-api.instabug.com

"No authentication token received from server"

• The API returned success but no token
• Enable --debug to see the response structure
• API might expect different field names

Debug Mode

Enable debug mode to see detailed API calls:

luciq-cli --debug auth login
luciq-cli --debug releases list

API Connection Issues

Test API connectivity:

# Use custom API URL
luciq-cli --api-url https://your-instance.instabug.com auth whoami

API Documentation

For more information about the Luciq API, visit:

• API Documentation
• Authentication Guide
• Release Management

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Support

• 📧 Email: [email protected]
• 💬 Discord: discord.gg/luciq
• 📚 Documentation: docs.luciq.io
• 🐛 Issues: GitHub Issues

License

MIT License - see LICENSE file for details.