Configuration

YouTrack CLI can be configured through multiple methods, allowing you to customize its behavior to match your workflow.

Configuration Sources

YouTrack CLI reads configuration from multiple sources in this order (later sources override earlier ones):

Default values
Configuration file (~/.config/youtrack-cli/.env)
Environment variables
Command-line arguments

Configuration File

The configuration file is an environment file located at ~/.config/youtrack-cli/.env by default. You can specify a different location using the --config flag.

Creating the Configuration File:

The easiest way to set up configuration is through the yt auth login command, which will automatically create the configuration file. Alternatively, you can create it manually:

# Create configuration directory
mkdir -p ~/.config/youtrack-cli

# Create the .env configuration file
cat > ~/.config/youtrack-cli/.env << EOF
YOUTRACK_BASE_URL=https://yourcompany.youtrack.cloud
YOUTRACK_TOKEN=your-api-token-here
YOUTRACK_USERNAME=your-username
EOF

Configuration File Format:

# YouTrack instance settings (required)
YOUTRACK_BASE_URL=https://yourcompany.youtrack.cloud
YOUTRACK_TOKEN=perm:your-api-token-here
YOUTRACK_USERNAME=your-username

# Optional: Default project for commands
DEFAULT_PROJECT=PROJECT-ID

# Optional: Output format preference
OUTPUT_FORMAT=table

Authentication Methods

API Token (Recommended)

The most secure method is using an API token:

Generate a token in YouTrack: Profile > Account Security > API Tokens
Set it in configuration:

yt config set youtrack.token "your-api-token"

Or set the environment variable:

export YT_TOKEN="your-api-token"

Username/Password

For development or testing:

yt config set youtrack.username "your-username"
yt config set youtrack.password "your-password"

Or use environment variables:

export YT_USERNAME="your-username"
export YT_PASSWORD="your-password"

Environment Variables

All configuration options can be set via environment variables using the YT_ prefix:

export YT_URL="https://yourcompany.youtrack.cloud"
export YT_TOKEN="your-api-token"
export YT_DEFAULT_PROJECT="PROJECT-ID"
export YT_OUTPUT_FORMAT="json"
export YT_MAX_RESULTS="100"

Configuration Commands

View Configuration

View all current configuration:

yt config list

View specific configuration value:

yt config get youtrack.url

Set Configuration

Set configuration values:

yt config set youtrack.url "https://yourcompany.youtrack.cloud"
yt config set defaults.project "PROJECT-ID"
yt config set display.output_format "json"

Configuration Options Reference

YouTrack Connection

Option	Type	Description
`youtrack.url`	string	YouTrack instance URL
`youtrack.token`	string	API token for authentication
`youtrack.username`	string	Username for authentication
`youtrack.password`	string	Password for authentication
`youtrack.verify_ssl`	boolean	Verify SSL certificates (default: true). WARNING: Disabling SSL verification is insecure and should only be used in development environments.
`youtrack.timeout`	integer	Request timeout in seconds (default: 30)

Default Values

Option	Type	Description
`defaults.project`	string	Default project for new issues
`defaults.assignee`	string	Default assignee for new issues
`defaults.priority`	string	Default priority for new issues
`defaults.state`	string	Default state for new issues

Display Settings

Option	Type	Description
`display.output_format`	string	Output format: table, json, yaml (default: table)
`display.max_results`	integer	Maximum results to display (default: 50)
`display.show_colors`	boolean	Enable colored output (default: true)
`display.pager`	boolean	Use pager for long output (default: true)
`display.date_format`	string	Date format string (default: %Y-%m-%d %H:%M)

Theme Settings

YouTrack CLI supports comprehensive theme customization, allowing you to personalize the appearance of console output with built-in themes or create your own custom themes.

Option	Type	Description
`YOUTRACK_THEME`	string	Console theme: default, dark, light, or custom theme name (default: default)

Built-in Themes:

default: Standard theme with cyan info text, green success, and red errors
dark: High-contrast theme optimized for dark terminals with bright colors
light: Theme optimized for light terminals with darker text colors

Theme Management Commands:

YouTrack CLI provides comprehensive theme management through the yt config theme command group:

# List all available themes (built-in + custom)
yt config theme list

# Show current theme and preview
yt config theme current

# Set active theme
yt config theme set dark

# Create a new custom theme interactively
yt config theme create my-theme

# Create a theme based on an existing one
yt config theme create my-dark --base dark

# Delete a custom theme
yt config theme delete my-theme

# Export a theme to JSON file
yt config theme export dark my-dark-theme.json

# Import a theme from JSON file
yt config theme import my-theme.json

# Import with custom name
yt config theme import downloaded-theme.json my-custom-name

Setting a Theme:

There are multiple ways to set your active theme:

# Using theme command (recommended)
yt config theme set dark

# Using config command
yt config set YOUTRACK_THEME dark

# Via configuration file
echo "YOUTRACK_THEME=dark" >> ~/.config/youtrack-cli/.env

# Via environment variable
export YOUTRACK_THEME=light

# Test different themes temporarily
YOUTRACK_THEME=dark yt issues list
YOUTRACK_THEME=light yt projects list

Creating Custom Themes:

The yt config theme create command provides an interactive interface for creating custom themes:

# Create a new theme from scratch
yt config theme create my-theme

# Create based on existing theme
yt config theme create my-dark --base dark

The interactive creator will guide you through customizing:

Core colors (most commonly customized): - info, warning, error, success - header, link, highlight
Additional colors (optional): - field, value, muted, prompt - title, subtitle - progress indicators - table styling

Custom Theme Storage:

Custom themes are stored as JSON files in ~/.config/youtrack-cli/themes/:

{
  "name": "my-custom-theme",
  "description": "My personalized theme",
  "colors": {
    "info": "bright_blue",
    "warning": "orange",
    "error": "bright_red",
    "success": "bright_green",
    "header": "bold bright_cyan",
    "link": "blue underline",
    "highlight": "bold bright_yellow"
  }
}

Theme Import/Export:

Share themes with team members or backup your customizations:

# Export current theme
yt config theme export my-theme my-team-theme.json

# Share with team members
yt config theme import team-theme.json

# Export built-in theme as starting point
yt config theme export dark dark-base.json

Color Values:

Themes support Rich’s extensive color system:

Standard colors: black, red, green, yellow, blue, magenta, cyan, white
Bright colors: bright_red, bright_green, bright_blue, etc.
RGB colors: rgb(255,0,0), #ff0000
Style modifiers: bold, italic, underline, dim
Combinations: “bold red”, “underline blue”, “dim cyan”

Theme Styles Reference:

Each theme provides consistent styling for these elements:

info: Informational messages and highlights
warning: Warning messages and cautions
success: Success messages and confirmations
error: Error messages and failures
prompt: Interactive prompts and user input
field: Field names and labels
value: Field values and data
highlight: Important text highlights
link: URLs and clickable links
header: Table headers and section titles
title: Page and section titles
subtitle: Secondary headings
muted: Less important or secondary text
progress.description: Progress bar descriptions
progress.percentage: Progress bar percentages
progress.elapsed: Progress bar elapsed time
table.header: Table column headers
table.row: Standard table rows
table.row.odd: Alternating table rows
panel.border: Panel borders
panel.title: Panel titles
panel.subtitle: Panel subtitles

Theme Examples:

Example custom theme configurations:

# Minimal theme with just core colors
yt config theme create minimal
# Set: info=blue, warning=yellow, error=red, success=green

# High-contrast theme for accessibility
yt config theme create high-contrast --base dark
# Customize with brighter, more distinct colors

# Monochrome theme
yt config theme create mono
# Use only grayscale colors for minimal distraction

Troubleshooting Themes:

If you experience theme issues:

# Reset to default theme
yt config theme set default

# Check current theme
yt config theme current

# List all available themes
yt config theme list

# Remove problematic custom theme
yt config theme delete problematic-theme

Common issues:

Colors not displaying: Check terminal color support
Theme not found: Verify theme name with yt config theme list
Import failed: Validate JSON format and color values
Permission errors: Ensure ~/.config/youtrack-cli/themes/ is writable

Time Tracking Settings

Option	Type	Description
`time.default_duration_format`	string	Duration format: hours, minutes (default: hours)
`time.round_to_minutes`	integer	Round time entries to nearest N minutes (default: 15)
`time.auto_start_timer`	boolean	Auto-start timer when updating issue state (default: false)

Troubleshooting

Configuration File Location

If you’re unsure where your configuration file is located:

yt config list --show-file

Permission Issues

If you get permission errors, ensure the configuration directory exists and is writable:

mkdir -p ~/.config/youtrack-cli
chmod 755 ~/.config/youtrack-cli

Testing Configuration

Test your configuration by running:

yt auth login --test

Configuration Examples

Basic Setup Example

Simple configuration for a single YouTrack instance:

# ~/.config/youtrack-cli/.env
YOUTRACK_BASE_URL=https://company.youtrack.cloud
YOUTRACK_TOKEN=perm:cm9vdC5yb290.UGVybWlzc2lvbnM=.1234567890abcdef
YOUTRACK_USERNAME=john.doe
DEFAULT_PROJECT=WEB
OUTPUT_FORMAT=table

Team Development Example

Configuration optimized for team development workflows:

# ~/.config/youtrack-cli/.env
YOUTRACK_BASE_URL=https://company.youtrack.cloud
YOUTRACK_TOKEN=perm:your-token-here
YOUTRACK_USERNAME=team.developer

# Project defaults
DEFAULT_PROJECT=TEAM-PROJECT

# Issue defaults
DEFAULTS_ASSIGNEE=john.doe
DEFAULTS_PRIORITY=Medium
DEFAULTS_TYPE=Task

# Display preferences
OUTPUT_FORMAT=table
MAX_RESULTS=25
SHOW_COLORS=true
DATE_FORMAT=%Y-%m-%d %H:%M
YOUTRACK_THEME=dark

# Time tracking
TIME_ROUND_TO_MINUTES=15
TIME_DEFAULT_DURATION_FORMAT=hours

CI/CD Pipeline Example

Configuration for automated CI/CD integration:

# CI environment variables
export YT_URL="https://company.youtrack.cloud"
export YT_TOKEN="${YOUTRACK_API_TOKEN}"  # From CI secrets
export YT_OUTPUT_FORMAT="json"
export YT_MAX_RESULTS="100"
export YT_SHOW_COLORS="false"
export YT_VERIFY_SSL="true"

Multi-Environment Example

Using different configurations for different environments:

# Development environment
# ~/.config/youtrack-cli/dev.env
YOUTRACK_BASE_URL=https://dev.youtrack.company.com
YOUTRACK_TOKEN=perm:dev-token-here
DEFAULT_PROJECT=DEV-PROJECT
OUTPUT_FORMAT=table

# Production environment
# ~/.config/youtrack-cli/prod.env
YOUTRACK_BASE_URL=https://youtrack.company.com
YOUTRACK_TOKEN=perm:prod-token-here
DEFAULT_PROJECT=PROD-PROJECT
OUTPUT_FORMAT=json

# Usage with different configs:
# yt --config ~/.config/youtrack-cli/dev.env issues list
# yt --config ~/.config/youtrack-cli/prod.env issues list

Corporate Proxy Example

Configuration for environments behind corporate proxy:

# ~/.config/youtrack-cli/.env
YOUTRACK_BASE_URL=https://youtrack.company.com
YOUTRACK_TOKEN=perm:your-token-here
YOUTRACK_USERNAME=corporate.user

# Proxy settings (via environment variables)
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.company.com

# SSL settings for corporate certificates
YOUTRACK_VERIFY_SSL=true
YOUTRACK_TIMEOUT=60