Authentication Command Group

The yt auth command group provides comprehensive authentication management for YouTrack CLI. Handle login, logout, token management, and credential verification.

Overview 

YouTrack CLI authentication is based on API tokens and manages secure access to your YouTrack instance. The auth command group allows you to:

Authenticate with YouTrack using API tokens
Manage and update authentication credentials
Verify and test authentication status
Securely store and retrieve credentials
Handle logout and credential cleanup

All commands in the CLI require proper authentication to access YouTrack resources.

Base Command 

yt auth [OPTIONS] COMMAND [ARGS]...

Authentication Commands 

login 

Authenticate with YouTrack and save credentials for subsequent CLI usage.

yt auth login [OPTIONS]

Options:

Option	Type	Description
`--base-url, -u`	string	YouTrack instance URL (will prompt if not provided)
`--token, -t`	string	YouTrack API token (will prompt securely if not provided)
`--username, -n`	string	Username for reference (optional)
`--no-verify-ssl`	flag	Disable SSL certificate verification (use with caution for self-signed certificates)

Examples:

# Interactive login (prompts for URL and token)
yt auth login

# Login with pre-filled URL
yt auth login --base-url https://yourdomain.youtrack.cloud

# Login with URL and username
yt auth login --base-url https://company.youtrack.cloud --username john.doe

# Completely non-interactive (not recommended for security)
yt auth login --base-url https://company.youtrack.cloud --token YOUR_API_TOKEN

# Login with self-signed SSL certificate
yt auth login --base-url https://internal.youtrack.local --no-verify-ssl

Security Notes:

API tokens are prompted securely and hidden during input
Sensitive credentials (tokens) are stored in system keyring with encryption
Non-sensitive configuration (base URL, username, SSL preference) is stored in .env file
Never include tokens in command history or scripts
Use environment variables or secure prompts for automation

logout 

Clear stored authentication credentials and log out of YouTrack.

yt auth logout

Examples:

# Logout with confirmation prompt
yt auth logout

# The command will ask for confirmation before clearing credentials
# Responds to "Are you sure you want to logout?" prompt

Behavior:

Removes stored authentication credentials
Clears cached authentication data
Requires confirmation to prevent accidental logout
Safe to run multiple times (no error if already logged out)

token 

Manage API tokens including viewing current token (masked) and updating credentials.

yt auth token [OPTIONS]

Options:

Option	Type	Description
`--show`	flag	Show current token (masked for security)
`--update`	flag	Update the current API token

Examples:

# Show current authentication status and masked token
yt auth token --show

# Update API token (prompts for new token)
yt auth token --update

# Show help for token management
yt auth token

Token Display Format:

When using --show, tokens are displayed in masked format for security:

Current token: perm:abc12345...xyz789
Base URL: https://company.youtrack.cloud
Username: john.doe

Authentication Process 

Initial Setup 

Obtain API Token: Generate a permanent token in YouTrack web interface
Run Login Command: Use yt auth login to authenticate
Verify Credentials: CLI automatically verifies token validity
Store Securely: Credentials are stored in local configuration

Token Generation 

To generate an API token in YouTrack:

Login to YouTrack web interface
Go to your profile settings
Navigate to “Authentication” section
Create a new “Permanent Token”
Copy the token for CLI authentication

Token Permissions: Ensure your token has appropriate permissions for CLI operations:

Read access to projects and issues
Write access for creating/updating resources
Administrative access for admin commands (if needed)

Authentication Workflow 

# Step 1: Initial authentication
yt auth login --base-url https://company.youtrack.cloud

# Step 2: Verify authentication works
yt auth token --show

# Step 3: Test CLI functionality
yt projects list

# Step 4: Use CLI normally
yt issues list --assignee me

Security Features 

Credential Storage 

Dual Storage: Sensitive tokens stored in system keyring, configuration in ~/.config/youtrack-cli/.env
Encryption: Tokens encrypted in keyring using Fernet symmetric encryption
Access Control: Files have restricted permissions, keyring uses OS security
No Plaintext: Tokens never stored in plaintext, .env file shows “[Stored in keyring]” placeholder

Token Masking 

Display Security: Tokens and API keys masked when displayed (abc123...xyz789)
Log Safety: Tokens not exposed in command output or logs
History Protection: Tokens not stored in shell history
Config List Safety: API keys shown as masked or “[Stored in keyring]” in config list

Session Management 

Token Validation: Automatic verification of token validity
Refresh Handling: Proper handling of token expiration
Error Recovery: Clear error messages for authentication failures

Common Workflows 

Initial Setup Workflow 

# First-time setup
echo "Setting up YouTrack CLI authentication..."

# Login interactively
yt auth login

# Verify setup
yt auth token --show

# Test connection
yt projects list

echo "Authentication setup complete!"

Token Rotation Workflow 

# Periodic token rotation for security
echo "Rotating API token..."

# Generate new token in YouTrack web interface first
# Then update CLI credentials
yt auth token --update

# Verify new token works
yt auth token --show
yt projects list

echo "Token rotation complete!"

Team Setup Workflow 

# Setup script for team members
#!/bin/bash

echo "YouTrack CLI Team Setup"
echo "======================"
echo "Please have your API token ready"
echo ""

# Standard company YouTrack instance
yt auth login --base-url https://company.youtrack.cloud

# Verify setup
if yt projects list > /dev/null 2>&1; then
  echo "✅ Authentication successful!"
  echo "You can now use the YouTrack CLI"
else
  echo "❌ Authentication failed. Please check your token."
fi

Troubleshooting Authentication 

Authentication Verification 

# Check current authentication status
yt auth token --show

# Test authentication with simple command
yt projects list

# Verify token has correct permissions
yt users list

Token Issues 

# If token expired or invalid
yt auth token --update

# If completely broken, re-authenticate
yt auth logout
yt auth login

# Clear any cached credentials
rm ~/.config/youtrack-cli/.env
yt auth login

Connection Problems 

# Test basic connectivity
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://company.youtrack.cloud/api/admin/projects"

# Check YouTrack instance URL
yt auth token --show

# Re-authenticate with correct URL
yt auth logout
yt auth login --base-url https://correct.youtrack.cloud

SSL Certificate Issues 

# For self-signed certificates or internal CAs
yt auth login --base-url https://internal.youtrack.local --no-verify-ssl

# Test connectivity with SSL verification disabled
curl -k -H "Authorization: Bearer YOUR_TOKEN" \
     "https://internal.youtrack.local/api/admin/projects"

# Note: SSL verification setting is saved with credentials
# All subsequent API calls will use the same SSL verification setting

Error Handling 

Common error scenarios and solutions:

Invalid Token

Regenerate token in YouTrack web interface
Update credentials using yt auth token --update

Expired Token

Create new permanent token
Update CLI credentials

Wrong Base URL

Verify YouTrack instance URL
Re-authenticate with correct URL

Permission Denied

Check token permissions in YouTrack
Ensure token has required access levels

Network Issues

Verify connectivity to YouTrack instance
Check firewall and proxy settings

SSL Certificate Errors

For self-signed certificates: yt auth login --no-verify-ssl
For corporate CAs: Add CA certificate to system trust store
Warning: Only disable SSL verification on trusted networks

Corrupted Credentials

Clear stored credentials: yt auth logout
Re-authenticate: yt auth login

Configuration Files 

Credential Storage Location 

# Default credential storage
~/.config/youtrack-cli/.env

# Custom config file location
yt --config /path/to/custom.env auth login

Configuration Format 

The configuration file contains non-sensitive authentication data:

# Example structure (token stored separately in keyring)
YOUTRACK_BASE_URL=https://company.youtrack.cloud
YOUTRACK_API_KEY=[Stored in keyring]
YOUTRACK_USERNAME=john.doe
YOUTRACK_VERIFY_SSL=true

Custom Configuration 

# Use custom configuration file
yt --config /path/to/project.env auth login

# Environment-specific authentication
yt --config ~/.config/yt-dev.env auth login    # Development
yt --config ~/.config/yt-prod.env auth login   # Production

Security Best Practices 

Token Management 

Regular Rotation: Rotate tokens periodically for security
Minimal Permissions: Use tokens with minimal required permissions
Secure Generation: Generate tokens securely in YouTrack web interface
No Sharing: Never share tokens between users or systems

Storage Security 

File Permissions: Ensure config files have restricted permissions
Backup Security: Exclude credential files from backups
Access Control: Limit access to credential storage locations

Operational Security 

Environment Separation: Use different tokens for different environments
Audit Trail: Monitor token usage and access patterns
Incident Response: Have procedures for token compromise
Team Guidelines: Establish team standards for authentication

Automation and CI/CD 

Environment Variables 

# Set environment variables for automation
export YOUTRACK_BASE_URL="https://company.youtrack.cloud"
export YOUTRACK_TOKEN="perm:your_token_here"

# Use in scripts
yt --config <(echo "YOUTRACK_BASE_URL=$YOUTRACK_BASE_URL"; echo "YOUTRACK_TOKEN=$YOUTRACK_TOKEN") projects list

CI/CD Integration 

# GitHub Actions example
- name: Setup YouTrack CLI
  env:
    YOUTRACK_TOKEN: ${{ secrets.YOUTRACK_TOKEN }}
    YOUTRACK_BASE_URL: ${{ secrets.YOUTRACK_BASE_URL }}
  run: |
    echo "YOUTRACK_TOKEN=$YOUTRACK_TOKEN" > ~/.youtrack-cli.env
    echo "YOUTRACK_BASE_URL=$YOUTRACK_BASE_URL" >> ~/.youtrack-cli.env
    yt --config ~/.youtrack-cli.env projects list

Service Account Setup 

# Create service account token in YouTrack
# Use for automated systems and CI/CD

# Setup service account authentication
yt auth login \
  --base-url https://company.youtrack.cloud \
  --username service-account

# Test service account access
yt projects list

Integration Examples 

Script Authentication 

#!/bin/bash
# Automated script with authentication check

# Check if authenticated
if ! yt auth token --show > /dev/null 2>&1; then
  echo "Please authenticate first:"
  yt auth login
fi

# Continue with script logic
echo "Running automated tasks..."
yt projects list

Multi-Environment Setup 

#!/bin/bash
# Setup for multiple environments

ENVIRONMENTS=("dev" "staging" "prod")

for env in "${ENVIRONMENTS[@]}"; do
  echo "Setting up $env environment..."
  yt --config ~/.config/yt-${env}.env auth login \
    --base-url "https://${env}.youtrack.company.com"
done

Credential Backup 

#!/bin/bash
# Backup authentication configuration (be careful with security)

BACKUP_DIR="~/.youtrack-cli-backup"
mkdir -p "$BACKUP_DIR"

# Copy configuration (ensure secure storage)
cp ~/.config/youtrack-cli/.env "$BACKUP_DIR/auth-backup-$(date +%Y%m%d).env"

echo "Credentials backed up to $BACKUP_DIR"