Quick Start Guide

This guide will help you get started with YouTrack CLI quickly.

Before You Begin

What is YouTrack?

YouTrack is an issue tracking and project management tool by JetBrains. If you’re new to YouTrack, we recommend reading the YouTrack Concepts guide first for a comprehensive understanding.

Key Concepts (Quick Reference):

  • Issues: Work items like bugs, features, or tasks that need to be tracked

  • Projects: Containers that organize related issues (e.g., “WEB-FRONTEND”, “MOBILE-APP”)

  • States: Issue statuses like “Open”, “In Progress”, “Resolved”, “Closed”

  • Assignee: The person responsible for working on an issue

  • Priority: Importance level (Critical, High, Medium, Low)

  • Types: Category of work (Bug, Feature, Task, Epic)

Prerequisites

  • A YouTrack instance URL (ask your team lead or admin)

  • API token or login credentials (see Authentication section below)

  • Basic command line familiarity

  • Python 3.9+ installed on your system

1. Authentication

First, authenticate with your YouTrack instance:

yt auth login

You’ll be prompted to enter: - YouTrack URL (e.g., https://yourcompany.youtrack.cloud) - Username - Password or API token

2. Basic Commands

List Issues

View all issues assigned to you:

yt issues list

Search for specific issues:

yt issues search "assignee:me state:open"

Create an Issue

Create a bug report for a login issue:

yt issues create WEB-FRONTEND "Login button not responding on mobile Safari" \
  --description "Users on iPhone 12 and 13 cannot tap login button. Error occurs on iOS Safari only." \
  --priority "High" \
  --type "Bug" \
  --assignee "mobile-team-lead"

Expected output:

🐛 Creating issue 'Login button not responding on mobile Safari' in project 'WEB-FRONTEND'...
✅ Issue 'Login button not responding on mobile Safari' created successfully
Issue ID: WEB-FRONTEND-123

Create a feature request:

yt issues create API-BACKEND "Add user profile API endpoint" \
  --description "Create REST API endpoint for user profile management with CRUD operations" \
  --priority "Medium" \
  --type "Feature" \
  --assignee "backend-dev"

Update an Issue

Update issue fields:

yt issues update ISSUE-123 --state "In Progress" --assignee "jane.doe"

Add a comment:

yt issues comments add ISSUE-123 "Working on this issue"

3. Project Management

List Projects

View all available projects:

yt projects list

Create a Project

yt projects create "New Project" "NP" --description "Project description"

1. Time Tracking

Log Work Time

Log time spent on an issue:

yt time log ISSUE-123 "2h 30m" --description "Fixed the bug"

View Time Reports

Generate time reports:

yt time report --from "2024-01-01" --to "2024-01-31" --assignee "me"

5. Configuration

View Current Configuration

yt config list

Set Configuration Values

yt config set default_project "PROJECT-ID"
yt config set output_format "table"

6. Common Workflows

Daily Workflow

  1. Check your assigned issues:

    yt issues list --assignee me --state open

  2. Update issue status as you work:

    yt issues update ISSUE-123 --state "In Progress"

  3. Log time when you’re done:

    yt time log ISSUE-123 "4h" --description "Completed implementation"

  4. Mark issue as resolved:

    yt issues update ISSUE-123 --state "Fixed"

Getting Help and Debugging

Get help for any command:

yt --help
yt issues --help
yt issues create --help

Troubleshooting Commands

If you encounter issues, YouTrack CLI provides enhanced debugging capabilities:

Verbose Mode - Shows progress and additional information:

yt --verbose issues list
yt --verbose projects create "New Project" "NP"

Debug Mode - Shows detailed information for troubleshooting:

yt --debug auth login
yt --debug issues create PROJECT-KEY "Test issue"

Error Examples with Suggestions

YouTrack CLI now provides helpful error messages with actionable suggestions:

# Example: Authentication error
$ yt issues list
Error: Authentication failed
Suggestion: Run 'yt auth login' to authenticate with YouTrack

# Example: Project not found
$ yt issues create INVALID-PROJECT "Test issue"
Error: Project 'INVALID-PROJECT' not found
Suggestion: Check if the project exists and you have access to it

Output Formatting Options

Control how results are displayed:

# Table format (default)
yt issues list --format table

# JSON format for automation
yt issues list --format json

Next Steps