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 multiple themes for customizing the appearance of console output.

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

Available 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

Setting a Theme:

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

# Set theme via environment variable
export YOUTRACK_THEME=light

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

Theme Styles:

Each theme provides consistent styling for:

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: Progress bars and status indicators
table: Table formatting and structure

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