The youtrack-workflow-cli package contains utilities that help you manage YouTrack workflows when you work in an external code editor. This lets you write and update workflows for YouTrack in JavaScript in your preferred development environment.
- Project Initialization: Initialize new workflow projects with interactive setup
- Sync Workflows: Synchronize workflows (pull and push) between local and YouTrack
- Status Tracking: Track the status of workflows with visual indicators
- Create new Workflow Rule: Create a new workflow rule from a template
- Validate Workflows: Run linting and type checking on workflow files
- Generate Types: Create TypeScript definitions for YouTrack project custom fields and work item types
- Logs with Watch mode: View logs for a workflow rules
- Sync with Watch mode: Watch for file changes and push changes to YouTrack
- Script Hooks: Run custom scripts before and after pushing workflows to YouTrack
- Conflict Resolution: Resolve conflicts between local and server versions
- TypeScript Support: Full TypeScript type definitions for YouTrack scripting API
- Secure Authentication: Use permanent tokens for secure access to YouTrack API
- Environment Variables Support: Configure via command line or environment variables
Get started with YouTrack workflow development in just a few steps:
Ensure you have one of the following JavaScript runtimes installed:
Create a new workflow project using the interactive setup:
npx youtrack-workflow-cli init [project-name]
# or with Bun
bunx youtrack-workflow-cli init [project-name]This command will:
- Prompt you for project name, YouTrack URL, and authentication token (or use provided options)
- Validate your YouTrack credentials
- Create a complete project structure with all necessary files
cd your-project-namenpm install
# or with Bun
bun installnpx ytw listThis should display the workflows available in your YouTrack instance.
npx ytw add # Add workflows to your project
npx ytw types # Generate TypeScript definitions (if using TypeScript)If you prefer to install the CLI globally:
npm install -g youtrack-workflow-cli
# or with Bun
bun install -g youtrack-workflow-cli
The package includes commands that let you synchronize local changes with your YouTrack installation. All commands are accessible through the ytw CLI tool. The following
commands are available:
npx ytw init [project-name] [options]Initializes a new YouTrack workflow project with interactive setup. This command creates a complete project structure with all necessary configuration files.
Options:
--host <host>- YouTrack base URL--token <token>- YouTrack token--typescript- Enable TypeScript support
Examples:
# Interactive mode (default)
npx ytw init
# Non-interactive with all options
npx ytw init my-project --host https://youtrack.example.com --token perm:abc123 --typescript
# Partial options (will prompt for missing values)
npx ytw init my-project --typescriptFeatures:
- Interactive prompts for project name, YouTrack URL, and token
- Credential validation with retry mechanism
- Optional TypeScript configuration
- Creates all necessary project files (package.json, .env, eslint config, etc.)
- Sets up proper folder structure for workflows and types
This is typically the first command you'll run when starting a new workflow project.
npx ytw listLists all the workflows that are available in your YouTrack installation.
npx ytw add [workflow-name...]Adds one or more workflows to your project. If no workflow names are specified, you'll be prompted to select from available workflows in YouTrack. The workflow information is stored in ytw.lock file.
Options:
- If no workflow name is provided, it will prompt you to select from available workflows in YouTrack.
npx ytw pull [workflow-name...] [--force]Downloads the specified workflows from your YouTrack installation to your local project.
Options:
-f, --force- pull existing workflows without checking status and confirmation- If no workflow names are provided, it will check status and prompt you to select workflows interactively from those which are not synced.
npx ytw push [workflow-name...] [--force]Uploads the workflows from your local project to your YouTrack installation.
Options:
-f, --force- push existing workflows without checking status and confirmation- If no workflow names are provided, it will check status and prompt you to select workflows interactively from those which are not synced.
npx ytw create [workflow-name] [rule-name] [template-name]Creates a new workflow rule from a template in the specified workflow folder.
Options:
- If no arguments are provided, it will prompt you to select a workflow, enter a rule name, and choose a template.
- Available templates include: 'action', 'custom', 'on-change', 'on-schedule', 'state-machine', and 'state-machine-per-type'.
npx ytw remove [workflow-name...]Removes workflows from your project and optionally deletes the associated files.
Options:
- If no workflow name is provided, it will prompt you to select which workflows to remove from those in your project.
ytw statusChecks the status of all workflows in your project and compares them with the versions in YouTrack. This command shows:
- Which workflows are in sync
- Which have local modifications
- Which are outdated (the YouTrack version is newer)
- Any conflicts between local and YouTrack versions
ytw sync [workflow-name...] [--force [strategy]] [--watch] [--lint] [--type-check] [--max-warnings [number]]Synchronizes workflows between your local project and YouTrack. This command:
- Checks the status of all workflows in your project
- Prompts you to select workflows that need to be synchronized
- Allows you to resolve conflicts between local and YouTrack versions
Options:
-f, --force [strategy]- synchronize workflows without checking status and with specified strategy (skip, pull, push)-w, --watch- watch for file changes and push changes to YouTrack-l, --lint- run linting checks on workflows-t, --type-check- run TypeScript type checking-m, --max-warnings [number]- maximum allowed warnings- If no workflow names are provided, it will check status and prompt you to select workflows interactively from those which are not synced.
Note: When linting is enabled (--lint or --type-check), the sync command respects the include and exclude configuration in your package.json. Workflows excluded from linting will be synced but won't be linted during the process.
ytw lint [workflow-name...] [--type-check]Runs linting checks on workflow files. This helps maintain code quality and catch potential errors early.
Options:
-t, --type-check- run TypeScript type checking- If no workflow names are provided, it will lint all workflows in your project.
Note: The lint command respects the include and exclude configuration in your package.json. Workflows can be filtered based on these settings - see the Configuration section for details.
Eslint config (eslint.config.js) example:
const js = require('@eslint/js');
module.exports = [
js.configs.recommended,
{
files: ['**/*.js'],
languageOptions: {
ecmaVersion: 2022,
sourceType: 'commonjs',
globals: {
console: 'readonly',
require: 'readonly',
},
},
rules: {
'no-var': 'error',
'prefer-const': 'error',
'no-console': 'warn',
'no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
},
},
];ytw logs [workflow-name...] [--watch [ms]] [--all] [--top <number>]View logs for a selected workflow rules. This helps you monitor the behavior of your workflows in real-time.
Options:
-w, --watch [ms]- watch for new logs in YouTrack in real-time with interval in milliseconds, default: 5000ms.-a, --all- fetch all logs for rules of all workflows in project-t, --top [number]- number of logs to fetch per rule, default: 10- If workflow names are provided and
--allis not specified, it will prompt you to select rules from provided workflows.
ytw types [project-id]Generates TypeScript type definitions for a YouTrack project's custom fields and work item types. This helps maintain type safety when developing workflows for specific projects.
The generated type definitions are saved to the /types folder by default, but you can customize this location using the typesFolder configuration in your package.json.
Options:
- If no project ID is provided, it will prompt you to select from available projects in YouTrack.
The status command uses the following symbols to indicate workflow status:
| Symbol | Status | Description |
|---|---|---|
| ✓ | Synced | Local files match YouTrack version |
| ↑ | Modified | Local files have changes not in YouTrack |
| ↓ | Outdated | YouTrack version is ahead of local files |
| ! | Conflict | Both local and YouTrack versions have changes |
| + | New | Local files exist but workflow not in YouTrack |
Most commands require the following parameters:
| Parameter | Description |
|---|---|
| --host | The base URL of your YouTrack installation. For an InCloud instance, include the trailing /youtrack. Can also be set via the YOUTRACK_BASE_URL environment variable. |
| --token | A permanent token that grants access to the YouTrack service. You can generate your own permanent tokens to authenticate with YouTrack on the Authentication tab of your Hub profile. Can also be set via the YOUTRACK_TOKEN environment variable. |
You can set the following environment variables to avoid passing host and token parameters with each command:
YOUTRACK_BASE_URL=https://youtrack.example.com
YOUTRACK_TOKEN=your-permanent-tokenYou can use youtrack-workflow-api-types package and generated types for your project to write type-safe workflows.
npm install --save-dev youtrack-workflow-api-types typescriptAdd paths to your project's tsconfig.json with following content:
{
"compilerOptions": {
"checkJs": true,
"allowJs": true,
"resolveJsonModule": true,
"moduleResolution": "node",
"target": "es2020",
"module": "commonjs",
"baseUrl": ".",
"paths": {
"@jetbrains/youtrack-scripting-api": ["node_modules/youtrack-workflow-api-types"],
"@jetbrains/youtrack-scripting-api/*": ["node_modules/youtrack-workflow-api-types/*"]
}
},
"include": [
"**/*.js"
],
"exclude": [
"node_modules"
]
}Add JSDoc annotations to your workflow files:
/** @import { Issue } from '../types/demo' */ // Default location
// or from custom location: '../custom-types/demo' if typesFolder is configured
exports.rule = entities.Issue.onChange({
title: 'example',
action: (ctx) => {
/** @type {Issue} */
const issue = ctx.issue;
// Use typescript validation for issue fields and work items
}
});You can configure your workflow management in your project's package.json file using the ytw section:
{
"ytw": {
"linting": {
"enableEslint": true,
"enableTypeCheck": false,
"failOnWarnings": false,
"maxWarnings": 10,
"include": ["workflow1", "workflow2"],
"exclude": ["legacy-workflow", "experimental-workflow"]
},
"prepush": "your-script-command",
"postpush": "your-script-command",
"typesFolder": "./custom-types"
}
}enableEslint(boolean): Enable or disable ESLint checks during linting and sync commands.enableTypeCheck(boolean): Enable or disable TypeScript type checking during linting and sync commands.failOnWarnings(boolean): Whether lint warnings should cause the command to fail.maxWarnings(number): Maximum number of warnings allowed before the linting fails.include(string[]): Array of workflow names to include in linting. If specified, only these workflows will be linted.exclude(string[]): Array of workflow names to exclude from linting. These workflows will never be linted, even if they're in the include list.
prepush(string): Script to run before pushing workflows to YouTrack. If this script fails (returns non-zero exit code), the push operation will be aborted.postpush(string): Script to run after successfully pushing a workflow to YouTrack.
typesFolder(string): Custom folder path for TypeScript type definitions generated by thetypescommand. Defaults to/typesif not specified. Can be relative (e.g.,"./custom-types") or absolute path.
These scripts are executed with the workflowName (and ruleName in sync with watch mode) passed as arguments, which allows you to perform different actions based on which workflow is being processed.
Example usage:
{
"ytw": {
"prepush": "node scripts/validate-workflow.js",
"postpush": "node scripts/notify-team.js"
}
}If your YouTrack domain uses an SSL certificate that is issued by a known certificate authority, you can establish a connection using just your personal permanent token. Your certificate is already included in CA certificate store that is built into Node.js. For certificates that are issued by a CA that is not recognized automatically or is self-signed, you need to modify the environment variables in Node.js to recognize or ignore your certificate.
For more information, refer to the YouTrack documentation.
MIT