Configuration

Priority order

Configuration is resolved from highest to lowest priority:

1. CLI flags — --url, --token, --backend, etc.
2. Environment variables — backend-specific (see below)
3. Project config — .track.toml in the current directory
4. Global config — ~/.tracker-cli/.track.toml

Config file format

Create .track.toml in your project directory or ~/.tracker-cli/.track.toml for global defaults.

YouTrack

backend = "youtrack"
url = "https://youtrack.example.com"
token = "perm:base64user.base64name.token"
default_project = "PROJ"

Jira

backend = "jira"

[jira]
url = "https://your-domain.atlassian.net"
email = "you@example.com"
token = "your-api-token"

Linear

backend = "linear"
default_project = "PROJ" # Linear team key/name/id

[linear]
token = "lin_api_xxxxxxxxxxxx"
url = "https://linear.app/your-workspace" # for `track open`
# api_url = "https://api.linear.app/graphql" # default
# default_team = "PROJ"                       # optional alias for default_project
# default_linear_project = "Track CLI"        # optional issue Project association

Multi-backend

You can configure multiple backends in one file and switch between them:

# Default backend
backend = "youtrack"

# YouTrack
url = "https://youtrack.example.com"
token = "perm:base64user.base64name.token"
default_project = "PROJ"

# Jira
[jira]
url = "https://your-domain.atlassian.net"
email = "you@example.com"
token = "your-api-token"

# Link type mappings are covered below.

track PROJ-123              # Uses YouTrack (default)
track -b jira PROJ-123      # Uses Jira
track -b lin ORE-123        # Uses Linear

track config backend jira   # Or change the default backend
track config backend linear

Link type mappings

track issue link accepts a small set of canonical link names so commands can stay portable across backends:

relates, depends, required, duplicates, duplicated-by, subtask, and parent.

Backends then translate those names into the native link type expected by the remote API. This matters when admins on your project tool rename issue link types, add custom relationship names, or use different words for the same workflow. For example, one Jira instance might call a dependency link Blocks, while another calls it Requires.

subtask and parent use backend-native hierarchy APIs where available. Link type mappings apply to the general issue-link path used by relates, depends, required, duplicates, duplicated-by, and any custom type name you pass with -t.

Defaults

CLI link type	YouTrack	Jira	GitLab	Linear
relates	Relates	Relates	relates_to	related
depends	Depend	Blocks	blocks	blocks
required	Depend	Blocks	is_blocked_by	blocks
duplicates	Duplicate	Duplicate	relates_to	duplicate
duplicated-by	Duplicate	Duplicate	relates_to	duplicate

Override mappings

Add a backend-specific link_mappings table to .track.toml. Keys are the CLI link type names you want to use; values are the native backend names.

[jira.link_mappings]
depends = "Requires"
required = "Requires"
duplicates = "Cloners"

[youtrack.link_mappings]
depends = "Is required for"

[gitlab.link_mappings]
duplicates = "blocks"

[linear.link_mappings]
relates = "similar"

With that config, scripts and interactive use keep the same command shape:

track -b j  i link PROJ-10 PROJ-11 -t depends
track -b yt i link PROJ-10 PROJ-11 -t depends
track -b gl i link 42 43 -t duplicates
track -b lin i link ORE-10 ORE-11 -t relates

You can also create local aliases for custom relationship names. Unrecognized types are passed through by default, but a mapping lets your team expose a stable CLI vocabulary even if the backend’s native name is awkward:

[jira.link_mappings]
qa-blocker = "Blocks"

[linear.link_mappings]
design-related = "similar"

track -b j   i link PROJ-20 PROJ-21 -t qa-blocker
track -b lin i link ORE-20 ORE-21 -t design-related

Workflow packs

One [workflow_pack] table defines local query templates that overlay cached built-ins. Selection is whole-pack (not field-merged): --config / TRACKER_CONFIG inspects only that file; otherwise ./.track.toml if it has [workflow_pack]; otherwise ~/.tracker-cli/.track.toml. There is no parent directory walk.

[workflow_pack]
name = "Orek backlog"
description = "Project-local views for backlog work."
default_project = "PROJ"

[[workflow_pack.queries]]
name = "ready"
description = "Issues ready for implementation."
query = "project: {PROJECT} #Unresolved State: {Ready}"

Rules:

• name is required and non-empty. description and default_project are optional; if present they must be non-empty. At least one query is required.
• Each query needs non-empty name, description, and query.
• Query names are ^[a-z][a-z0-9_]*$ and unique case-insensitively.
• Unknown fields on the pack or a query record are rejected.
• Only exact {PROJECT} is substituted: --project, then pack default_project, then top-level default_project.
• Pack queries win on name collision with built-ins. Duplicate names inside one pack are an error. An invalid pack fails -T search and workflow commands.
• The section is preserved by config set / Config::save, but it is not editable via track config set. Packs are not written into .tracker-cache/.
• Cached built-ins are backend-scoped: the cache records the backend that wrote it, and workflow list / -T resolution only use templates matching the selected backend. A cache refreshed for another backend is ignored, not leaked — run track cache refresh after switching backends. A project pack shadows the global one and its queries always win on name collision.

Environment variables

Environment variables override config-file settings:

# Generic (any backend). TRACKER_* variables configure the active backend connection.
export TRACKER_BACKEND=youtrack
export TRACKER_URL=https://youtrack.example.com
export TRACKER_TOKEN=YOUR_TOKEN

# YouTrack
export YOUTRACK_URL=https://youtrack.example.com
export YOUTRACK_TOKEN=YOUR_TOKEN

# Jira
export JIRA_URL=https://your-domain.atlassian.net
export JIRA_EMAIL=you@example.com
export JIRA_TOKEN=your-api-token

# GitHub
export GITHUB_TOKEN=ghp_xxx
export GITHUB_OWNER=your-org
export GITHUB_REPO=your-repo

# GitLab
export GITLAB_TOKEN=glpat_xxx
export GITLAB_URL=https://gitlab.com/api/v4
export GITLAB_PROJECT_ID=12345

# Linear
export LINEAR_TOKEN=lin_api_xxx
export LINEAR_URL=https://linear.app/your-workspace
export LINEAR_DEFAULT_TEAM=PROJ
# export LINEAR_API_URL=https://api.linear.app/graphql
# export LINEAR_DEFAULT_PROJECT="Track CLI"

Backend selection

The default backend is YouTrack. Choose a backend three ways:

Config file (recommended)

backend = "youtrack"  # or "jira", "github", "gitlab", "linear"

track config backend jira

Environment variable

export TRACKER_BACKEND=jira
track PROJ-123              # Uses Jira

Per-command flag

track -b jira PROJ-123      # Jira for this command only
track -b yt  PROJ-123       # YouTrack
track -b lin PROJ-123       # Linear
track -b j   PROJ-123       # Jira (short alias)

Priority: CLI flag > environment variable > config file > default (YouTrack).

Validate capabilities

Use config test for a quick URL/token probe, then doctor when you need to know what the selected backend can actually do.

track config test                     # Single connectivity check
track doctor                          # Capability audit for the effective backend
track doctor --all-backends           # Audit every configured backend
track -b github doctor                # Audit one backend with the global selector
track doctor --project PROJ           # Use a project for scoped checks
track doctor --write-check            # Local schema validation only; no remote writes
track doctor --all-backends --strict -o json

doctor reports ok, degraded, failed, or skipped per check. A scope-limited token may be degraded while search/read workflows still work; bad credentials or a broken read path roll the backend up as failed.