Metadata-Version: 2.4
Name: jetbrains-youtrack-cli
Version: 0.1.0
Summary: A portable command-line client for the JetBrains YouTrack REST API.
Project-URL: Homepage, https://github.com/rock3r/youtrack-cli
Project-URL: Repository, https://github.com/rock3r/youtrack-cli
Project-URL: Issues, https://github.com/rock3r/youtrack-cli/issues
Project-URL: License, https://uelicense.eu
Author: The youtrack-cli authors
License: Copyright (c) 2026 The youtrack-cli authors
        
        Licensed under the Unenshittifiable License (UEL) v1.0.
        Source: https://uelicense.eu  — see full text below.
        
        ----------------------------------------------------------------
        
        THE UNENSHITTIFIABLE LICENSE (UEL) v1.0
        
        Use it. Fork it. Learn from it. Self-host it. Improve it.
        Just don't enshittify it.
        
        00. THE SPIRIT
        This license is for software meant to stay useful to people — not to be quietly enclosed, paywalled, and made worse over time.
        Everything below is the legally-operative version of one simple promise: keep the commons open, and keep it out of the toll-booth business. Where the plain meaning and the legalese ever seem to disagree, the spirit wins.
        
        01. DEFINITIONS
        “The Software” means the work distributed under this license, including its source, and any modified versions.
        “You” means any person or organisation exercising the rights granted here.
        “Commercial Offering” means providing the Software, or substantially the Software, to third parties for a fee, paid subscription, or paid access of any kind — including a hosted service, a paid edition, or a bundled commercial product.
        “Internal Use” means running the Software for yourself or your own organisation's own purposes, without offering it to third parties for a fee.
        
        02. WHAT YOU MAY DO
        You may read, study, and learn from the source. You may run it anywhere, for any non-prohibited purpose, including Internal Use at a company of any size.
        You may copy, modify, and fork it. You may self-host it for yourself or your community, forever, at no cost. If you distribute your modified versions, you must do so under this same license, with source.
        You may charge for your own time and expertise around the Software — installation, configuration, hosting setup, training, support, and consulting are all explicitly welcome.
        
        03. CONDITIONS
        Keep this license and the copyright notice intact in all copies and substantial portions of the Software.
        Distribute modified versions under this same license, with source. Improvements to the commons stay in the commons.
        State significant changes you made, so people can tell your fork from the original.
        
        04. WHAT YOU MAY NOT DO
        You may not use the Software, or a substantially similar derivative, as the basis of a Commercial Offering. No paid clones, no selling access, no paid “Pro” editions, no bundling it into a product you charge for.
        You may not place the Software, or access to it, behind a paywall, subscription, advertising, or any other toll on the commons.
        These limits travel with the Software. You cannot relicense your way out of them.
        
        05. BRANDING & IDENTITY
        The code can be forked. The identity cannot be impersonated. You may truthfully describe your work as “based on” or “forked from” the original project.
        You may not present your fork as the official project, use its name or logo to imply endorsement, or pass off a derivative as the original.
        
        06. CONTRIBUTIONS
        Unless you say otherwise, anything you contribute back to the Software is offered under this same license, so it can benefit everyone who comes after you.
        
        07. NO WARRANTY
        The Software is provided “as is”, without warranty of any kind, express or implied. The authors are not liable for any claim, damages, or other liability arising from the Software or its use. It's a public park, not a managed service — enjoy it responsibly.
        
        08. TERMINATION
        If you violate these terms, your rights under this license end automatically. They are reinstated the moment you stop and put things right — the door back into the commons is always open.
        
        In one sentence: keep the commons open, and keep it out of the toll-booth business.
License-File: LICENSE
Keywords: cli,issue-tracker,jetbrains,rest-api,youtrack
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Bug Tracking
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: rich<14.0,>=13.7
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer<1.0,>=0.12
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: shiv>=1.0; extra == 'dev'
Description-Content-Type: text/markdown

# youtrack-cli

A CLI for the [JetBrains YouTrack REST API](https://www.jetbrains.com/help/youtrack/devportal/youtrack-rest-api.html),
developed and tested against a local YouTrack instance.

## Quick start (users)

```bash
# Install from GitHub (nothing on PyPI yet — see CHANGELOG.md)
pipx install git+https://github.com/rock3r/youtrack-cli

# After the first PyPI release:
# pipx install jetbrains-youtrack-cli

# Configure your YouTrack instance and save the token
yt auth login

# Verify
yt --version
yt status

# Search issues
yt issues --all --limit 20
yt show JT-1

# Create / edit / comment / link
yt create DEMO "Fix the widget" --type Bug --priority Major
yt edit JT-1 --state Done --summary "Fixed"
yt comment JT-1 "Verified on staging"
yt link JT-1 relates_to JT-2
```

> Global options (`--output`, `--base-url`, `--token`, `--config`, `--op-vault`,
> `--op-item`, `--op-field`, `--no-color`, `--quiet`, `--version`) must appear **before**
> the subcommand because Typer places them on the root app. Example:
> `yt --output json issues`, not `yt issues --output json`.

Run `yt --help` or `yt <command> --help` for options. Use `--output json` for scripting.

**Install:** this repo has not been published to PyPI yet. Use the `pipx install git+…`
line above, or `make standalone` for a local `dist/yt.pyz`. The PyPI package name will be
`jetbrains-youtrack-cli` when the first release is tagged.

## Authentication

`yt` needs a YouTrack base URL and a permanent API token. It looks them up in this
order:

1. Command-line flags: `--base-url` and `--token`.
2. Environment variables: `YOUTRACK_BASE_URL` and `YOUTRACK_TOKEN`.
3. A `.env` file in the current working directory.
4. The config file at `~/.config/youtrack-cli/config.toml` (written by `yt auth login`).
5. 1Password CLI (`op`): `--op-vault`, `--op-item`, and `--op-field` (or the equivalent
   `YOUTRACK_OP_*` environment variables).
6. Default base URL: `http://localhost:8080`.

If you use 1Password, the token is fetched from `op` once per command and cached for the
process lifetime. The default field is `password`; use `--op-field` to read a different
field. Example:

```bash
yt --op-vault Private --op-item "YouTrack token" --op-field "api token" status
```

Run `yt auth login` to save a token to the config file so you don't need `--token` or
`--op-*` on every invocation.

> Note: the `.env` and config-file sources are never mixed when the token comes from
> different places, so a project directory `.env` can't accidentally redirect a stored
> config token to a different server.

# Quick start (local dev environment)

Everything you need — a local YouTrack server in Apple Container, configured and
seeded with realistic JetBrains-style data — in one command:

```bash
./scripts/setup.sh
```

This installs Apple Container, runs YouTrack 2026.2, completes the first-run
wizard headlessly, mints an API token, and provisions projects/users/issues.
See **[docs/local-youtrack.md](docs/local-youtrack.md)** for full details.

| | |
|---|---|
| URL | http://localhost:8080 |
| Admin | `admin` / `Yt-Admin-2026!` |
| API token | in `.env` (`YOUTRACK_TOKEN`) |

### Verify it

```bash
source .env
curl -s -H "Authorization: Bearer $YOUTRACK_TOKEN" \
  "$YOUTRACK_BASE_URL/api/issues?query=project:JT&fields=idReadable,summary" | jq
```

## Seed data

8 projects (`JT`, `IJPL`, `IDEA`, `KT`, `RID`, `WEB`, `PY`, `DEMO`), 11 users, and
~115 issues across all states/priorities/types/subsystems — mirrors the structure of
youtrack.jetbrains.com. Issues are enriched with comments and links to exercise the
full CLI workflow. Re-provision any time with:

```bash
./scripts/provision.py && ./scripts/provision_jewel.py && ./scripts/provision_enrichment.py
```

(idempotent).

### Custom field schema (mirrors youtrack.jetbrains.com)

`provision_jewel.py` applies the exact custom-field layout from the official instance's
**Jewel** project to every project:

| Field | Type | Required | Default |
|---|---|---|---|
| Priority | enum | yes | Normal |
| Type | enum | yes | — |
| State | state | yes | Submitted |
| Subsystems | enum[*] (multi) | no | — |
| Assignee | user | no | — |
| Target version | version | yes | Backlog |
| Included in builds | build[*] (multi) | no | — |
| Available in | version[*] (multi) | no | — |
| Security Severity | enum | no | — |
| Security Problem Type | enum | no | Vulnerability |
| QA | user | no | — |
| Verified | enum | no | — |
| Verified in builds | build[*] (multi) | no | — |

Plus the YouTrack defaults (`Subsystem`, `Fix versions`, `Affected versions`,
`Fixed in build`, `Estimation`, `Spent time`) — handy for exercising every field type
in the CLI.

## Layout

```
scripts/
  setup.sh                   # one-shot install + configure + provision
  configure.py             # complete the wizard + create API token (idempotent)
  provision.py             # seed projects/users/issues (idempotent)
  provision_jewel.py       # apply the youtrack.jetbrains.com custom-field schema
  provision_enrichment.py  # add comments and links for workflow variety
  youtrack.sh              # start/stop/status/logs/shell/reset-data
  query.sh                 # example API calls (reference for building the CLI)
docs/
  local-youtrack.md
.youtrack-server/   # YouTrack persistent data (gitignored)
.env                # base URL + token (gitignored)
```

## API reference (for building the CLI)

All calls use `Authorization: Bearer $YOUTRACK_TOKEN` and return JSON.
YouTrack uses a `fields=` query param to select returned fields (see
[Fields Syntax](https://www.jetbrains.com/help/youtrack/devportal/Fields-Syntax.html)).

| Resource | Method & path |
|---|---|
| Current user | `GET /api/users/me?fields=login,fullName` |
| Issues (search) | `GET /api/issues?query=<youtrack query>&fields=...` |
| Get issue | `GET /api/issues/{id}?fields=...` |
| Create issue | `POST /api/issues` |
| Apply command | `POST /api/issues/{id}/commands` |
| Projects | `GET /api/admin/projects?fields=...` |
| Users | `GET /api/users?fields=...` |
| Custom fields | `GET /api/admin/customFieldSettings/customFields` |

Run `./scripts/query.sh` for live examples.

## License

Licensed under the **Unenshittifiable License (UEL) v1.0**. Free for internal and community
use, modification, and self-hosting. You may not repackage and sell the CLI itself as a
commercial product; improvements stay under UEL. See `LICENSE` for the full text.
