Users Command Group

The yt users command group provides comprehensive user management capabilities in YouTrack. This includes creating, listing, updating users, and managing their permissions and group memberships.

Overview 

YouTrack user management involves handling user accounts, permissions, and organizational structure. The users command group allows you to:

List and search for users
Create new user accounts with various settings
Update user information and status
Manage user permissions and group memberships
Handle user authentication settings
Control user access and security settings

Base Command 

yt users [OPTIONS] COMMAND [ARGS]...

User updates (email, full name, etc.) require proper Hub API configuration. On local or test YouTrack instances, these updates may not persist due to Hub API limitations. This is a known limitation of test environments.

permissions 

Manage user permissions and group memberships.

yt users permissions USER_ID [OPTIONS]

Arguments:

USER_ID - The username or user ID (required)

Options:

Option	Type	Description
`--action, -a`	choice	Permission action: add_to_group, remove_from_group (required)
`--group-id, -g`	string	Group ID for group operations

Examples:

# Add user to a group
yt users permissions USERNAME --action add_to_group --group-id developers

# Remove user from a group
yt users permissions USERNAME --action remove_from_group --group-id admins

# Manage multiple group memberships
yt users permissions USERNAME --action add_to_group --group-id testers
yt users permissions USERNAME --action add_to_group --group-id reviewers

groups 

Display groups that a user belongs to.

yt users groups USER_ID [OPTIONS]

Arguments:

USER_ID - The username or user ID to query (required)

Options:

Option	Type	Description
`--format`	choice	Output format: table, json (default: table)

Examples:

# View user's groups in table format
yt users groups john.doe

# View user's groups in JSON format
yt users groups admin --format json

# Check group memberships for a specific user
yt users groups project.manager

# Export user group data for reporting
yt users groups team.lead --format json > user_groups.json

roles 

Display roles assigned to a user.

yt users roles USER_ID [OPTIONS]

Arguments:

USER_ID - The username or user ID to query (required)

Options:

Option	Type	Description
`--format`	choice	Output format: table, json (default: table)

Examples:

# View user's roles in table format
yt users roles john.doe

# View user's roles in JSON format
yt users roles admin --format json

# Check role assignments for project lead
yt users roles project.lead

# Export role data for audit purposes
yt users roles security.admin --format json > user_roles.json

teams 

Display teams that a user is a member of.

yt users teams USER_ID [OPTIONS]

Arguments:

USER_ID - The username or user ID to query (required)

Options:

Option	Type	Description
`--format`	choice	Output format: table, json (default: table)

Examples:

# View user's teams in table format
yt users teams john.doe

# View user's teams in JSON format
yt users teams jane.smith --format json

# Check team memberships for developer
yt users teams developer.user

# Export team data for organizational chart
yt users teams manager.user --format json > user_teams.json

assign-role 

Assign a role to a user for access control and permission management.

yt users assign-role USER_ID ROLE_ID

Arguments:

USER_ID - The username or user ID to assign the role to (required)
ROLE_ID - The role identifier to assign to the user (required)

Description:

The assign-role command assigns the specified role to the user. Roles in YouTrack are typically project-specific and managed through Hub API. Roles define what permissions and access levels a user has within the system or specific projects.

Examples:

# Assign a role to a user
yt users assign-role john.doe developer-role-id

# Assign admin role to user
yt users assign-role admin system-admin

# Assign project-specific role
yt users assign-role project.manager project-lead-role

# Assign multiple roles to different users
yt users assign-role alice.developer dev-team-lead
yt users assign-role bob.tester qa-team-lead

Role Management:

Project Roles: Roles specific to individual projects with tailored permissions
System Roles: Global roles that apply across the entire YouTrack instance
Custom Roles: Organization-specific roles created for unique access patterns
Temporary Roles: Roles assigned for specific time periods or projects

Use Cases:

Granting project leadership permissions to team leads
Assigning specialized access for quality assurance roles
Managing administrative privileges for system administrators
Setting up role-based access control for compliance requirements

Note

Role assignments are managed through the Hub API and may have specific requirements depending on your YouTrack configuration. Ensure the role ID exists and is appropriate for the user’s responsibilities.

User Management Features 

User Account Management: Complete lifecycle management of user accounts including creation, updates, and status changes.
Security Controls: Password management, forced password changes, and account banning capabilities.
Group Membership: Manage user permissions through group memberships and role assignments.
Search and Discovery: Powerful search capabilities to find users by various criteria, including filtering by user status (active vs banned).
Bulk Operations: Support for managing multiple users efficiently.
Status Management: Control user account status including active, banned, and password change requirements.

User Account States 

Active Users: Normal user accounts with full access based on their permissions.
Banned Users: User accounts that are temporarily or permanently restricted from access.
Password Change Required: Users who must change their password on next login for security reasons.
New Users: Recently created accounts that may need initial setup or verification.

Common Workflows 

User Onboarding 

# Create new employee account
yt users create john.doe "John Doe" "john.doe@company.com" \
  --force-change-password

# Add to appropriate groups
yt users permissions john.doe --action add_to_group --group-id employees
yt users permissions john.doe --action add_to_group --group-id developers

# Verify user creation
yt users update john.doe --show-details

User Maintenance 

# Update user information
yt users update john.doe --full-name "John A. Doe"
yt users update john.doe --email "john.a.doe@company.com"

# Force password reset for security
yt users update john.doe --force-change-password

# View current user settings
yt users update john.doe --show-details

Security Management 

# Ban suspicious user account
yt users update suspicious.user --banned

# Force password change for security incident
yt users update affected.user --force-change-password

# Unban user after investigation
yt users update suspicious.user --unbanned

User Discovery and Reporting 

# Search for administrators
yt users list --query "admin"

# Find users by department or role
yt users list --query "developer"

# List only active users for current operations
yt users list --active-only

# Find active developers for team management
yt users list --active-only --query "developer"

# Export active user list for reporting
yt users list --active-only --format json --fields "login,fullName,email" > active_users.json

# Export all users with status for audit
yt users list --format json --fields "login,fullName,email,banned" > user_report.json

# List all users with detailed information
yt users list --fields "id,login,fullName,email,created,lastAccess,banned"

Permission Management 

# Add user to development team
yt users permissions developer.user --action add_to_group --group-id developers
yt users permissions developer.user --action add_to_group --group-id code-reviewers

# Remove user from administrative groups
yt users permissions former.admin --action remove_from_group --group-id administrators

# Manage project-specific permissions
yt users permissions project.lead --action add_to_group --group-id project-managers

Permission Analysis 

# Analyze user's current permissions
yt users groups john.doe
yt users roles john.doe
yt users teams john.doe

# Export complete permission audit for a user
yt users groups john.doe --format json > john_groups.json
yt users roles john.doe --format json > john_roles.json
yt users teams john.doe --format json > john_teams.json

# Quick permission check for multiple users
for user in alice bob charlie; do
  echo "=== Permissions for $user ==="
  yt users groups $user
  echo
done

# Verify user has required permissions before project assignment
yt users roles project.candidate
yt users groups project.candidate

Best Practices 

Secure Password Policies: Always use strong passwords and force password changes for new accounts.
Principle of Least Privilege: Grant users only the minimum permissions needed for their role.
Regular Audits: Periodically review user accounts and permissions for security compliance.
Group-Based Permissions: Use groups to manage permissions rather than individual assignments.
Account Lifecycle: Properly manage the full lifecycle from creation to deactivation.
Documentation: Maintain clear documentation of user roles and permission structures.
Security Monitoring: Monitor for suspicious activity and respond appropriately.
Consistent Naming: Use consistent naming conventions for usernames and groups.
Email Verification: Ensure email addresses are accurate for communication and password resets.
Deactivation Process: Have a clear process for handling user departures and account cleanup.

Security Considerations 

Password Management 

# Force password change for security
yt users update USERNAME --force-change-password

# Update password directly (use with caution)
yt users update USERNAME --password "new-secure-password"

Account Security 

# Temporarily ban suspicious account
yt users update SUSPICIOUS_USER --banned

# Investigate and then reactivate if appropriate
yt users update SUSPICIOUS_USER --unbanned

# Force password change after security incident
yt users update AFFECTED_USER --force-change-password

Access Control 

# Remove from sensitive groups
yt users permissions USERNAME --action remove_from_group --group-id administrators
yt users permissions USERNAME --action remove_from_group --group-id sensitive-project

# Add to restricted group
yt users permissions USERNAME --action add_to_group --group-id restricted-users

Output Formats 

Table Format (Default)

The default table format provides a clean view of user information:

┌──────────────┬─────────────────┬────────────────────────┬─────────┬─────────────────┐
│ Login        │ Full Name       │ Email                  │ Banned  │ Last Access     │
├──────────────┼─────────────────┼────────────────────────┼─────────┼─────────────────┤
│ john.doe     │ John Doe        │ john.doe@company.com   │ No      │ 2024-01-15      │
│ jane.smith   │ Jane Smith      │ jane.smith@company.com │ No      │ 2024-01-14      │
│ admin.user   │ Administrator   │ admin@company.com      │ No      │ 2024-01-15      │
└──────────────┴─────────────────┴────────────────────────┴─────────┴─────────────────┘

JSON Format 

JSON format provides structured data for automation:

[
  {
    "id": "1-1",
    "login": "john.doe",
    "fullName": "John Doe",
    "email": "john.doe@company.com",
    "banned": false,
    "created": "2024-01-01T10:00:00.000Z",
    "lastAccess": "2024-01-15T09:30:00.000Z",
    "forcePasswordChange": false
  }
]

Error Handling 

Common error scenarios and solutions:

Permission Denied: Ensure you have administrative privileges to manage users and permissions.
User Already Exists: Check if a user with the same login or email already exists in the system.
Invalid Email Format: Verify the email address follows proper email format standards.
Weak Password: Ensure passwords meet your organization’s security requirements.
Group Not Found: Verify the group ID exists and is accessible for permission management.
User Not Found: Confirm the username or user ID is correct and the user exists.
Banned User Operations: Some operations may be restricted on banned user accounts.

Integration Examples 

Bulk User Management 

#!/bin/bash
# Bulk user creation from CSV

while IFS=',' read -r login fullname email; do
  yt users create "$login" "$fullname" "$email" --force-change-password
  yt users permissions "$login" --action add_to_group --group-id employees
done < new_users.csv

User Audit Script 

#!/bin/bash
# Generate user audit report

echo "User Audit Report - $(date)"
echo "================================"

# List all users
yt users list --format json > users_audit.json

# Count active vs banned users
echo "Active users: $(jq '[.[] | select(.banned == false)] | length' users_audit.json)"
echo "Banned users: $(jq '[.[] | select(.banned == true)] | length' users_audit.json)"

# Users requiring password change
echo "Users requiring password change:"
jq -r '.[] | select(.forcePasswordChange == true) | .login' users_audit.json

Permission Cleanup 

# Remove departed employee from all sensitive groups
DEPARTED_USER="former.employee"

# Remove from administrative groups
yt users permissions "$DEPARTED_USER" --action remove_from_group --group-id administrators
yt users permissions "$DEPARTED_USER" --action remove_from_group --group-id project-managers

# Ban the account
yt users update "$DEPARTED_USER" --banned

Option	Type	Description
`--fields, -f`	string	Comma-separated list of user fields to return
`--top, -t`	integer	Maximum number of users to return
`--query, -q`	string	Search query to filter users
`--active-only`	flag	Show only active (non-banned) users
`--format`	choice	Output format: table, json (default: table)

Option	Type	Description
`--password, -p`	string	User password (will prompt securely if not provided; shows warning if provided via command line)
`--banned`	flag	Create user as banned (inactive)
`--force-change-password`	flag	Force password change on first login

Option	Type	Description
`--full-name, -n`	string	New full name
`--email, -e`	string	New email address
`--password, -p`	string	New password
`--banned/--unbanned`	flag	Ban or unban the user
`--force-change-password`	flag	Force password change on next login
`--show-details`	flag	Show detailed user information

Users Command Group

Overview 

Base Command 

User Management Commands 

list 

create 

update 

permissions 

groups 

roles 

teams 

assign-role 

User Management Features 

User Account States 

Common Workflows 

User Onboarding 

User Maintenance 

Security Management 

User Discovery and Reporting 

Permission Management 

Permission Analysis 

Best Practices 

Security Considerations 

Password Management 

Account Security 

Access Control 

Output Formats 

Table Format (Default)

JSON Format 

Error Handling 

Integration Examples 

Bulk User Management 

User Audit Script 

Permission Cleanup 

See Also 