billpeet YouTrack
Interact with a YouTrack instance using the yt CLI. All commands output JSON by default for reliable parsing.
Setup
Configure once (credentials saved to ~/.config/yt-cli/config.json):
yt setup --url https://your-instance.youtrack.cloud --token <permanent-api-token>
Or use environment variables (these take priority over the config file):
export YOUTRACK_BASE_URL=https://your-instance.youtrack.cloud
export YOUTRACK_TOKEN=<permanent-api-token>
Issues
Search
yt issue search "<query>" --format json --pretty
yt issue search "project: MyProject #Unresolved assignee: me" --top 20 --format json
yt issue search "tag: bug" --top 10 --skip 0 --format json
YouTrack query syntax: project: PROJ, #Unresolved, assignee: me, priority: Critical, tag: bug, free text, etc.
Get a single issue
yt issue get PROJ-123 --format json --pretty
Create an issue
yt issue create --project PROJ --summary "Summary here" --description "Details" --format json
yt issue create --project PROJ --summary "Summary here" --description "First paragraph\n\nScope:\n- Item one\n- Item two" --format json
yt issue create --project PROJ --summary "Summary here" --agile "Continuous Improvement" --parent PROJ-123 --format json
Multiline descriptions and comments
When creating or updating issue descriptions, or adding comments, preserve paragraph and list formatting by using escaped newline sequences (\n) inside the quoted argument:
yt issue create --project PROJ --summary "Example" --description "First paragraph\n\nScope:\n- Item one\n- Item two" --format json
yt issue comment PROJ-123 --text "Implemented changes:\n- Added API endpoint\n- Updated tests" --format json
Do not double-escape newlines as \\n unless you intentionally want the literal text \n to appear in YouTrack. The yt CLI converts \n to real newlines before sending text to YouTrack. Literal shell newlines are also acceptable if your shell/tooling supports them, but escaped \n is the safest portable form for agents.
Update an issue
yt issue update PROJ-123 --summary "New summary" --format json
yt issue update PROJ-123 --description "Updated description" --format json
yt issue update PROJ-123 --description "First paragraph\n\nScope:\n- Item one\n- Item two" --format json
yt issue update PROJ-123 --field "Priority=Critical" --field "State=In Progress" --format json
yt issue update PROJ-123 --agile "Continuous Improvement" --parent PROJ-456 --format json
Custom fields use --field "Name=Value" and can be repeated for multiple fields. Use --agile to add an issue to a board/current sprint and --parent to set the issue as a subtask of another issue for feature-based swimlanes.
Comments
List comments:
yt issue comments PROJ-123 --format json --pretty
Add a comment:
yt issue comment PROJ-123 --text "Comment text here" --format json
Projects
yt project list --format json --pretty
Agile Boards
yt agile list --format json --pretty
Users
Get the authenticated user:
yt user me --format json --pretty
Output format
All commands support --format json (compact) or --format text (human-readable). Add --pretty for indented JSON.
Exit codes: 0 = success, 1 = error. Errors are written to stderr as JSON.
Pagination
Use --top <n> (default 50) and --skip <n> (default 0) on issue search for pagination.
Common workflows
Find and update an issue:
yt issue search "summary: login bug #Unresolved" --format json --top 5
yt issue update PROJ-42 --field "State=In Progress" --agile "Continuous Improvement"
yt issue comment PROJ-42 --text "Started investigating — reproducible in staging."
Create and confirm:
yt issue create --project PROJ --summary "Fix null pointer in auth flow" --description "Stack trace: ..." --format json --pretty
Assign to a board and feature swimlane:
yt agile list --format json --pretty
yt issue update PROJ-42 --agile "Continuous Improvement" --parent PROJ-123 --format json --pretty