API Reference

This section documents the Python API for YouTrack CLI. While the primary interface is the command-line tool, the underlying Python modules can be used programmatically.

Core Modules

youtrack_cli.exceptions

Custom exceptions and error handling for YouTrack CLI.

Client API

The YouTrackClient is the main interface for interacting with YouTrack programmatically:

from youtrack_cli.client import YouTrackClient

client = YouTrackClient(
    url="https://your-company.myjetbrains.com/youtrack",
    token="your-api-token"
)

# List issues
issues = client.issues.list(assignee="me", state="open")

# Create an issue
issue = client.issues.create(
    title="Bug report",
    description="Something is broken",
    project="PROJECT-ID"
)

# Update an issue
client.issues.update(issue.id, state="In Progress")

Models

YouTrack CLI uses Pydantic models for data validation and serialization. Key models include:

Issue - Issue data structure
Project - Project information
User - User details
Comment - Issue comments
Attachment - File attachments

Configuration

Programmatic configuration using the settings system:

from youtrack_cli.config import Settings

settings = Settings(
    youtrack_url="https://your-company.myjetbrains.com/youtrack",
    youtrack_token="your-api-token",
    default_project="PROJECT-ID"
)

client = YouTrackClient.from_settings(settings)

Error Handling

YouTrack CLI defines several exception types for different error conditions:

from youtrack_cli.exceptions import (
    YouTrackError,
    AuthenticationError,
    NotFoundError,
    ValidationError
)

try:
    issue = client.issues.get("INVALID-ID")
except NotFoundError:
    print("Issue not found")
except AuthenticationError:
    print("Authentication failed")
except YouTrackError as e:
    print(f"YouTrack error: {e}")

Utilities

Helper functions and utilities:

from youtrack_cli.utils import (
    format_duration,
    parse_issue_id,
    validate_project_key
)

# Format time duration
formatted = format_duration(7200)  # "2h"

# Parse issue ID
project, number = parse_issue_id("PROJECT-123")

# Validate project key
is_valid = validate_project_key("PROJ")

Integration Examples

Custom Scripts

Creating custom automation scripts:

#!/usr/bin/env python3
"""Auto-assign issues based on keywords."""

from youtrack_cli.client import YouTrackClient
from youtrack_cli.config import Settings

def auto_assign_issues():
    settings = Settings()
    client = YouTrackClient.from_settings(settings)

    # Get unassigned issues
    issues = client.issues.list(assignee=None, state="Open")

    for issue in issues:
        if "frontend" in issue.summary.lower():
            client.issues.update(issue.id, assignee="frontend-team")
        elif "backend" in issue.summary.lower():
            client.issues.update(issue.id, assignee="backend-team")

if __name__ == "__main__":
    auto_assign_issues()

Jupyter Notebooks

Using YouTrack CLI in data analysis:

import pandas as pd
from youtrack_cli.client import YouTrackClient

client = YouTrackClient(url="...", token="...")

# Get issues data
issues = client.issues.list(project="PROJECT-ID")

# Convert to DataFrame
df = pd.DataFrame([issue.dict() for issue in issues])

# Analyze issue metrics
state_counts = df.groupby('state').size()
print(state_counts)

Web Applications

Integrating with web frameworks:

from flask import Flask, jsonify
from youtrack_cli.client import YouTrackClient

app = Flask(__name__)
client = YouTrackClient(url="...", token="...")

@app.route('/api/issues')
def get_issues():
    issues = client.issues.list(state="Open")
    return jsonify([issue.dict() for issue in issues])

@app.route('/api/issues', methods=['POST'])
def create_issue():
    data = request.json
    issue = client.issues.create(**data)
    return jsonify(issue.dict()), 201