Administrative Command Group

The yt admin command group provides comprehensive administrative capabilities for YouTrack system management. These commands require administrative privileges and handle system-wide settings, maintenance, and user management.

Overview 

YouTrack administrative operations manage system-wide configurations, user groups, custom fields, and system maintenance. The admin command group allows you to:

Manage global YouTrack settings and configuration
Handle license information and usage monitoring
Perform system maintenance operations
Manage user groups and permissions
Configure custom fields across projects
Monitor system health and diagnostics

Warning

Administrative commands require YouTrack administrator privileges. Users without sufficient permissions will receive appropriate error messages.

Base Command 

yt admin [OPTIONS] COMMAND [ARGS]...

Global Settings Management 

Note

The global-settings commands have been deprecated and are no longer available. Use the global-settings list command to view settings.

global-settings list 

List all global YouTrack settings.

yt admin global-settings list

Examples:

# List all global settings
yt admin global-settings list

License Management 

Note

The license show command has been deprecated and is no longer available.

license usage 

Show detailed license usage statistics and capacity information.

yt admin license usage

Examples:

# Show license usage statistics
yt admin license usage

# Monitor license utilization
yt admin license usage

System Maintenance 

maintenance 

Perform system maintenance operations and administrative tasks.

yt admin maintenance [OPTIONS] COMMAND [ARGS]...

Description:

The maintenance command group provides access to system maintenance operations and administrative utilities for YouTrack instances. This command serves as an entry point for various maintenance tasks that may be available depending on your YouTrack version and configuration.

Examples:

# Access maintenance operations
yt admin maintenance

# View available maintenance commands
yt admin maintenance --help

Note

Specific maintenance operations may vary depending on your YouTrack version and configuration. Use yt admin maintenance --help to see all available maintenance commands.

Note

The maintenance clear-cache command has been deprecated and is no longer available. Cache management must be performed through:

The YouTrack administrative UI
Server restart procedures
Direct server access

Please consult your YouTrack administrator or the JetBrains support team for cache management.

System Health Monitoring 

health check 

Run comprehensive system health diagnostics and display system status.

yt admin health check

Examples:

# Run health diagnostics
yt admin health check

# Regular system health monitoring
yt admin health check

# Pre-maintenance health check
yt admin health check

User Groups Management 

user-groups list 

List all user groups in the YouTrack system with filtering options.

yt admin user-groups list [OPTIONS]

Options:

Option	Type	Description
`--fields, -f`	string	Comma-separated list of fields to return

Examples:

# List all user groups
yt admin user-groups list

# List groups with specific fields
yt admin user-groups list --fields "id,name,description,users(login)"

# List groups with user information
yt admin user-groups list --fields "id,name,description,users(fullName)"

user-groups create 

Create a new user group with specified settings.

yt admin user-groups create NAME [OPTIONS]

Arguments:

NAME - The name of the new user group (required)

Options:

Option	Type	Description
`--description, -d`	string	Group description

Examples:

# Create a basic user group
yt admin user-groups create "DevOps Team"

# Create a group with description
yt admin user-groups create "QA Team" --description "Quality Assurance Team"

# Create project-specific groups
yt admin user-groups create "Project Alpha Team" --description "Alpha project development team"

Custom Fields Management 

fields list 

List all custom fields configured across YouTrack projects.

yt admin fields list [OPTIONS]

Options:

Option	Type	Description
`--fields, -f`	string	Comma-separated list of fields to return

Examples:

# List all custom fields
yt admin fields list

# List fields with specific information
yt admin fields list --fields "id,name,fieldType(presentation),isPrivate"

# List field types and usage
yt admin fields list --fields "name,fieldType(presentation),projects(name)"

Internationalization (i18n) Management 

i18n list 

List available locales for internationalization. This command is an alias for yt admin locale list.

yt admin i18n list

Examples:

# List all available locales
yt admin i18n list

# Same functionality as locale list
yt admin locale list

Note

This command provides the same functionality as yt admin locale list for consistency with other i18n commands.

Administrative Features 

Global Settings 

System Configuration: Manage server-wide settings including performance, security, and feature configurations.
Authentication Settings: Configure authentication methods, session timeouts, and security policies.
Email Configuration: Set up email servers, notification templates, and delivery settings.
Performance Tuning: Adjust system performance parameters and resource limits.

License Management 

License Information: View license details including expiration dates, feature limits, and user capacity.
Usage Monitoring: Track license utilization and capacity planning.
Compliance Tracking: Monitor license compliance and usage patterns.

System Maintenance 

Cache Management: Note: Cache clearing is not available through the REST API. Use the YouTrack administrative UI or server-side tools for cache management.
Health Monitoring: Comprehensive system health checks and diagnostics.
Performance Optimization: Tools for system performance analysis and optimization.

User and Group Management 

User Groups: Create and manage user groups for permission and access control.
Permission Management: Configure group-based permissions and access rights.
Organizational Structure: Set up user groups that reflect organizational hierarchy.

Custom Fields 

Field Management: View and manage custom fields across all projects.
Field Configuration: Monitor field usage and configuration across the system.
Data Consistency: Ensure custom field consistency across projects.

Common Administrative Workflows 

System Health Monitoring 

# Daily health check routine
echo "=== Daily YouTrack Health Check ==="
echo "Date: $(date)"
echo ""

# Check system health
yt admin health check

# Check license status
echo ""
echo "=== License Status ==="
yt admin license usage

# Check license usage
echo ""
echo "=== License Usage ==="
yt admin license usage

Regular Maintenance 

# Weekly maintenance routine
echo "=== Weekly YouTrack Maintenance ==="

# Note: Cache clearing is not available through the REST API
echo "Cache clearing must be done through the YouTrack UI or server tools"
# Cache clearing commands have been deprecated

# Health check after maintenance
echo "Post-maintenance health check..."
yt admin health check

echo "Maintenance completed at $(date)"

User Group Management 

# Set up new project team
PROJECT_NAME="Alpha"

# Create project-specific groups
yt admin user-groups create "${PROJECT_NAME} Developers" \
  --description "Development team for ${PROJECT_NAME} project"

yt admin user-groups create "${PROJECT_NAME} Testers" \
  --description "QA team for ${PROJECT_NAME} project"

yt admin user-groups create "${PROJECT_NAME} Managers" \
  --description "Project managers for ${PROJECT_NAME} project"

# List created groups
yt admin user-groups list --fields "name,description"

System Configuration 

# Configure system settings for new installation
echo "Configuring YouTrack system settings..."

# Note: Global settings configuration commands have been deprecated
echo "System settings must be configured through the YouTrack web interface"

# Verify configuration
echo "Verifying configuration..."
yt admin global-settings list

License Monitoring 

#!/bin/bash
# License monitoring and alerting script

echo "=== License Monitoring Report ==="
echo "Generated: $(date)"
echo ""

# Get license information
USAGE_INFO=$(yt admin license usage)

echo "$USAGE_INFO"

# Alert if usage is high (example threshold: 80%)
# This would need proper parsing of the actual output format
echo ""
echo "=== Usage Analysis ==="
echo "License monitoring completed"

Best Practices 

Regular Monitoring: Perform regular health checks and license monitoring.
Maintenance Scheduling: Schedule maintenance operations during low-usage periods.
Permission Management: Use groups for permission management rather than individual assignments.
Documentation: Document all administrative changes and configurations.
Backup Before Changes: Always backup configurations before making changes.
Testing: Test administrative changes in non-production environments first.
Monitoring: Set up monitoring for license usage and system health.
Security: Follow security best practices for administrative access.
Change Management: Use proper change management processes for system modifications.
Capacity Planning: Monitor usage trends for capacity planning and license management.

Security Considerations 

Administrative Access 

Limited Access: Restrict administrative access to authorized personnel only
Audit Trail: Maintain audit logs of administrative actions
Role Separation: Separate development and administrative responsibilities
Regular Review: Regularly review and update administrative permissions

System Security 

Setting Validation: Validate all configuration changes for security implications
Secure Defaults: Use secure default values for system settings
Regular Updates: Keep system configurations current with security best practices
Access Monitoring: Monitor administrative access and actions

Troubleshooting 

Common Issues and Solutions 

Permission Denied Errors

Verify administrative privileges and check authentication status.

Setting Not Found

Check setting key spelling and availability in your YouTrack version.

Cache Clear Not Available

The clear-cache command returns an error explaining that cache clearing is not available through the YouTrack REST API. Use the administrative UI or server-side tools instead.

Group Creation Failures

Check for naming conflicts and permission requirements.

Health Check Issues

Review system logs and resource availability.

Health Check 404 Errors

If the health check command returns a 404 error, this may indicate:

Your YouTrack version doesn’t support the system settings endpoint
The API endpoint has changed in your YouTrack version
Your YouTrack instance has a different API configuration

The command will automatically try fallback endpoints and provide specific guidance based on the error type.

System Diagnostics 

# Administrative troubleshooting workflow
echo "=== YouTrack Administrative Diagnostics ==="

# Check authentication and permissions
echo "1. Authentication check..."
if yt admin health check > /dev/null 2>&1; then
  echo "✅ Administrative access verified"
else
  echo "❌ Administrative access failed"
  exit 1
fi

# Check system health
echo "2. System health check..."
yt admin health check

# Check license status
echo "3. License status..."
yt admin license usage

echo "Diagnostics completed"

Error Recovery 

# Error recovery procedures
echo "=== Administrative Error Recovery ==="

# Note: Cache clearing is not available through the REST API
echo "Cache management must be done through YouTrack UI or server tools"
# Manual intervention required for cache clearing

# Verify system health after recovery
echo "Verifying system health..."
yt admin health check

# Check critical settings
echo "Verifying critical settings..."
yt admin global-settings list

Integration Examples 

Monitoring Integration 

#!/bin/bash
# Integration with monitoring systems

# Health check for monitoring system
if yt admin health check > /dev/null 2>&1; then
  echo "youtrack_health_status 1"
else
  echo "youtrack_health_status 0"
fi

# License usage metrics
# This would need proper parsing of actual output
echo "youtrack_license_usage_percent 75"

Backup Integration 

#!/bin/bash
# Backup administrative configurations

BACKUP_DIR="/backup/youtrack/$(date +%Y%m%d)"
mkdir -p "$BACKUP_DIR"

# Export global settings
yt admin global-settings list > "$BACKUP_DIR/global_settings.txt"

# Export user groups
yt admin user-groups list --fields "id,name,description" > "$BACKUP_DIR/user_groups.txt"

# Export custom fields
yt admin fields list > "$BACKUP_DIR/custom_fields.txt"

echo "Administrative backup completed: $BACKUP_DIR"

Automation Scripts 

#!/bin/bash
# Automated administrative maintenance

LOG_FILE="/var/log/youtrack_admin.log"

log() {
  echo "$(date): $1" | tee -a "$LOG_FILE"
}

log "Starting automated maintenance"

# Note: Cache clearing is not available through the REST API
log "Cache clearing must be done through YouTrack UI or server tools"
# Manual cache management required

# Health check
log "Running health check"
if yt admin health check > /dev/null 2>&1; then
  log "Health check passed"
else
  log "Health check failed - alerting administrators"
  # Send alert to administrators
fi

log "Automated maintenance completed"

Limitations 

Some administrative operations may require web interface access
Complex permission configurations may not be fully exposed via CLI
Advanced system configurations may require direct database access
Certain maintenance operations may require system restart