Issues Command Group

The yt issues command group provides comprehensive issue management capabilities for YouTrack. This is the core functionality for creating, updating, searching, and managing issues in your YouTrack projects.

Overview

The issues command group offers complete issue lifecycle management including:

  • Creating and updating issues with all custom fields

  • Batch operations for creating and updating multiple issues from files

  • Advanced searching and filtering with YouTrack query language

  • Managing issue comments and attachments

  • Handling issue relationships and links

  • Assigning issues and managing workflow states

  • Managing issue tags and project transitions

Base Command

yt issues [OPTIONS] COMMAND [ARGS]...

Issue Management Commands

Create Issues

Create new issues in YouTrack projects.

yt issues create PROJECT_ID SUMMARY [OPTIONS]
Arguments:

  • PROJECT_ID - The ID of the project to create the issue in

  • SUMMARY - Brief description of the issue

Options:

  • -d, --description TEXT - Detailed issue description

  • -t, --type TEXT - Issue type (e.g., Bug, Feature, Task)

  • -p, --priority TEXT - Issue priority (e.g., Critical, High, Medium, Low)

  • -a, --assignee TEXT - Username of the assignee

Example:

yt issues create PROJ-1 "Fix login bug" -d "Users cannot login with special characters" -t Bug -p High -a john.doe

List Issues

List and filter issues with advanced options.

yt issues list [OPTIONS]
Options:

  • -p, --project-id TEXT - Filter by project ID

  • -s, --state TEXT - Filter by issue state

  • -a, --assignee TEXT - Filter by assignee

  • -f, --fields TEXT - Comma-separated list of fields to return

  • -t, --top INTEGER - Maximum number of issues to return (legacy)

  • --max-results INTEGER - Maximum number of results to fetch (default: 10,000)

  • --after-cursor TEXT - Start listing after this cursor position

  • --before-cursor TEXT - Start listing before this cursor position

  • --paginated - Display results with interactive pagination

  • --display-page-size INTEGER - Items per page for interactive display (default: 50)

  • --all - Fetch all results automatically (respects max-results limit)

  • -q, --query TEXT - Advanced query filter using YouTrack syntax

  • --format [table|json|csv] - Output format (default: table)

Note

The assignee column in table output displays both the user’s full name and username in the format “Full Name (username)” when both are available. This helps with user identification when multiple users may share similar names.

Examples:

# List all issues in a project with interactive pagination
yt issues list -p PROJ-1 --paginated

# List high priority bugs assigned to a user
yt issues list -p PROJ-1 -a john.doe --query "priority:High type:Bug"

# List issues in JSON format with cursor pagination
yt issues list --format json --max-results 50

# Export issues to CSV format for spreadsheet analysis
yt issues list --format csv --limit 100

# Navigate through pages using cursors
yt issues list -p PROJ-1 --after-cursor "cursor_token_here"

# Fetch all issues automatically (up to 10,000)
yt issues list -p PROJ-1 --all

Update Issues

Update existing issues with new field values.

yt issues update ISSUE_ID [OPTIONS]
Arguments:

  • ISSUE_ID - The ID of the issue to update

Options:

  • -s, --summary TEXT - New issue summary

  • -d, --description TEXT - New issue description

  • --state TEXT - New issue state

  • -p, --priority TEXT - New issue priority

  • -a, --assignee TEXT - New assignee username

  • -t, --type TEXT - New issue type

  • --show-details - Show current issue details instead of updating

Examples:

# Update issue priority and assignee
yt issues update PROJ-123 -p Critical -a jane.smith

# View current issue details
yt issues update PROJ-123 --show-details

Delete Issues

Delete issues from YouTrack.

yt issues delete ISSUE_ID [OPTIONS]
Arguments:

  • ISSUE_ID - The ID of the issue to delete

Options:

  • --force - Skip confirmation prompt

Examples:

# Interactive deletion (will prompt for confirmation)
yt issues delete PROJ-123

# Non-interactive deletion for automation
yt issues delete PROJ-123 --force

Note

Use the --force flag for automation scripts and CI/CD pipelines to skip the interactive confirmation prompt.

Search Issues

Advanced issue search with YouTrack query language.

yt issues search QUERY [OPTIONS]
Arguments:

  • QUERY - Search query using YouTrack syntax

Options:

  • -p, --project-id TEXT - Filter by project ID

  • -t, --top INTEGER - Maximum number of results (legacy)

  • --max-results INTEGER - Maximum number of results to fetch (default: 10,000)

  • --after-cursor TEXT - Start searching after this cursor position

  • --before-cursor TEXT - Start searching before this cursor position

  • --paginated - Display results with interactive pagination

  • --display-page-size INTEGER - Items per page for interactive display (default: 50)

  • --all - Fetch all results automatically (respects max-results limit)

  • --format [table|json|csv] - Output format

Examples:

# Search for bugs with specific text
yt issues search "login error" -p PROJ-1

# Complex query with multiple conditions and pagination
yt issues search "priority:Critical state:Open assignee:me" --paginated

# Search with cursor navigation
yt issues search "bug" --after-cursor "search_cursor_token"

# Get all search results automatically
yt issues search "type:Bug state:Open" --all

Assign Issues

Assign issues to users.

yt issues assign ISSUE_ID ASSIGNEE
Arguments:

  • ISSUE_ID - The ID of the issue

  • ASSIGNEE - Username of the new assignee

Example:

yt issues assign PROJ-123 john.doe

Move Issues

Move issues between states within the same project, or transfer issues to different projects entirely.

yt issues move ISSUE_ID [OPTIONS]
Arguments:

  • ISSUE_ID - The ID of the issue to move

Options:

  • -s, --state TEXT - New state for the issue

  • -p, --project-id TEXT - Move to different project (short name or ID)

State Moves (Within Project):

# Move issue to different state
yt issues move PROJ-123 -s "In Progress"
yt issues move PROJ-123 --state "Done"

Project Moves (Between Projects):

# Move issue to different project
yt issues move PROJ-123 -p WEB
yt issues move DEMO-456 --project-id TEST

Advanced Examples:

# Check available projects first
yt projects list

# Move issue with validation
yt issues show PROJ-123  # Verify source issue
yt issues move PROJ-123 -p TARGET-PROJ
yt issues list -p TARGET-PROJ  # Verify move

Warning

Project Move Considerations:

  • Ensure you have appropriate permissions in both source and target projects

  • Custom fields that exist in the source project but not in the target may be lost

  • Issue numbering will change to match the target project’s scheme

  • All issue data (description, comments, attachments) will be preserved

  • Verify the move completed successfully by checking the target project

Note

State Changes:

State changes use YouTrack’s custom field format to ensure reliable transitions. The CLI will report success only when the state change is actually applied. Use exact state names as they appear in your YouTrack workflow.

Tag Management

Manage issue tags.

Add Tags:

yt issues tag add ISSUE_ID TAG_NAME

Remove Tags:

yt issues tag remove ISSUE_ID TAG_NAME

List Tags:

yt issues tag list ISSUE_ID

Examples:

# Add a tag
yt issues tag add PROJ-123 urgent

# Remove a tag
yt issues tag remove PROJ-123 outdated

# List all tags on an issue
yt issues tag list PROJ-123

Benchmark Performance

Benchmark field selection performance improvements to measure API optimization benefits.

yt issues benchmark [OPTIONS]
Options:

  • -p, --project-id TEXT - Project ID to benchmark with

  • --sample-size INTEGER - Number of issues to fetch for benchmarking (default: 50)

Examples:

# Run benchmark with default settings
yt issues benchmark

# Benchmark specific project with custom sample size
yt issues benchmark -p FPU --sample-size 100

# Benchmark with minimal sample for quick testing
yt issues benchmark --sample-size 10

Note

This command runs performance tests comparing minimal, standard, and full field selection profiles to demonstrate the optimization benefits. It helps understand the performance impact of different field selection strategies when working with large datasets.

Comment Management

Manage comments on issues.

Add Comments

yt issues comments add ISSUE_ID TEXT

Example:

yt issues comments add PROJ-123 "Fixed in latest build"

List Comments

yt issues comments list ISSUE_ID [OPTIONS]
Options:

  • --format [table|json|csv] - Output format

Update Comments

yt issues comments update ISSUE_ID COMMENT_ID TEXT

Delete Comments

yt issues comments delete ISSUE_ID COMMENT_ID [OPTIONS]
Options:

  • --force - Skip confirmation prompt

Attachment Management

Manage file attachments on issues.

Upload Attachments

yt issues attach upload ISSUE_ID FILE_PATH

Example:

yt issues attach upload PROJ-123 /path/to/screenshot.png

Download Attachments

yt issues attach download ISSUE_ID ATTACHMENT_ID [OPTIONS]
Options:

  • -o, --output PATH - Output file path

List Attachments

List all attachments for an issue, displaying attachment IDs needed for download and delete operations.

yt issues attach list ISSUE_ID [OPTIONS]
Options:

  • --format [table|json|csv] - Output format

Output: Displays attachment ID, name, size, author, and creation date. The attachment ID can be used with the download and delete commands.

Delete Attachments

yt issues attach delete ISSUE_ID ATTACHMENT_ID [OPTIONS]
Options:

  • --force - Skip confirmation prompt

Issue Relationships

Manage links and relationships between issues.

Batch Operations

The yt issues batch command group provides efficient bulk operations for creating and updating multiple issues from CSV or JSON files. This is ideal for migrating issues, bulk updates, or data imports.

Batch Create Issues

Create multiple issues from a CSV or JSON file.

yt issues batch create --file INPUT_FILE [OPTIONS]
Options:

  • -f, --file PATH - Path to CSV or JSON file containing issue data (required)

  • --dry-run - Validate and preview operations without executing them

  • --continue-on-error - Continue processing after errors (default: true)

  • --save-failed PATH - Save failed operations to specified file for retry

  • --rollback-on-error - Rollback (delete) created issues if any operation fails

CSV File Format: The CSV file should have the following columns:

project_id,summary,description,type,priority,assignee
FPU,Fix login bug,Login fails on mobile devices,Bug,High,john.doe
FPU,Add user dashboard,Create dashboard with user metrics,Feature,Medium,jane.smith

JSON File Format: The JSON file should contain an array of issue objects:

[
  {
    "project_id": "FPU",
    "summary": "Fix login bug",
    "description": "Login fails on mobile devices",
    "type": "Bug",
    "priority": "High",
    "assignee": "john.doe"
  },
  {
    "project_id": "FPU",
    "summary": "Add user dashboard",
    "description": "Create dashboard with user metrics",
    "type": "Feature",
    "priority": "Medium",
    "assignee": "jane.smith"
  }
]

Examples:

# Create issues from CSV file
yt issues batch create --file issues.csv

# Dry run to preview operations
yt issues batch create --file issues.csv --dry-run

# Create with error handling and save failed operations
yt issues batch create --file issues.csv --save-failed failed.csv

# Create with automatic rollback on errors
yt issues batch create --file issues.csv --rollback-on-error

Batch Update Issues

Update multiple issues from a CSV or JSON file.

yt issues batch update --file INPUT_FILE [OPTIONS]
Options:

  • -f, --file PATH - Path to CSV or JSON file containing update data (required)

  • --dry-run - Validate and preview operations without executing them

  • --continue-on-error - Continue processing after errors (default: true)

  • --save-failed PATH - Save failed operations to specified file for retry

CSV File Format: The CSV file should include issue_id and any fields to update:

issue_id,summary,description,state,type,priority,assignee
FPU-1,Updated summary,,In Progress,,High,
FPU-2,,Updated description text,Done,,,john.doe

JSON File Format: The JSON file should contain an array of update objects:

[
  {
    "issue_id": "FPU-1",
    "summary": "Updated summary",
    "state": "In Progress",
    "priority": "High"
  },
  {
    "issue_id": "FPU-2",
    "description": "Updated description text",
    "state": "Done",
    "assignee": "john.doe"
  }
]

Examples:

# Update issues from CSV file
yt issues batch update --file updates.csv

# Dry run to preview updates
yt issues batch update --file updates.csv --dry-run

# Update with error handling
yt issues batch update --file updates.csv --save-failed failed.csv

Validate Batch Files

Validate a batch operation file without executing operations.

yt issues batch validate --file INPUT_FILE --operation OPERATION
Arguments:

  • --file PATH - Path to CSV or JSON file to validate (required)

  • --operation [create|update] - Type of operation to validate for (required)

Examples:

# Validate a file for batch create
yt issues batch validate --file issues.csv --operation create

# Validate a file for batch update
yt issues batch validate --file updates.json --operation update

Generate Template Files

Generate template files for batch operations.

yt issues batch templates [OPTIONS]
Options:

  • --format [csv|json] - Template format to generate (default: csv)

  • -o, --output-dir PATH - Directory to save template files (default: current directory)

Examples:

# Generate CSV templates in current directory
yt issues batch templates

# Generate JSON templates in specific directory
yt issues batch templates --format json --output-dir ./templates

Batch Operations Best Practices

File Preparation:

  • Always validate your files before running batch operations

  • Use dry-run mode to preview operations and catch potential issues

  • Keep backup copies of your data files

Error Handling:

  • Use --save-failed to capture failed operations for retry

  • Review error messages to understand why operations failed

  • Consider using --rollback-on-error for create operations when consistency is critical

Performance:

  • Batch operations are faster than individual commands for large datasets

  • Progress bars show real-time status and estimated completion time

  • Operations are logged for audit trail and troubleshooting

Data Quality:

  • Ensure project IDs, usernames, and field values are valid before processing

  • Use consistent formatting for dates, priorities, and other field values

  • Remove empty rows and columns from CSV files to avoid validation errors

Workflow Integration:

  • Generate templates to ensure consistent field mapping

  • Use validation commands in CI/CD pipelines for automated quality checks

  • Combine with scripts for complex data transformations before import

Authentication

All issue commands require authentication. Make sure you’re logged in:

yt auth login

Error Handling

The CLI provides detailed error messages for common issues:

  • Authentication errors - Check your login status with yt auth token --show

  • Permission errors - Verify you have access to the project and required permissions

  • Invalid issue IDs - Ensure the issue exists and you have access to view it

  • API errors - Network issues or YouTrack server problems

Best Practices

Issue Creation:

  • Use descriptive summaries that clearly identify the problem or request

  • Include detailed descriptions with steps to reproduce for bugs

  • Set appropriate priority and type to help with organization

Searching:

  • Use YouTrack’s query language for complex searches

  • Combine multiple filters for precise results

  • Save frequently used queries as project saved searches in the web interface

Comments:

  • Use comments to track progress and communicate with team members

  • Include relevant context and links to related information

  • Update issue status when commenting on resolution

Attachments:

  • Upload screenshots, logs, and relevant files to provide context

  • Use descriptive filenames for easier identification

  • Consider file size limits and compress large files when necessary

Advanced Usage

Bulk Operations: For bulk operations, combine CLI commands with shell scripting:

# Update multiple issues
for issue in PROJ-123 PROJ-124 PROJ-125; do
    yt issues update $issue -s "Resolved"
done

Integration with Scripts: Use JSON output for integration with other tools:

# Get issue data for processing
yt issues list -p PROJ-1 --format json | jq '.[] | select(.priority.name == "High")'

Automation: Combine with CI/CD pipelines for automated issue management:

# Create issue from build failure
yt issues create PROJ-1 "Build failed in $BRANCH" -d "Build log: $BUILD_LOG" -t Bug -p High

See Also