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

Machine-Readable Output (JSON and CSV)

When a machine-readable output format is requested with --format json or --format csv, status and progress messages (for example 🔍 Fetching issues...) are written to stderr instead of stdout. This guarantees that stdout contains only the structured payload, so the output can be piped or parsed directly without any manual filtering:

# stdout contains only valid JSON; the status line goes to stderr
yt issues list --query "project:FOO type: Epic" --format json | jq '.[].id'

# Discard the status messages entirely by redirecting stderr
yt issues list --format json 2>/dev/null > issues.json

To suppress the status messages on stderr as well, combine with --quiet:

yt --quiet issues list --format json

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.