Setup Command

The yt setup command provides an interactive setup wizard for first-time configuration of YouTrack CLI. This command guides you through configuring your YouTrack URL, authentication, and basic preferences to get you up and running quickly.

Overview 

The setup command simplifies initial CLI configuration by:

Guiding you through YouTrack server connection configuration
Setting up authentication credentials securely
Configuring basic CLI preferences and defaults
Validating your configuration to ensure everything works correctly
Providing helpful tips and best practices for CLI usage

Base Command 

yt setup [OPTIONS]

Command Options 

Options:

--skip-validation - Skip connection validation during setup
-h, --help - Show help message and exit

Examples:

# Run the interactive setup wizard
yt setup

# Setup without validating the connection (useful for offline setup)
yt setup --skip-validation

Setup Process 

Interactive Configuration 

The setup wizard will guide you through several configuration steps:

1. YouTrack Server Configuration:

YouTrack instance URL (e.g., https://youtrack.yourcompany.com)
Server connection validation and testing
SSL/TLS configuration if required

2. Authentication Setup:

Authentication method selection (token-based recommended)
Credential entry and secure storage
Authentication testing and verification

3. Basic Preferences:

Default output format preferences
Color and display options
Basic workflow preferences

4. Validation and Testing:

Connection testing to verify server accessibility
Authentication verification
Basic API functionality testing

Configuration Validation 

By default, the setup wizard validates your configuration:

# Standard setup with validation
yt setup

The validation process includes:

Network Connectivity: Testing connection to your YouTrack instance
Authentication: Verifying credentials and permissions
API Access: Testing basic API functionality
Configuration: Ensuring all settings are properly saved

Skipping Validation 

You can skip validation during setup if needed:

# Setup without validation (useful for offline environments)
yt setup --skip-validation

Use cases for skipping validation:

Offline Setup: Configuring CLI when YouTrack server is temporarily unavailable
Network Restrictions: Setting up in environments with limited connectivity
Batch Configuration: Automated setup scripts where validation is handled separately
Testing Configurations: Setting up test configurations without live connections

First-Time Setup Workflow 

Initial Installation 

After installing YouTrack CLI, start with the setup command:

# First-time setup
yt setup

The wizard will walk you through:

Welcome and Introduction * Overview of the setup process * Information about what will be configured
Server Configuration * YouTrack server URL input * Connection testing (unless skipped) * SSL certificate validation if needed
Authentication Configuration * Token-based authentication setup (recommended) * Secure credential storage * Authentication testing
Preference Configuration * Default project selection (if applicable) * Output format preferences * Display and color options
Completion and Verification * Configuration summary * Test commands to verify setup * Next steps and usage tips

Post-Setup Verification 

After completing setup, verify your configuration:

# Test authentication
yt auth status

# Test basic functionality
yt projects list

# Check configuration
yt config show

Configuration Storage 

Secure Credential Storage 

The setup wizard ensures secure handling of your credentials:

Local Storage: Credentials are stored locally on your system
Encryption: Sensitive data is encrypted using system-appropriate methods
Access Control: Configuration files have restricted file permissions
No Transmission: Credentials are never transmitted except for authentication

Configuration File Locations 

Setup creates configuration files in standard locations:

Linux/macOS: ~/.config/youtrack-cli/
Windows: %APPDATA%\youtrack-cli\

The configuration includes:

Connection Settings: Server URL and connection parameters
Authentication: Encrypted credential storage
User Preferences: Default options and display settings
Cache Configuration: Local cache settings for performance

Reconfiguration and Updates 

Running Setup Again 

You can run setup multiple times to update your configuration:

# Reconfigure existing setup
yt setup

The wizard will:

Detect Existing Configuration: Show current settings for reference
Allow Updates: Let you modify any configuration option
Preserve Settings: Keep settings you don’t want to change
Validate Changes: Test new configuration before saving

Partial Reconfiguration 

For specific configuration changes, consider these alternatives to full setup:

# Update authentication only
yt auth login

# Modify specific configuration settings
yt config set server.url https://new-youtrack.com

# Update display preferences
yt config set output.format json

Integration with Other Commands 

Authentication Integration 

Setup works seamlessly with authentication commands:

# Setup includes authentication configuration
yt setup

# Later, you can update authentication separately
yt auth login --token new-token

# Check authentication status anytime
yt auth status

Configuration Management 

Setup integrates with configuration management:

# Setup creates initial configuration
yt setup

# View and modify configuration later
yt config show
yt config set key value

# Export configuration for backup
yt config export config-backup.json

Automation and Scripting 

Automated Setup 

For automated environments, use non-interactive setup:

#!/bin/bash
# Automated setup script

# Set environment variables for automated configuration
export YOUTRACK_URL="https://youtrack.company.com"
export YOUTRACK_TOKEN="your-api-token"

# Run setup with validation skipped for automation
yt setup --skip-validation

# Verify setup completed successfully
yt auth status

CI/CD Integration 

Integrate setup into CI/CD pipelines:

# GitHub Actions example
- name: Setup YouTrack CLI
  run: |
    yt setup --skip-validation
    yt auth login --token ${{ secrets.YOUTRACK_TOKEN }} --base-url ${{ vars.YOUTRACK_URL }}

Docker Container Setup 

For containerized environments:

# Dockerfile example
FROM python:3.11-slim
RUN pip install youtrack-cli

# Copy pre-configured setup
COPY youtrack-config.json /root/.config/youtrack-cli/config.json

# Verify setup
RUN yt auth status

Best Practices 

Initial Setup:

Run setup in a secure environment to protect credential entry
Use strong, unique tokens for authentication
Test configuration thoroughly after initial setup

Security Considerations:

Regularly rotate authentication tokens
Keep configuration files secure with appropriate permissions
Use enhanced security mode for sensitive environments

Team Environments:

Document your YouTrack server configuration for team members
Provide setup instructions specific to your environment
Consider creating setup automation for consistent team configuration

Maintenance:

Review and update configuration periodically
Test configuration after YouTrack server updates
Keep backup copies of working configurations

Troubleshooting 

Common Setup Issues 

Connection Problems:

Verify YouTrack server URL is correct and accessible
Check network connectivity and firewall settings
Ensure SSL certificates are valid if using HTTPS

Authentication Issues:

Verify token is valid and has appropriate permissions
Check that token hasn’t expired
Ensure user account associated with token is active

Configuration Problems:

Check file permissions on configuration directory
Ensure sufficient disk space for configuration files
Verify environment variables if using automated setup

Setup Validation Failures 

If setup validation fails:

# Run setup with validation skipped to complete configuration
yt setup --skip-validation

# Then diagnose issues separately
yt auth status
yt projects list --debug

Recovery from Failed Setup 

If setup fails or becomes corrupted:

# Remove existing configuration
rm -rf ~/.config/youtrack-cli/

# Start fresh setup
yt setup

# Or restore from backup
cp backup-config.json ~/.config/youtrack-cli/config.json