Download the PHP package visualbuilder/youtrack-cli without Composer

YouTrack CLI

Laravel artisan commands, MCP tools, and a webhook receiver for driving YouTrack issue workflows from terminals, scripts, and AI agents.

20 commands, 20 MCP tools, structured-error JSON envelopes, multi-instance config, signed-webhook receiver. Designed to be the source of truth any consumer (coding agent, CI pipeline, developer's terminal, MCP-aware IDE, slash command) can call.

Install

The service provider auto-registers; no manual wiring needed. Optionally publish the config to override workflow state names:

If you drive YouTrack with Claude Code, install the bundled slash-command skill into your host's .claude/commands/:

/youtrack then gives Claude the full command surface, lifecycle walkthrough, and project-setup pointers as context.

Configure

Set in your host .env:

Workflow-state names default to a sensible 10-step lifecycle (Ready for Dev → In Progress → Code Review → … → Done) and are env-overridable via config/youtrack.php.

Custom priority and type vocabularies

Hosts that don't use the stock Bug / Feature / Task types or P1–P5 priority grades configure their own under youtrack.priorities and youtrack.types:

The values arrays drive the CreateIssue MCP tool's JSON-schema enums, so AI agents see exactly which values your YouTrack project accepts. Leave a list empty to disable the constraint and fall back to "anything goes".

Multi-workspace

Talking to more than one YouTrack workspace? Add another entry under youtrack.connections:

Every artisan command accepts --instance=NAME; programmatic callers use (new YouTrackService())->on('support') or app(IssueService::class)->on('support'). Single-workspace hosts only need the default entry.

MCP server (optional)

When laravel/mcp is installed, the package registers a youtrack MCP server exposing every artisan command as an agent-callable tool. Disable via YOUTRACK_MCP_ENABLED=false if you want CLI-only.

Webhook receiver

Inbound YouTrack webhooks land at POST /youtrack/webhook. Configure the same secret in your YouTrack project's webhook settings and in .env:

Subscribe to Visualbuilder\YoutrackCli\Events\YoutrackWebhookReceived from the host's EventServiceProvider to react to deliveries. The package itself ships zero default behaviour — what to do with an event is a host concern. Idempotent on X-YouTrack-Delivery-Id for 24h.

YouTrack project setup

The CLI reads YouTrack custom fields by exact name. Two configurable buckets:

Required fields (stock YouTrack defaults)

The CLI cannot do useful work without these. They're shipped with every YouTrack project — nothing to configure unless your project has been customised.

"state" vs "Status" — we picked state as the public-surface name (it's the standard term in workflow engines), but on the wire the package reads/writes YouTrack's Status custom field. They mean the same thing: the column a ticket sits in on your kanban board.

If your project diverges (some YouTrack tenants enforce additional required fields), extend the list:

Recommended fields (host-specific)

Empty by default — populate with whatever fields your workflow expects beyond the stock trio. Examples from the agentic ecosystem this package was extracted from:

Add these in Project Settings → Fields in the YouTrack UI. They're optional — youtrack:check-project reports them as recommended.missing rather than failing.

Anything else

Custom fields not in either list still work transparently — get-issue returns the full untouched custom_fields map, and set-field writes any field by exact name:

Verifying your setup

Run the doctor command after configuring the project — it returns exit code 0 when every required field is present and 1 when something's missing.

Recommended state vocabulary

The package's default state names match a ten-step development lifecycle. If your YouTrack project's Status enum values are different, override them in config/youtrack.php (or via env in your service provider) — every list/update command resolves through that map, no hard-coded strings in command bodies.

Adding new states is a config-only change; the CLI never hard-codes a value beyond what config('youtrack.states.*') returns.

Commands

Every command writes a JSON document to stdout — friendly for jq, AI agents, and shell pipelines.

Listing tickets by state

Inspecting one ticket

Returns full details: summary, description, state, priority, type, custom fields (PR URL, assignee, etc.), and every comment.

Searching

Free-text search over summaries and descriptions.

Creating a ticket

Defaults: --type=Bug, --priority=P3 (valid: P0 highest — P5 lowest, types: Bug, Enhancement, Feature, …).

Moving workflow state

Pass the human-readable state name exactly as it appears on your board.

Custom fields

Common one — saves a PR link as a custom field on the ticket.

Comments

Markdown supported.

Bulk fingerprint search

Hits multiple error-fingerprint hashes in a single API call — used by error-monitoring pipelines to dedupe before opening new tickets.

Checking project setup

Audits the project's custom fields against tier 1 (required) and tier 2 (recommended). Exit code 0 when ready, 1 when a tier-1 field is missing or the project doesn't exist. See YouTrack project setup below.

Programmatic use

Inject the service classes:

IssueService wraps every command's logic; YouTrackService is the underlying HTTP client.

License

GPL-2.0-or-later.