Command Aliases

YouTrack CLI provides convenient aliases for commonly used commands to improve usability and reduce typing. This document describes all available command aliases and how to use them effectively.

Overview

Command aliases allow you to use shorter command names for frequently used operations. For example, instead of typing yt issues list, you can simply use yt i l.

Main Command Aliases

The following aliases are available for the main command groups:

Main Command Aliases

Alias

Full Command

Description

i

issues

Issue management commands

a

articles

Knowledge base article commands

p

projects

Project management commands

u

users

User management commands

t

time

Time tracking commands

b

boards

Agile board commands

c, cfg

config

Configuration management

login

auth

Authentication commands

Global Shortcuts

YouTrack CLI provides global shortcuts for the most common operations (Issue #345):

Global Shortcuts

Shortcut

Equivalent Command

Description

ls

issues list

List issues (most common operation)

new

issues create

Create a new issue (most common creation)

Usage Examples:

# List all issues
yt ls

# List your assigned issues
yt ls --assignee me

# List issues in a specific project
yt ls --project DEMO

# Create a new issue
yt new DEMO "Fix login bug"

# Create a bug with details
yt new DEMO "Login fails" --type Bug --assignee john.doe

User-Defined Aliases

In addition to built-in aliases, you can create your own custom aliases for frequently used commands (Issue #345).

Managing Custom Aliases

Use the yt alias command group to manage your custom aliases:

# List all aliases (built-in and custom)
yt alias list

# Add a custom alias
yt alias add myissues "issues list --assignee me"

# Show what an alias does
yt alias show myissues

# Remove a custom alias
yt alias remove myissues

Custom Alias Examples:

# Create shortcuts for common workflows
yt alias add bugs "issues list --type Bug --state Open"
yt alias add mybugs "issues list --type Bug --assignee me"
yt alias add quickbug "issues create --type Bug"

# Use your custom aliases
yt bugs                    # List all open bugs
yt mybugs                  # List bugs assigned to you
yt quickbug DEMO "Title"   # Create a bug quickly

Alias Rules:

  • Custom aliases take precedence over built-in aliases

  • Aliases cannot conflict with existing command names

  • Aliases are stored in your configuration file

  • Complex commands with arguments and options are supported

Flatter Command Alternatives

YouTrack CLI provides flatter alternatives to deeply nested commands for improved usability. These commands reduce the number of levels you need to type while maintaining full backward compatibility.

Flatter Command Alternatives

Flatter Command

Original Nested Command

Description

burndown

reports burndown

Generate burndown reports

velocity

reports velocity

Generate velocity reports

groups

admin user-groups

Manage user groups and permissions

settings

admin global-settings

Manage global YouTrack settings

audit

security audit

View command audit log

Subcommand Aliases

Within the issues command group, additional aliases are available for common operations:

Issues Subcommand Aliases

Alias

Full Command

Description

c, new

create

Create a new issue

l, ls

list

List issues

u, edit

update

Update an existing issue

s, find

search

Search for issues

d, del, rm

delete

Delete an issue

Usage Examples

Here are practical examples showing how to use aliases effectively:

Basic Operations

Create a new issue:

# Using full commands
yt issues create PROJECT-123 "Fix login bug"

# Using global shortcut (new in Issue #345)
yt new PROJECT-123 "Fix login bug"

# Using command group aliases
yt i c PROJECT-123 "Fix login bug"
yt i new PROJECT-123 "Fix login bug"

List issues:

# Using full commands
yt issues list --assignee me

# Using global shortcut (new in Issue #345)
yt ls --assignee me

# Using command group aliases
yt i l --assignee me
yt i ls --assignee me

Search for issues:

# Using full commands
yt issues search "priority:Critical"

# Using aliases
yt i s "priority:Critical"
yt i find "priority:Critical"

Configuration Management

# Using full commands
yt config set OUTPUT_FORMAT json
yt config get OUTPUT_FORMAT

# Using aliases
yt c set OUTPUT_FORMAT json
yt cfg get OUTPUT_FORMAT

Authentication

# Using full commands
yt auth login

# Using aliases
yt login

Project Management

# Using full commands
yt projects list

# Using aliases
yt p list

Time Tracking

# Using full commands
yt time log ISSUE-123 "2h 30m" --description "Fixed the bug"

# Using aliases
yt t log ISSUE-123 "2h 30m" --description "Fixed the bug"

Flatter Commands

# Reports - Traditional vs Flatter
yt reports burndown PROJECT-123 --sprint "Sprint 1"
yt burndown PROJECT-123 --sprint "Sprint 1"

yt reports velocity PROJECT-123 --sprints 5
yt velocity PROJECT-123 --sprints 5

# User Groups - Traditional vs Flatter
yt admin user-groups create "Team Lead" --description "Team leadership role"
yt groups create "Team Lead" --description "Team leadership role"

yt admin user-groups list
yt groups list

# Settings - Traditional vs Flatter
yt admin global-settings get --name system.timeZone
yt settings get --name system.timeZone

yt admin global-settings set timeout 30
yt settings set timeout 30

# Audit Log - Traditional vs Flatter
yt security audit --limit 25 --format json
yt audit --limit 25 --format json

Complex Workflows

You can chain aliases for even more efficient workflows:

Daily Issue Management:

# Check your assigned issues (using global shortcut)
yt ls --assignee me --state Open

# Or using command group alias
yt i l --assignee me --state Open

# Create a new bug report (using global shortcut)
yt new WEB-123 "Mobile login issue" --type Bug --priority High

# Or using command group alias
yt i c WEB-123 "Mobile login issue" --type Bug --priority High

# Update issue status
yt i u ISSUE-456 --state "In Progress"

# Log work time
yt t log ISSUE-456 "1h 30m" --description "Initial investigation"

Custom Alias Workflows:

# Set up custom aliases for your workflow
yt alias add mywork "issues list --assignee me --state Open"
yt alias add sprint "issues list --project DEMO --sprint current"
yt alias add bug "issues create --type Bug"

# Use your custom aliases
yt mywork                           # Check your work
yt sprint                           # Check current sprint
yt bug PROJECT-123 "Title"          # Create a bug quickly

Configuration and Setup:

# Quick authentication
yt login

# Configure output format
yt c set OUTPUT_FORMAT table

# List current configuration
yt c list

Flatter Command Workflows:

# Daily reporting workflow
yt burndown PROJECT-123                    # Quick burndown check
yt velocity PROJECT-123 --sprints 3        # Check team velocity

# Administrative tasks
yt groups create "QA Team"                 # Create user group
yt settings get --name system.timeZone     # Check timezone setting
yt audit --limit 10                       # Review recent actions

Help and Discovery

All aliases work with the --help flag to show command documentation:

# Get help for issues commands
yt i --help

# Get help for creating issues
yt i c --help

# Get help for configuration
yt c --help

The main help command also lists all available aliases:

yt --help

Best Practices

  1. Start with Full Commands: When learning, use full command names to understand the structure.

  2. Use Aliases for Frequent Operations: Once comfortable, switch to aliases for commands you use often.

  3. Mix and Match: You can combine full commands and aliases as needed:

    yt i create PROJECT-123 "Title"  # Mix of alias and full command

  4. Shell Completion: Aliases work with shell completion, making them even faster to use.

  5. Documentation: When sharing commands with others, consider using full names for clarity in documentation.

Shell Completion

Aliases are fully supported by the shell completion system. After setting up completion for your shell:

# Generate completion for bash
yt completion bash --install

# Generate completion for zsh
yt completion zsh --install

# Generate completion for fish
yt completion fish --install

You can use tab completion with aliases just like with full commands:

yt i <TAB>       # Shows issues subcommands
yt i c <TAB>     # Shows create command options
yt c s<TAB>      # Completes to "set"

Migration Guide

If you’re upgrading from a version without aliases or flatter commands, your existing commands will continue to work unchanged. All enhancements are additive and don’t replace existing functionality.

You can gradually adopt new command patterns at your own pace:

  1. Continue using full commands in scripts and documentation

  2. Start using aliases for interactive command-line work

  3. Try flatter commands for frequently used nested operations

  4. Update your muscle memory over time

Flatter Command Migration Examples:

# Old (still works)              # New flatter alternative
yt reports burndown PROJECT      yt burndown PROJECT
yt admin user-groups create      yt groups create
yt security audit               yt audit

Troubleshooting

If aliases don’t work as expected:

  1. Check Version: Ensure you’re using a version that supports aliases (v0.3.0+) and user-defined aliases (v0.10.0+)

  2. Verify Installation: Run yt --help to see if aliases are listed

  3. Clear Cache: If using shell completion, you may need to restart your shell or reload completion

  4. Conflict Resolution: If an alias conflicts with another command, the original command takes precedence

  5. Custom Alias Issues:

    • Run yt alias list to see all available aliases

    • Check if your custom alias conflicts with existing commands

    • Verify alias syntax with yt alias show <alias-name>

    • Custom aliases are stored in ~/.config/youtrack-cli/.env as ALIAS_<name>=<command>

  6. Alias Not Found: If a custom alias isn’t working, it may have been removed or the configuration file may be corrupted. Use yt alias add to recreate it.

For additional help, see the Troubleshooting guide or file an issue on GitHub.