Tutorial System

YouTrack CLI includes an interactive tutorial system designed to help new users learn the CLI through guided, hands-on experiences. The tutorial system covers essential workflows and best practices with step-by-step instructions.

Overview

The tutorial system provides:

  • Interactive Learning: Step-by-step guidance through common workflows

  • Progress Tracking: Automatic saving of tutorial progress with resume capability

  • Real-world Examples: Practical commands and scenarios you’ll use daily

  • Beginner-friendly: Clear explanations and helpful tips throughout

Available Tutorials

Setup Tutorial (setup)

Learn how to authenticate and configure YouTrack CLI for first use. This tutorial covers:

  • Understanding YouTrack CLI capabilities

  • Setting up authentication with API tokens

  • Verifying your connection

  • Configuring optional settings

Issues Tutorial (issues)

Master issue management with the CLI. This tutorial covers:

  • Understanding YouTrack issues

  • Listing and filtering issues

  • Creating new issues

  • Viewing detailed issue information

  • Updating issues and their status

Projects Tutorial (projects)

Learn to work with YouTrack projects effectively. This tutorial covers:

  • Understanding project structure

  • Exploring available projects

  • Viewing project details and configuration

  • Working with project-specific custom fields

Time Tracking Tutorial (time)

Master time tracking for project management. This tutorial covers:

  • Understanding time tracking concepts

  • Logging work time against issues

  • Viewing time entries and reports

  • Best practices for time tracking

Docker Tutorial (docker)

Set up a local YouTrack instance using Docker for hands-on learning. This tutorial covers:

  • Checking Docker availability and requirements

  • Downloading and starting a YouTrack container

  • Accessing the YouTrack Configuration Wizard with a one-time token

  • Completing the initial YouTrack setup (5-10 minutes)

  • Connecting the CLI to your local instance

  • Practicing with a real YouTrack environment

  • Managing and cleaning up the Docker resources

Requirements: Docker must be installed and running on your system. This tutorial creates a local YouTrack instance at http://localhost:8080 for learning purposes.

Initial Setup Time: The YouTrack configuration wizard typically takes 5-10 minutes to complete, including setting up an administrator account, configuring basic settings, and creating your first project.

Using the Tutorial System

List Available Tutorials

View all available tutorials and their progress:

yt tutorial list

Add the --show-progress flag to see detailed completion statistics:

yt tutorial list --show-progress

Run a Tutorial

Start a tutorial from the beginning:

yt tutorial run setup

Resume a tutorial from a specific step:

yt tutorial run issues --step 3

Reset and restart a tutorial:

yt tutorial run projects --reset

Manage Tutorial Progress

View detailed progress for all tutorials:

yt tutorial progress

Reset progress for a specific tutorial:

yt tutorial reset issues

Reset all tutorial progress:

yt tutorial reset --all

Provide Feedback

Share feedback about the tutorial system:

yt tutorial feedback

Tutorial Features

Interactive Navigation

During a tutorial, you can:

  • Next: Continue to the next step

  • Repeat: Review the current step again

  • Skip: Skip the current step and move forward

  • Quit: Exit the tutorial (progress is saved automatically)

Progress Persistence

  • Tutorial progress is automatically saved

  • You can safely exit and resume tutorials later

  • Progress is stored in ~/.config/youtrack-cli/tutorial_progress.json

  • Each tutorial tracks completed steps and current position

Step-by-Step Guidance

Each tutorial step includes:

  • Clear title and description

  • Detailed instructions

  • Example commands to try

  • Helpful tips and best practices

  • Troubleshooting guidance

Tips for Success

  1. Take Your Time: Tutorials are self-paced - don’t rush through them

  2. Try the Commands: Execute the example commands in your terminal

  3. Read the Tips: Each step includes helpful tips and best practices

  4. Use Real Data: When possible, work with real YouTrack projects and issues

  5. Ask Questions: Use the feedback command to report issues or suggestions

Troubleshooting

Tutorial Won’t Start

  • Ensure YouTrack CLI is properly installed

  • Check that you have the latest version

  • Try resetting the tutorial progress

Progress Not Saving

  • Verify write permissions to ~/.config/youtrack-cli/

  • Check available disk space

  • Try manually creating the config directory

Commands Not Working

  • Ensure you’re authenticated with yt auth login

  • Verify your YouTrack instance is accessible

  • Check that you have appropriate permissions

Docker Tutorial Issues

  • Docker not available: Install Docker Desktop and ensure it’s running

  • Port 8080 in use: Stop other services using the port or modify the tutorial to use a different port

  • Container won’t start: Check Docker logs with docker logs youtrack-tutorial

  • YouTrack takes too long to start: Initial startup can take 5-10 minutes, especially on slower systems

  • Permission denied: Ensure your user has Docker permissions (add to docker group on Linux)

  • Out of disk space: YouTrack image is ~1GB, ensure sufficient space available

  • Configuration Wizard URL not displayed: The tutorial automatically captures the wizard token from container logs and displays the complete URL

  • Wizard token expired: If you wait too long to access the URL, restart the container to get a new token

Advanced Usage

Custom Tutorial Content

While the built-in tutorials cover essential workflows, you can extend your learning by:

  • Exploring advanced command options with --help

  • Reading the full documentation

  • Experimenting with different YouTrack projects

  • Combining commands in scripts

Integration with Other Learning

The tutorial system complements other learning resources:

  • CLI help system (yt --help, yt COMMAND --help)

  • Online documentation

  • YouTrack API documentation

  • Community examples and scripts

Getting Help

If you need help with the tutorial system:

  1. Use yt tutorial --help for command reference

  2. Check the troubleshooting section above

  3. Report issues at https://github.com/ryancheley/yt-cli/issues

  4. Provide feedback with yt tutorial feedback

The tutorial system is designed to make learning YouTrack CLI enjoyable and effective. Take advantage of the interactive features and don’t hesitate to revisit tutorials as needed!