Progress Indicators

The YouTrack CLI provides visual progress indicators for long-running operations to improve user experience and provide feedback during bulk operations.

Overview

Progress indicators are automatically shown for operations that may take significant time, including:

  • Report Generation: Burndown and velocity reports with large datasets

  • Issue Operations: Bulk issue listing, searching, and file operations

  • Admin Operations: System maintenance tasks, cache clearing, and health checks

  • File Operations: Upload/download of attachments

Types of Progress Indicators

Progress Bars

For operations with known duration or item count:

⠋ Generating burndown report... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 3/3 0:00:02 0:00:00

Features:

  • Spinner animation

  • Descriptive text that updates during operation

  • Progress bar showing completion percentage

  • Item counters (completed/total)

  • Time elapsed and estimated time remaining

Spinners

For indeterminate operations:

⠋ Fetching issues...

Used when the total duration or item count is unknown.

Configuration

Disabling Progress Indicators

You can disable progress indicators globally using the --no-progress flag:

# Disable progress indicators for a single command
yt --no-progress reports burndown PROJECT-1

# Disable for all subcommands
yt --no-progress issues list --project PROJECT-1

Environment Compatibility

Progress indicators automatically detect the environment:

  • Interactive terminals: Full progress bars with animations

  • Non-interactive environments: Simplified or disabled output

  • CI/CD pipelines: Automatically disabled to prevent log clutter

Implementation Details

Progress Manager

The progress system is built around a centralized ProgressManager class that:

  • Manages multiple concurrent progress indicators

  • Handles environment detection

  • Provides context managers for easy integration

  • Supports both determinate and indeterminate progress

Integration Pattern

Operations integrate progress indicators using context managers:

from .progress import get_progress_manager

progress_manager = get_progress_manager()

# For determinate progress
with progress_manager.progress_bar("Processing items...", total=len(items)) as tracker:
    for item in items:
        # Process item
        tracker.advance()

# For indeterminate progress
with progress_manager.spinner("Working..."):
    # Long-running operation
    perform_operation()

Affected Commands

Reports

All report generation commands show progress indicators:

  • yt reports burndown - Shows 3-step progress for query building, data fetching, and metric calculation

  • yt reports velocity - Shows progress for each sprint being analyzed

Issues

Issue commands with progress indicators:

  • yt issues list - Spinner during API calls for large result sets

  • yt issues search - Progress bar for complex searches

  • yt issues attach upload - Progress bar for file uploads

  • yt issues attach download - Progress bar for file downloads

Admin

Administrative operations with progress:

  • yt admin maintenance clear-cache - Spinner for cache clearing operations

  • yt admin health check - Progress bar for multi-step diagnostics

  • yt admin usage users report - Progress bar for report generation

Best Practices

For Users

  1. Large Operations: Progress indicators are most helpful for operations involving:

    • More than 100 items

    • File uploads/downloads

    • Complex reports or searches

  2. CI/CD Integration: Use --no-progress in automated scripts to keep logs clean

  3. Performance: Progress indicators add minimal overhead and can be left enabled in most cases

For Developers

  1. Integration: Add progress indicators to any operation that:

    • Takes more than 2-3 seconds typically

    • Processes multiple items sequentially

    • Involves network I/O with potential delays

  2. Granularity: Choose appropriate progress granularity:

    • Too fine: Updates too frequently, performance impact

    • Too coarse: Poor user experience

  3. Error Handling: Progress indicators automatically clean up on exceptions

Performance Impact

Progress indicators are designed to have minimal performance impact:

  • Overhead: Less than 1% for typical operations

  • Memory: Minimal additional memory usage

  • Network: No additional network calls

  • Rendering: Efficient terminal rendering with minimal CPU usage

The progress system automatically disables in non-interactive environments to eliminate any overhead in automated scenarios.