youtrack-cli

Terminal-first CLI for YouTrack. Covers the issue lifecycle — issues, comments, attachments — in both human-readable table and --json output modes.

Install

curl -fsSL https://raw.githubusercontent.com/ghostspice/youtrack-cli/0.1.x/install.sh | bash

Clones the repo and builds from source. Requires git and the Rust toolchain. Installs to ~/.local/bin (override with YOUTRACK_CLI_INSTALL_DIR).

Or manually:

make install        # builds release binary → ~/.local/bin/youtrack-cli

Auth

1. System keychain (auth login)

Store credentials once in the OS keychain (macOS Keychain, Linux Secret Service / KWallet):

youtrack-cli auth login    # prompts for URL and token, validates, saves
youtrack-cli auth logout   # removes saved token
youtrack-cli ping          # ping the API and print the authenticated user

auth login also writes youtrack_url into the config file so subsequent commands can discover it automatically. If the config file already contains a token entry, that entry takes precedence over the keychain — remove it to use the saved keychain credential.

2. Environment variables

export YOUTRACK_HOST=your.youtrack.cloud   # bare host; https:// is added automatically
export YOUTRACK_TOKEN=perm:...
youtrack-cli issue list

3. Config file

~/.config/youtrack-cli/config.toml (or $XDG_CONFIG_HOME/youtrack-cli/config.toml):

youtrack_url = "https://your.youtrack.cloud"
token = "perm:..."

Token values may reference environment variables:

token = "env:YOUTRACK_TOKEN"

Credentials are resolved in order (first match wins): env var → config file → keychain.

The YOUTRACK_HOST, YOUTRACK_TOKEN, and YOUTRACK_OUTPUT env vars are trimmed of surrounding whitespace; an empty value falls through to the next source. YOUTRACK_HOST is a bare hostname (e.g. youtrack.example.com, optional :port and path) — the https:// prefix is added for you. To use http:// or a non-default scheme, set youtrack_url in the config file instead.

Usage

youtrack-cli [OPTIONS] <COMMAND>

Options:
  --output <FORMAT>   table | json | yaml
  --verbose           show config sources, enable debug logging
  --quiet             errors only

Commands:
  auth login / logout
  ping
  issue list   [--query <YQL>] [--top <N>] [--skip <N>] [--all]
  issue get    <ID>
  issue create --project <ID> --summary <S> [--description <D>]
  issue update <ID> [--summary <S>] [--description <D>]
  issue delete <ID> [--yes]

  issue comment list   <ID>
  issue comment add    <ID> --text <T>
  issue comment update <ID> <COMMENT_ID> --text <T>
  issue comment delete <ID> <COMMENT_ID> [--yes]

  issue attachment list   <ID>
  issue attachment upload <ID> --file <PATH> [--name <NAME>] [--replace]
  issue attachment delete <ID> <ATTACHMENT_ID> [--yes]

Examples

# First-time setup
youtrack-cli auth login

# Five open issues in DEMO, as a table
youtrack-cli issue list --query "project: DEMO state: Open" --top 5

# All issues for a project, as JSON, pipe through jq
youtrack-cli issue list --query "project: DEMO" --all --json | jq '.[].id'

# Create, comment, attach, delete
ID=$(youtrack-cli issue create --project DEMO --summary "smoke" --json | jq -r .id)
youtrack-cli issue comment add "$ID" --text "hi"
youtrack-cli issue attachment upload "$ID" --file ./log.txt
youtrack-cli issue delete "$ID" --yes

Development

make test       # cargo test --all
make lint       # cargo clippy --all-targets -- -D warnings
make fmt-check  # cargo fmt --all --check
make ci         # all of the above

Limitations

• No free-form commands — the YouTrack Commands API is not yet exposed. Use issue update for --summary / --description changes.
• No attachment download — only list / upload / delete.
• Attachment uploads load the whole file into memory. Fine for typical attachments (<10 MB).

Exit codes

Code	Meaning
0	Success
1	Runtime error (network / API)
2	Configuration or usage error
3	Authentication or authorization error
4	Not found (HTTP 404)
5	Rate limited

License

MIT