YouTrack CLI

A powerful command line interface for JetBrains YouTrack issue tracking system.

Features

• Complete YouTrack Management: Issues, articles, projects, users, time tracking, boards, and reporting
• Enterprise Security Features: Command audit logging, credential encryption, token expiration warnings
• Flexible Authentication: Secure token-based authentication with keyring integration
• Rich Output Formats: Beautiful tables and JSON export for automation
• Progress Indicators: Visual feedback for long-running operations with Rich progress bars
• Comprehensive Configuration: Customizable defaults and environment-specific settings
• Administrative Tools: System management, user groups, and health monitoring
• Developer-Friendly: Built with modern Python practices and extensive documentation
• Enhanced Error Handling: User-friendly error messages with actionable suggestions
• Advanced Logging: Rich logging with debug and verbose modes for troubleshooting
• Robust HTTP Operations: Automatic retry logic with exponential backoff for reliability
• Performance Optimization: Dynamic field selection reduces API response sizes by up to 75%

Quick Start

Installation

Using uv (Recommended)

The fastest and most reliable way to install YouTrack CLI:

# Install uv first (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install YouTrack CLI as a tool
uv tool install youtrack-cli

# Verify installation
yt --version

Traditional pip installation

# From PyPI (when available)
pip install yt-cli

# With virtual environment (recommended for pip)
python -m venv youtrack-env
source youtrack-env/bin/activate  # Linux/macOS
# or
youtrack-env\Scripts\activate     # Windows
pip install yt-cli

Development installation

# Clone and set up for development
git clone https://github.com/YOUR_USERNAME/yt-cli.git
cd yt-cli

# Using uv (recommended)
uv sync --dev
uv pip install -e .

# Or using pip (requires pip >= 24.0 for PEP 735 support)
pip install -e . --group dev

Authentication

# Login to your YouTrack instance
yt auth login

# Login with SSL certificate verification disabled (for self-signed certificates)
yt auth login --no-verify-ssl

# Verify authentication
yt auth token --show

Shell Completion

YouTrack CLI supports tab completion for bash, zsh, and fish shells:

# Enable shell completion (see docs for full instructions)
yt completion bash --install

📖 Complete shell completion guide

Basic Usage

# List projects
yt projects list

# Create an article
yt articles create "Getting Started" --content "Welcome to our documentation"

# Create an article from a markdown file
yt articles create "API Documentation" --file api-docs.md

# Log work time
yt time log ISSUE-123 "2h" --description "Feature development"

# Generate reports (flatter syntax)
yt burndown PROJECT-123
yt velocity PROJECT-123

# Or use traditional nested commands
yt reports burndown PROJECT-123

# Enable debug logging for troubleshooting
yt --debug issues list

Documentation

📚 Complete Documentation

For comprehensive guides, examples, and API reference, visit our documentation:

• Quick Start Guide - Get up and running quickly
• Command Reference - Detailed documentation for all commands
• Configuration Guide - Customize your CLI experience
• Development Guide - Contributing and development setup

Available Commands

Command Group	Description
yt issues	Complete issue lifecycle management with search, comments, and relationships
yt articles	Manage knowledge base articles with hierarchical organization and tagging
yt projects	Create and manage YouTrack projects
yt users	User management and permissions
yt time	Time tracking with flexible duration formats
yt boards	Agile board operations and management
yt reports	Generate burndown and velocity reports
yt burndown	Generate burndown reports (flatter alternative)
yt velocity	Generate velocity reports (flatter alternative)
yt groups	Manage user groups (flatter alternative to admin user-groups)
yt settings	Manage global settings (flatter alternative to admin global-settings)
yt audit	View audit logs (flatter alternative to security audit)
yt auth	Authentication and credential management
yt config	CLI configuration and preferences
yt admin	Administrative operations (requires admin privileges)

Command Examples

Issues

# Create and manage issues
yt issues create PROJECT-123 "Fix login bug" --type Bug --priority High --assignee john.doe
yt issues list --project-id PROJECT-123 --state Open
yt issues search "priority:Critical state:Open"
yt issues update ISSUE-456 --state "In Progress"

# Comments and collaboration
yt issues comments add ISSUE-456 "Fixed in latest build"
yt issues attach upload ISSUE-456 /path/to/screenshot.png

# Issue relationships
yt issues links create ISSUE-456 ISSUE-789 "depends on"
yt issues tag add ISSUE-456 urgent

Articles

# Create and manage knowledge base
yt articles create "API Guide" --content "Comprehensive API documentation"

# Create articles from markdown files
yt articles create "Installation Guide" --file docs/install.md

# Organize existing documentation
yt articles create "Developer Guide" --file dev-guide.md --project-id PROJECT-123

# Tag articles for better organization
yt articles tag ARTICLE-123 documentation tutorial

yt articles tree --project-id PROJECT-123
yt articles search "authentication"

Projects

# Project management
yt projects create "Web App" "WEB" --leader john.doe --template scrum
yt projects list --show-archived
yt projects configure WEB --description "Main web application"

Time Tracking

# Flexible time logging
yt time log ISSUE-123 "2h 30m" --work-type "Development"
yt time report --start-date "2024-01-01" --end-date "2024-01-31"
yt time summary --group-by user

Reporting

# Project insights (flatter syntax)
yt burndown PROJECT-123 --sprint "Sprint 1"
yt velocity PROJECT-123 --sprints 10

# Or use traditional nested commands
yt reports burndown PROJECT-123 --sprint "Sprint 1"
yt reports velocity PROJECT-123 --sprints 10

Administration

# User group management (flatter syntax)
yt groups create "Team Lead" --description "Team leadership role"
yt groups list

# Global settings (flatter syntax)
yt settings get --name system.timeZone
yt settings set timeout 30

# Audit logging (flatter syntax)
yt audit --limit 25 --format json

# Traditional nested commands also work
yt admin user-groups create "Team Lead"
yt admin global-settings get
yt security audit

Help and Support

• 📖 Documentation - Comprehensive guides and examples
• 🐛 Issue Tracker - Report bugs and request features
• 💬 Discussions - Ask questions and share ideas

Development

This project uses uv for dependency management.

Setup

# Clone the repository
git clone https://github.com/YOUR_USERNAME/yt-cli.git
cd yt-cli

# Install dependencies
uv sync --dev

# Install pre-commit hooks
uv run pre-commit install

# Install the package in editable mode
uv pip install -e .

Testing

This project uses pytest with randomized test execution to ensure test reliability:

# Run tests (automatically randomized order)
uv run pytest

# Run tests with coverage
uv run pytest --cov=yt_cli

# Run tests on multiple Python versions
uv run tox

# Run tests with specific random seed for reproducibility
uv run pytest --randomly-seed=12345

# Disable randomization if needed
uv run pytest --randomly-dont-shuffle

Randomized Testing: Tests run in random order by default using pytest-randomly to catch order-dependent bugs and improve test reliability. Each test run displays the random seed used, which can be reused to reproduce specific test failures.

Code Quality

This project uses comprehensive pre-commit hooks for code quality:

# Run all quality checks (automatically runs on commit)
uv run pre-commit run --all-files

# Individual quality checks
uv run ruff check      # Linting
uv run ruff format     # Code formatting
uv run ty check        # Type checking

Pre-commit Hooks

The project includes comprehensive pre-commit hooks that run automatically before each commit:

• File Quality: Trailing whitespace, end-of-file fixes, YAML/TOML validation
• Code Quality: Ruff linting and formatting, ty type checking
• Testing: Full pytest test suite
• Security: zizmor GitHub Actions security analysis

To run pre-commit hooks manually:

# Run all hooks on all files
uv run pre-commit run --all-files

# Run specific hook
uv run pre-commit run pytest

Security

# Check GitHub Actions workflows
uv run zizmor .github/workflows/

License

MIT License - see LICENSE file for details.