ytrack

A fast, agent-friendly CLI for querying JetBrains YouTrack instances. Get issue status, project metadata, and tracking data from the command line with structured JSON/YAML output for scripts and beautiful tables for humans.

Features

• kubectl-style commands — intuitive resource-based CLI (ytrack issue get, ytrack project list)
• Agent-friendly output — structured JSON/YAML by default, beautiful tables for interactive use
• Multi-instance support — manage multiple YouTrack profiles with automatic context switching
• Secure token storage — OS keychain integration (Keychain, Secret Service, Credential Manager)
• Smart caching — file-based TTL cache per profile (5min issues, 60min projects)
• Shell completions — Bash, Zsh, Fish, PowerShell included in releases

Installation

macOS

Homebrew (Coming Soon)

Direct Download

# Apple Silicon (M1/M2/M3)
curl -L https://github.com/zhuk/ytrack/releases/latest/download/ytrack_darwin_arm64.tar.gz | tar xz
sudo mv ytrack /usr/local/bin/

# Intel
curl -L https://github.com/zhuk/ytrack/releases/latest/download/ytrack_darwin_amd64.tar.gz | tar xz
sudo mv ytrack /usr/local/bin/

Linux

Direct Download

# amd64
curl -L https://github.com/zhuk/ytrack/releases/latest/download/ytrack_linux_amd64.tar.gz | tar xz
sudo mv ytrack /usr/local/bin/

# arm64
curl -L https://github.com/zhuk/ytrack/releases/latest/download/ytrack_linux_arm64.tar.gz | tar xz
sudo mv ytrack /usr/local/bin/

Windows

Scoop (Coming Soon)

Direct Download

Invoke-WebRequest -Uri "https://github.com/zhuk/ytrack/releases/latest/download/ytrack_windows_amd64.zip" -OutFile "ytrack.zip"
Expand-Archive ytrack.zip
Move-Item ytrack.exe "C:\Program Files\ytrack.exe"

Configuration

Set up your YouTrack instance by creating a profile:

ytrack config add --profile default --url https://youtrack.example.com --token perm:your-token-here

Using Environment Variables

Override the active profile or token:

export YTRACK_PROFILE=default
export YTRACK_TOKEN=perm:your-token-here

Creating a Permanent Token

1. Open your YouTrack instance
2. Go to Profile → Authentication → New Token
3. Name it (e.g., "ytrack CLI") and set appropriate permissions
4. Copy the token (starts with perm:)

Multiple Instances

For multiple YouTrack instances, create separate profiles:

ytrack config add --profile main --url https://youtrack.example.com --token perm:your-token
ytrack config add --profile work --url https://work.youtrack.com --token perm:work-token

# Set active profile
export YTRACK_PROFILE=work

# Or use .ytrack file in project directory
echo "profile: work" > .ytrack

Quick Start

# Check version
ytrack version

# List issues
ytrack issue list

# Get specific issue details
ytrack issue get YT-123

# List projects
ytrack project list

# Get JSON output for scripts
ytrack issue get YT-123 -o json | jq '.id, .summary'

# Check your setup
ytrack config validate --check-auth

Documentation

• Full Documentation — complete command reference and examples
• Shell Completions — setup guide for Bash, Zsh, Fish, PowerShell
• Architecture — system design and technical decisions
• API Integration — YouTrack API mapping and response transformation

Examples

Scripting with JSON Output

# Get issue details in JSON format
ytrack issue get YT-123 -o json | jq '{id, summary, state, created}'

# Get all projects
ytrack project list -o json | jq '[.[] | {name: .name, shortName: .shortName}]'

Daily Workflow

# Check issue status
ytrack issue get YT-123

# List projects
ytrack project list

# Validate config before CI job
ytrack config validate --check-auth

Development

See AGENTS.md for development guidelines and architecture patterns.

Release Checklist

1. make lint passes
2. make test passes
3. make build produces a working binary
4. ./bin/ytrack version shows the expected version
5. Tag the release: git tag v1.2.3
6. Push the tag: git push origin v1.2.3
7. CI builds and publishes the release automatically

License

Apache 2.0 — see LICENSE file for details.

Support

• Issues: GitHub Issues
• Documentation: docs/prd/