ytrack is a small cross-platform command-line client for YouTrack. It keeps
shared credentials in a global config file, keeps project-specific settings in
the current repository, and gives you short commands for creating issues and
moving their status.
The project is an early MVP. It currently supports:
- global YouTrack URL and token configuration
- local per-directory URL, token, and project configuration
- creating YouTrack issues
- changing issue status through YouTrack commands
- inspecting and resolving YouTrack users
- creating YouTrack projects
- raw JSON output for API-backed commands
brew install rtcoder/tap/ytrackDevelopment builds from the main branch are available with:
brew install --HEAD rtcoder/tap/ytrackDownload a release package from:
https://github.com/rtcoder/ytrack/releases
Download the .deb package for your CPU architecture from GitHub Releases,
then install it with apt:
sudo apt install ./ytrack_<version>_linux_amd64.debUse ytrack_<version>_linux_arm64.deb instead on ARM64 systems.
Download the .rpm package for your CPU architecture from GitHub Releases,
then install it with dnf:
sudo dnf install ./ytrack_<version>_linux_amd64.rpmUse ytrack_<version>_linux_arm64.rpm instead on ARM64 systems.
Release assets include:
- macOS Intel:
ytrack_<version>_darwin_amd64.tar.gz - macOS Apple silicon:
ytrack_<version>_darwin_arm64.tar.gz - Linux x64:
ytrack_<version>_linux_amd64.tar.gz - Linux ARM64:
ytrack_<version>_linux_arm64.tar.gz - Debian/Ubuntu x64:
ytrack_<version>_linux_amd64.deb - Debian/Ubuntu ARM64:
ytrack_<version>_linux_arm64.deb - Fedora/RHEL x64:
ytrack_<version>_linux_amd64.rpm - Fedora/RHEL ARM64:
ytrack_<version>_linux_arm64.rpm - Windows x64:
ytrack_<version>_windows_amd64.zip - SHA-256 hashes:
checksums.txt
go build -o ytrack ./cmd/ytrackOr install into your Go bin directory:
go install ./cmd/ytrackSet your shared YouTrack URL and token once:
ytrack global set-url https://youtrack.example.com
ytrack global set-token perm:your-tokenInside a repository, set the YouTrack project ID:
ytrack set-project-id 0-1Or run the interactive local setup:
ytrack initCreate an issue:
ytrack issue create "Crash on save" "Steps to reproduce..."Move an issue to another status:
ytrack issue status ART-123 DoneShow the current user:
ytrack user meCreate a project:
ytrack project create "Mobile App" --key MOB --leader meConfiguration is merged at runtime:
local ./.ytrack/config.json > global OS user config
Local values override global values. This lets you keep one global token while each repository chooses its own YouTrack project.
project_id is local-only by design. It is never read from or written to the
global config, which helps avoid creating issues in the wrong project.
Global config lives under Go's os.UserConfigDir():
- macOS: usually
~/Library/Application Support/ytrack/config.json - Linux: usually
~/.config/ytrack/config.json - Windows: usually
%APPDATA%\ytrack\config.json
Local config lives in the current working directory:
./.ytrack/config.json
Config files containing tokens are written with 0600 permissions where the
operating system supports POSIX file modes.
Add this to repositories where you use local config:
.ytrack/Show the effective merged config:
ytrack showShow only global config:
ytrack global showTokens are masked in output:
url: https://youtrack.example.com
token: perm:xxxx...abcd
project_id: 0-1
Generated command reference is available in docs/commands.md.
ytrack --help
ytrack --json <command>--json prints raw JSON for commands that call the YouTrack API. It is useful
for scripts and shell pipelines.
ytrack global show
ytrack global set-url <url>
ytrack global set-token <token>
ytrack global unset-url
ytrack global unset-tokenGlobal config is best for values shared across projects, such as the YouTrack base URL and a personal permanent token.
Examples:
ytrack global set-url https://youtrack.example.com
ytrack global set-token perm:your-token
ytrack global show
ytrack global unset-tokenThere is no ytrack global set-project-id. Project IDs are intentionally local.
ytrack show
ytrack init
ytrack set-url <url>
ytrack set-token <token>
ytrack set-project-id <project-id>
ytrack unset-url
ytrack unset-token
ytrack unset-project-idLocal config is best for repository-specific overrides. The most common local
setting is project_id.
Examples:
ytrack set-project-id 0-1
ytrack set-url https://team.youtrack.example.com
ytrack set-token perm:project-specific-token
ytrack show
ytrack unset-project-idytrack issue create <summary>
ytrack issue create <summary> <description>
ytrack issue create <summary> --description-file <path>
ytrack issue create <summary> --description-file -
ytrack issue create <summary> [description] [--type <type>] [--assignee <user>] [--priority <priority>] [--version <version>]
ytrack issue list
ytrack issue list --state <value>
ytrack issue list --assigned-to <user>
ytrack issue show <issue-id>
ytrack issue edit <issue-id> [--title <title>] [--description <description>] [--type <type>] [--priority <priority>]
ytrack issue type <issue-id> <type>
ytrack issue priority <issue-id> <priority>
ytrack issue comment <issue-id> <text>
ytrack issue assign <issue-id> <user>
ytrack issue command <issue-id> <command>
ytrack issue close <issue-id>
ytrack issue status <issue-id> <status>Create an issue with only a summary:
ytrack issue create "Crash on save"Create an issue with a summary and description:
ytrack issue create "Crash on save" "Steps to reproduce..."Create an issue with metadata:
ytrack issue create "Crash on save" "Steps to reproduce..." --type Bug --assignee me --priority High --version v0.1.10Create an issue with a longer description from a file or stdin:
ytrack issue create "Crash on save" --description-file bug.md
cat bug.md | ytrack issue create "Crash on save" --description-file -List issues in the configured local project:
ytrack issue list
ytrack issue list --state Submitted
ytrack issue list --assigned-to meChange issue status:
ytrack issue status ART-123 Done
ytrack issue status ART-123 "In Progress"
ytrack issue close ART-123Show issue details:
ytrack issue show ART-123Edit issue fields:
ytrack issue edit ART-123 --title "New title"
ytrack issue edit ART-123 -t "New title" -d "New description" --type Task --priority High
ytrack issue type ART-123 Task
ytrack issue priority ART-123 HighComment, assign, or run a raw YouTrack command:
ytrack issue comment ART-123 "Looks good"
ytrack issue assign ART-123 me
ytrack issue command ART-123 "Priority Critical"issue status sends a YouTrack command in this form:
State <status>
ytrack user me
ytrack user list
ytrack user list --top <count>
ytrack user list --skip <count>
ytrack user find <query>Show the current user for the configured token:
ytrack user meList users:
ytrack user list
ytrack user list --top 20Find one user by ID, me, login, name, or email:
ytrack user find me
ytrack user find 24-55
ytrack user find m.scottIf a search matches multiple users, ytrack prints an error with the matching
IDs and logins so you can run the command again with a more specific value.
ytrack project create [title]
ytrack project create [title] --key <project-key> --leader <user>
ytrack project create [title] --key <project-key> --leader <user> --set-project-id
ytrack project create [title] --key <project-key> --leader <user> --template kanban
ytrack project create [title] --key <project-key> --leader <user> --template scrum
ytrack project list issues
ytrack project list issues --status <value>
ytrack project list issues --user <value>
ytrack project list issues --type <value>
ytrack project list issues --priority <value>
ytrack project list statuses
ytrack project list users
ytrack project list types
ytrack project list priorities
ytrack project list versionsCreate a project with command-line arguments:
ytrack project create "Mobile App" --key MOB --leader me
ytrack project create "Mobile App" --key MOB --leader rtcoder
ytrack project create "Mobile App" --key MOB --leader 1-2
ytrack project create "Mobile App" --key MOB --leader me --set-project-idThe --leader value accepts the same references as ytrack user find: me, a
YouTrack user ID, login, name, or email. The command resolves it to the user ID
required by YouTrack before creating the project.
Use --set-project-id to save the newly created project ID to the local
./.ytrack/config.json for the current directory.
Run without arguments to answer prompts:
$ ytrack project create
Set project name:
Mobile App
Set project key:
MOB
Set leader:
me
Set new project as local project_id? [y/N]
y
If the current directory already has a local project_id, interactive mode asks
before overwriting it:
Local project_id is 0-1. Overwrite with 0-16? [y/N]
List data for the configured local project:
ytrack project list issues
ytrack project list issues --status Submitted
ytrack project list issues --user me
ytrack project list issues --type Bug
ytrack project list issues --priority Normal
ytrack project list statuses
ytrack project list users
ytrack project list types
ytrack project list priorities
ytrack project list versionsUse --json before the command:
ytrack --json issue create "Crash on save"
ytrack --json issue create "Crash on save" "Steps to reproduce..."
ytrack --json issue show ART-123
ytrack --json issue edit ART-123 --title "New title"
ytrack --json issue comment ART-123 "Looks good"
ytrack --json issue command ART-123 "Priority Critical"
ytrack --json issue status ART-123 Done
ytrack --json user me
ytrack --json user list --top 20
ytrack --json project create "Mobile App" --key MOB --leader me
ytrack --json project list usersWithout --json, successful commands print human-readable output:
Created ART-123: "Crash on save"
url: https://youtrack.example.com/issue/ART-123
Updated ART-123 to Done
With --json, API-backed commands print the raw YouTrack response. API error
responses with error_description are printed as concise actionable messages.
Generate shell completion scripts with:
ytrack completion bash
ytrack completion zsh
ytrack completion fish
ytrack completion powershellissue create requires:
urltoken- local
project_id
issue status requires:
urltoken
User commands require:
urltoken
project create requires:
urltoken- a project name
- a project key
- a resolvable project leader
Missing values produce actionable errors, for example:
missing configured project_id, run `ytrack set-project-id <project-id>`
Create a permanent token in YouTrack and pass it to:
ytrack global set-token perm:your-tokenIf a repository needs different credentials, override the token locally:
ytrack set-token perm:project-specific-tokenRun tests:
go test ./...Pull requests run:
go test -count=1 ./...Build the CLI:
go build -o ytrack ./cmd/ytrackCross-compile examples:
GOOS=darwin GOARCH=arm64 go build -o dist/ytrack-darwin-arm64 ./cmd/ytrack
GOOS=linux GOARCH=amd64 go build -o dist/ytrack-linux-amd64 ./cmd/ytrack
GOOS=windows GOARCH=amd64 go build -o dist/ytrack-windows-amd64.exe ./cmd/ytrackGitHub Actions publishes release packages when a version tag is pushed:
git tag v0.1.1
git push origin v0.1.1You can also run the Release workflow manually from GitHub Actions and provide
an existing tag.
The release workflow:
- runs tests
- builds Linux, macOS, and Windows binaries
- packages Linux
.deband.rpmrelease assets - uploads release assets and
checksums.txt - updates
rtcoder/homebrew-tapwhenHOMEBREW_TAP_TOKENis configured
MIT