Backends

track keeps the day-to-day commands consistent, but each backend has different authentication, identifier rules, search syntax, and capability boundaries. Use this page to decide which backend mode you are in, what the CLI can do there, and which backend-native quirks matter before automating a workflow.

At a glance

YouTrack

Full tracker automation for issues, fields, tags, links, and Knowledge Base pages.

IDs: PROJ-123, articles like KB-A-1

Jira + Confluence

Best for Jira Cloud teams that also want Markdown-authored documentation published into Confluence pages.

IDs: issue keys, numeric Confluence page/space IDs

GitHub

Best for repository-scoped issue workflows, labels, milestones, comments, sub-issues, and Markdown wiki pages.

IDs: numeric issue numbers like 42

GitLab

Best for project-scoped GitLab issues, labels, notes, issue links, parent-child work items, and Markdown wiki pages.

IDs: project IID like #42

Linear

Best for team-scoped Linear issues with labels, states, parent-child issues, and relation links.

IDs: team issue IDs like ORE-123

Feature + command compatibility

The shared command names are the selling point. The matrix shows where that surface stays consistent and where the backend's native model changes the behavior.

Full native or complete support Limited command works with backend-specific limits No unsupported or intentionally empty

Issue lifecycle

Create, inspect, update, close, or delete tracked work items.

track i ctrack i utrack i rm

YouTrackFullCRUD

JiraFullCRUD

GitHubLimitedno delete

GitLabFullCRUD

LinearFullCRUD

Search and batch reads

Fetch large result sets for reports, cleanup, triage, and agent context.

track i s "..." --alltrack -o json

YouTrackFullquery language

JiraFullJQL

GitHubFullsearch API

GitLabFullfilters

LinearFullGraphQL

Comments and history

Pull conversation context and field transition history into the same CLI output.

track i cmttrack i hist

YouTrackFullcomments + history

JiraFullcomments + changelog

GitHubFullcomments + events

GitLabFullnotes + events

LinearFullcomments + history

Links and hierarchy

Connect work across blockers, related issues, subtasks, and parent-child relationships.

track i link A Btrack i link A B -t subtask

YouTrackFullnative links

JiraFulllinks + subtasks

GitHubLimitedsub-issues only

GitLabFulllinks + parent

LinearFullrelations + parent

Tags and labels

Normalize tracker labels as CLI tags for filtering, reporting, and updates.

track tags lstrack i u --tag

YouTrackFulltag objects

JiraLimitedlabels auto-create

GitHubFulllabels

GitLabFulllabels

LinearFulllabels

Projects and scope

List or resolve the container that gives issue commands their default scope.

track p lstrack p gtrack p c

YouTrackFullprojects

JiraLimitedno create

GitHubLimitedrepo scope

GitLabLimitedproject scope

LinearLimitedteam scope

Fields

Read or update typed issue metadata while preserving backend-specific field names.

track p fields PROJtrack i u --field

YouTrackFullfield admin

JiraFullsystem + custom

GitHubLimitedmapped fields

GitLabLimitedstandard fields

LinearLimitedmapped fields

Wiki and docs

Use one article command surface for tracker-native docs and repository wiki pages.

track wiki c --body-filetrack wiki u

YouTrackFullKnowledge Base

JiraFullMarkdown to Confluence

GitHubFullMarkdown wiki

GitLabLimitedno comments or move

LinearNounsupported

Attachments

Upload supporting files to issues, issue comments, wiki pages, or wiki comments where the backend exposes it.

track i attachtrack wiki attach

YouTrackFullissue + wiki

JiraFullissue + wiki

GitHubLimitedwiki only

GitLabLimitedissue + wiki block

LinearNounsupported

Agent workflows

Return structured output, cache context, and preview declarative changes before mutation.

track -o jsontrack cache refreshtrack apply --dry-run

YouTrackFullJSON + cache

JiraFullJSON + cache

GitHubFullJSON + cache

GitLabFullJSON + cache

LinearFullJSON + cache

YouTrack

YouTrack is the most complete backend in track: issue CRUD, comments, links, tags, custom fields, field administration, projects, and Knowledge Base articles all use first-party YouTrack APIs.

Configure

YOUTRACK_URL, YOUTRACK_TOKEN, optional default_project.

Identifiers

Issues use readable IDs such as PROJ-123. Articles use readable Knowledge Base IDs such as KB-A-1.

Search

Use YouTrack query syntax, for example project: PROJ #Unresolved.

Good fit

Automation that needs issue state, custom fields, tags, links, articles, and project metadata from one system.

track -b yt i s "project: PROJ #Unresolved" --all
track -b yt wiki list -p PROJ --all
track -b yt field list

Jira

Jira support targets Jira Cloud and uses Confluence for article commands. It is especially useful when teams want tracker automation and wiki publishing from the same agent-friendly command surface.

Markdown wiki publishing: article content passed with --body-file can be authored as Markdown and converted to Confluence storage format when creating or updating pages. Agents can draft a runbook in the repo, review it as a normal file, then publish it without writing Confluence XML by hand.

Configure

JIRA_URL, JIRA_EMAIL, and JIRA_TOKEN. Authentication uses Basic Auth with email and API token.

Identifiers

Issues use Jira keys such as PROJ-123. Confluence pages and spaces use numeric IDs.

Rich text

Issue descriptions and comments use Atlassian Document Format. Rich-text custom fields are surfaced as rendered plain text.

Fields and labels

System and custom fields are preserved in custom_fields. Jira labels map to common CLI tags.

track -b j i s "project = PROJ AND resolution IS EMPTY" --all
track -b j wiki create -p 65957 -s "Rollback runbook" \
  --body-file ./runbook.md
track -b j wiki update 123456 --body-file ./runbook.md

Jira quirks to know

Confluence path: Jira article commands use Confluence at the same Atlassian domain with a /wiki path.

Components: surfaced as a Components multi-value custom field. Filter by area with JQL such as component = "Rendering".

Project creation: generally requires administrator workflows in Jira; use the web interface for project setup.

Subtasks: create new subtasks with --parent, or link existing issues with issue link -t subtask.

GitHub

GitHub support is repository-scoped and maps GitHub Issues into the common issue model. It filters pull requests out of issue listings so searches behave like issue-only workflows.

Configure

GITHUB_TOKEN, GITHUB_OWNER, GITHUB_REPO, optional GITHUB_API_URL.

Identifiers

Use numeric issue numbers such as 42. The configured owner/repo supplies the repository scope.

Labels

GitHub labels map to common CLI tags, including label colors.

Hierarchy

Sub-issues are supported through GitHub's sub-issues API with --parent or issue link -t subtask/parent.

track -b gh 42 --full
track -b gh i s "is:open label:bug" --all
track -b gh i link 42 43 -t subtask

GitHub limits

No issue deletion: GitHub does not support deleting issues through the Issues API; close them instead.

No general issue links: use comments such as #42 for related references unless you are using sub-issues.

Wiki support: article commands use the repository wiki and Markdown pages. GitHub wiki pages do not support comments.

Rate limits: use authenticated requests for reliable automation.

GitLab

GitLab support is project-scoped and uses GitLab REST API v4 for issue operations, with GraphQL used where parent-child work item hierarchy is required.

Configure

GITLAB_TOKEN, GITLAB_URL, and GITLAB_PROJECT_ID. The URL should point at /api/v4.

Identifiers

Issue commands use the project IID, such as #42, not the global GitLab issue ID.

Labels and notes

Labels map to common CLI tags. GitLab comments are notes; system notes are filtered from comment lists.

Links

Supports relates_to, blocks, and is_blocked_by, plus parent-child hierarchy through GraphQL.

track -b gl 42 --full
track -b gl i s "state=opened" --all
track -b gl i link 42 43 -t depends

GitLab limits

No project creation: configure an existing project with gitlab.project_id.

Wiki support: article commands use GitLab project wiki pages. Wiki comments and moving wiki pages are not supported.

Project path IDs: numeric project IDs are simplest, but URL-encoded project paths can also be used where configured.

Linear

Linear support is team-scoped. The CLI's project concept maps to a Linear team key, name, or ID; Linear's native Project is an issue association that can be set through a field or default config.

Configure

LINEAR_TOKEN, LINEAR_URL, LINEAR_DEFAULT_TEAM, optional LINEAR_DEFAULT_PROJECT.

Identifiers

Use Linear issue IDs such as ORE-123. Team scope comes from default_project or linear.default_team.

Labels and projects

Labels map to tags. Unknown labels on create/update are rejected. Linear Project can be set with --field "Project=Track CLI".

Links

Parent-child uses Linear parent IDs. Relation links support related, blocks, duplicate, and similar.

track -b lin ORE-123 --full
track -b lin i s "#Open" --all
track -b lin i u ORE-123 --field "Project=Track CLI"

Linear limits

No team creation: configure an existing Linear team for CLI project scope.

No Knowledge Base: article and wiki commands are not available for Linear.

Project naming: Linear Project is not the same thing as the CLI project selector; use the Project field when you mean Linear's native project association.