{"id":28261126,"url":"https://github.com/udamir/youtrack-workflow-cli","last_synced_at":"2026-02-01T20:03:09.261Z","repository":{"id":291303146,"uuid":"976854766","full_name":"udamir/youtrack-workflow-cli","owner":"udamir","description":"Youtrack workflow CLI","archived":false,"fork":false,"pushed_at":"2026-01-12T22:21:24.000Z","size":530,"stargazers_count":7,"open_issues_count":6,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-01-13T01:50:58.409Z","etag":null,"topics":["cli","typescript","youtrack","youtrack-workflow"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/udamir.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-02T21:57:46.000Z","updated_at":"2026-01-12T22:21:27.000Z","dependencies_parsed_at":"2025-05-03T18:52:02.350Z","dependency_job_id":"90f44275-d8a1-4bd0-9146-bc7c73bdfa97","html_url":"https://github.com/udamir/youtrack-workflow-cli","commit_stats":null,"previous_names":["udamir/youtrack-workflow-cli"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/udamir/youtrack-workflow-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/udamir%2Fyoutrack-workflow-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/udamir%2Fyoutrack-workflow-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/udamir%2Fyoutrack-workflow-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/udamir%2Fyoutrack-workflow-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/udamir","download_url":"https://codeload.github.com/udamir/youtrack-workflow-cli/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/udamir%2Fyoutrack-workflow-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28988417,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T18:17:03.387Z","status":"ssl_error","status_checked_at":"2026-02-01T18:16:57.287Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","typescript","youtrack","youtrack-workflow"],"created_at":"2025-05-20T05:12:29.164Z","updated_at":"2026-02-01T20:03:09.255Z","avatar_url":"https://github.com/udamir.png","language":"TypeScript","funding_links":["https://buymeacoffee.com/udamir"],"categories":[],"sub_categories":[],"readme":"# youtrack-workflow-cli\n\u003cimg alt=\"npm\" src=\"https://img.shields.io/npm/v/youtrack-workflow-cli\"\u003e \u003cimg alt=\"npm\" src=\"https://img.shields.io/npm/dm/youtrack-workflow-cli?label=npm\"\u003e \u003cimg alt=\"npm type definitions\" src=\"https://img.shields.io/npm/types/youtrack-workflow-cli\"\u003e \u003cimg alt=\"GitHub\" src=\"https://img.shields.io/github/license/udamir/youtrack-workflow-cli\"\u003e\n\nThe **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.\n\n## Features\n\n- **Project Initialization**: Initialize new workflow projects with interactive setup\n- **Sync Workflows**: Synchronize workflows (pull and push) between local and YouTrack\n- **Status Tracking**: Track the status of workflows with visual indicators\n- **Create new Workflow Rule**: Create a new workflow rule from a template\n- **Validate Workflows**: Run linting and type checking on workflow files\n- **Generate Types**: Create TypeScript definitions for YouTrack project custom fields and work item types\n- **Logs with Watch mode**: View logs for a workflow rules\n- **Sync with Watch mode**: Watch for file changes and push changes to YouTrack\n- **Script Hooks**: Run custom scripts before and after pushing workflows to YouTrack\n- **Conflict Resolution**: Resolve conflicts between local and server versions\n- **TypeScript Support**: Full TypeScript type definitions for YouTrack scripting API\n- **Secure Authentication**: Use permanent tokens for secure access to YouTrack API\n- **Environment Variables Support**: Configure via command line or environment variables\n\n## Quick Start\n\nGet started with YouTrack workflow development in just a few steps:\n\n### Prerequisites\n\nEnsure you have one of the following JavaScript runtimes installed:\n- [Node.js](https://nodejs.org/en/) (recommended)\n- [Bun](https://bun.sh/) (fast alternative)\n\n### 1. Initialize a New Project\n\nCreate a new workflow project using the interactive setup:\n\n```bash\nnpx youtrack-workflow-cli init [project-name]\n# or with Bun\nbunx youtrack-workflow-cli init [project-name]\n```\n\nThis command will:\n- Prompt you for project name, YouTrack URL, and authentication token (or use provided options)\n- Validate your YouTrack credentials\n- Create a complete project structure with all necessary files\n\n### 2. Navigate to Your Project\n\n```bash\ncd your-project-name\n```\n\n### 3. Install Dependencies\n\n```bash\nnpm install\n# or with Bun\nbun install\n```\n\n### 4. Verify Setup\n\n```bash\nnpx ytw list\n```\n\nThis should display the workflows available in your YouTrack instance.\n\n### 5. Start Developing\n\n```bash\nnpx ytw add    # Add workflows to your project\nnpx ytw types  # Generate TypeScript definitions (if using TypeScript)\n```\n\n### Alternative Installation\n\nIf you prefer to install the CLI globally:\n\n```bash\nnpm install -g youtrack-workflow-cli\n# or with Bun\nbun install -g youtrack-workflow-cli\n\n```\n\n## Commands\n\nThe package includes commands that let you synchronize local changes with your YouTrack installation. All commands are accessible through the `ytw` CLI tool. The following\ncommands are available:\n\n### Init\n\n```bash\nnpx ytw init [project-name] [options]\n```\n\nInitializes a new YouTrack workflow project with interactive setup. This command creates a complete project structure with all necessary configuration files.\n\n**Options:**\n- `--host \u003chost\u003e` - YouTrack base URL\n- `--token \u003ctoken\u003e` - YouTrack token\n- `--typescript` - Enable TypeScript support\n\n**Examples:**\n\n```bash\n# Interactive mode (default)\nnpx ytw init\n\n# Non-interactive with all options\nnpx ytw init my-project --host https://youtrack.example.com --token perm:abc123 --typescript\n\n# Partial options (will prompt for missing values)\nnpx ytw init my-project --typescript\n```\n\n**Features:**\n- Interactive prompts for project name, YouTrack URL, and token\n- Credential validation with retry mechanism\n- Optional TypeScript configuration\n- Creates all necessary project files (package.json, .env, eslint config, etc.)\n- Sets up proper folder structure for workflows and types\n\nThis is typically the first command you'll run when starting a new workflow project.\n\n### List\n\n```bash\nnpx ytw list\n```\n\nLists all the workflows that are available in your YouTrack installation.\n\n### Add\n\n```bash\nnpx ytw add [workflow-name...]\n```\n\nAdds 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.\n\nOptions:\n- If no workflow name is provided, it will prompt you to select from available workflows in YouTrack.\n\n### Pull\n\n```bash\nnpx ytw pull [workflow-name...] [--force]\n```\n\nDownloads the specified workflows from your YouTrack installation to your local project.\n\nOptions:\n- `-f, --force` - pull existing workflows without checking status and confirmation\n- If no workflow names are provided, it will check status and prompt you to select workflows interactively from those which are not synced.\n\n### Push\n\n```bash\nnpx ytw push [workflow-name...] [--force]\n```\n\nUploads the workflows from your local project to your YouTrack installation.\n\nOptions:\n- `-f, --force` - push existing workflows without checking status and confirmation\n- If no workflow names are provided, it will check status and prompt you to select workflows interactively from those which are not synced.\n\n### Create\n\n```bash\nnpx ytw create [workflow-name] [rule-name] [template-name]\n```\n\nCreates a new workflow rule from a template in the specified workflow folder.\n\nOptions:\n- If no arguments are provided, it will prompt you to select a workflow, enter a rule name, and choose a template.\n- Available templates include: 'action', 'custom', 'on-change', 'on-schedule', 'state-machine', and 'state-machine-per-type'.\n\n### Remove\n\n```bash\nnpx ytw remove [workflow-name...]\n```\n\nRemoves workflows from your project and optionally deletes the associated files.\n\nOptions:\n- If no workflow name is provided, it will prompt you to select which workflows to remove from those in your project.\n\n### Status\n\n```bash\nytw status\n```\n\nChecks the status of all workflows in your project and compares them with the versions in YouTrack. This command shows:\n- Which workflows are in sync\n- Which have local modifications\n- Which are outdated (the YouTrack version is newer)\n- Any conflicts between local and YouTrack versions\n\n### Sync\n\n```bash\nytw sync [workflow-name...] [--force [strategy]] [--watch] [--lint] [--type-check] [--max-warnings [number]]\n```\n\nSynchronizes workflows between your local project and YouTrack. This command:\n- Checks the status of all workflows in your project\n- Prompts you to select workflows that need to be synchronized\n- Allows you to resolve conflicts between local and YouTrack versions\n\nOptions:\n- `-f, --force [strategy]` - synchronize workflows without checking status and with specified strategy (skip, pull, push)\n- `-w, --watch` - watch for file changes and push changes to YouTrack\n- `-l, --lint` - run linting checks on workflows\n- `-t, --type-check` - run TypeScript type checking\n- `-m, --max-warnings [number]` - maximum allowed warnings\n- If no workflow names are provided, it will check status and prompt you to select workflows interactively from those which are not synced.\n\n**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.\n\n### Lint\n\n```bash\nytw lint [workflow-name...] [--type-check]\n```\n\nRuns linting checks on workflow files. This helps maintain code quality and catch potential errors early.\n\nOptions:\n- `-t, --type-check` - run TypeScript type checking\n- If no workflow names are provided, it will lint all workflows in your project.\n\n**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](#configuration-in-packagejson) section for details.\n\n\nEslint config (`eslint.config.js`) example:\n```js\nconst js = require('@eslint/js');\n\nmodule.exports = [\n  js.configs.recommended,\n  {\n    files: ['**/*.js'],\n    languageOptions: {\n      ecmaVersion: 2022,\n      sourceType: 'commonjs',\n      globals: {\n        console: 'readonly',\n        require: 'readonly',\n      },\n    },\n    rules: {\n      'no-var': 'error',\n      'prefer-const': 'error',\n      'no-console': 'warn',\n      'no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],\n    },\n  },\n];\n```\n\n### Logs\n\n```bash\nytw logs [targets...] [--watch [ms]] [--all] [--top \u003cnumber\u003e] [--last \u003cnumber\u003e] [--since \u003cvalue\u003e]\n```\n\nView logs for workflow rules. This helps you monitor the behavior of your workflows in real-time.\n\n**Arguments:**\n- `[targets...]` - Workflow names or workflow/rule paths. Supports two formats:\n  - `workflow-name` - Target a workflow (will prompt for rule selection or use `--all`)\n  - `workflow-name/rule-name` - Target a specific rule directly (no prompt)\n\n**Options:**\n- `-t, --top \u003cnumber\u003e` - Number of logs to fetch per rule (default: 10)\n- `-l, --last \u003cnumber\u003e` - Show only the last N log entries (tail)\n- `-s, --since \u003cvalue\u003e` - Show logs since timestamp or duration. Supports:\n  - Unix timestamp: `1768577702000`\n  - Duration: `5m`, `1h`, `2d`, `1w`\n  - Compound duration: `\"1h 30m\"`, `\"2d 5h 15m\"`\n- `-w, --watch [ms]` - Watch for new logs in real-time (default interval: 5000ms)\n- `-a, --all` - Fetch logs for all rules in the workflow(s)\n\n**Examples:**\n\n```bash\n# View logs for a specific rule (no prompt)\nytw logs my-workflow/my-rule\n\n# View logs for multiple specific rules\nytw logs workflow1/rule1 workflow2/rule2\n\n# View logs for a workflow (prompts for rule selection)\nytw logs my-workflow\n\n# View all logs for a workflow\nytw logs my-workflow --all\n\n# Watch logs for a specific rule\nytw logs my-workflow/my-rule --watch\n\n# Mixed: specific rule + workflow selection\nytw logs workflow1/rule1 workflow2\n\n# Show only the last 10 log entries\nytw logs my-workflow/my-rule --last 10\n\n# Show logs from the last 5 minutes\nytw logs my-workflow/my-rule --since 5m\n\n# Show logs from the last 1 hour and 30 minutes\nytw logs my-workflow/my-rule --since \"1h 30m\"\n\n# Combine options: last 20 logs from the past hour\nytw logs my-workflow/my-rule --since 1h --last 20\n```\n\n### Types\n\n```bash\nytw types [project-id]\n```\n\nGenerates 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.\n\nThe 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`.\n\nOptions:\n- If no project ID is provided, it will prompt you to select from available projects in YouTrack.\n\n### Status Symbols\n\nThe status command uses the following symbols to indicate workflow status:\n\n| Symbol | Status   | Description                                    |\n| ------ | -------- | ---------------------------------------------- |\n| ✓      | Synced   | Local files match YouTrack version             |\n| ↑      | Modified | Local files have changes not in YouTrack       |\n| ↓      | Outdated | YouTrack version is ahead of local files       |\n| !      | Conflict | Both local and YouTrack versions have changes  |\n| +      | New      | Local files exist but workflow not in YouTrack |\n\n### Common Parameters\n\nMost commands require the following parameters:\n\n| Parameter | Description                                                                                                                                                                                                                                            |\n| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| --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.                                                                                 |\n| --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. |\n\n## Environment Variables\n\nYou can set the following environment variables to avoid passing host and token parameters with each command:\n\n```bash\nYOUTRACK_BASE_URL=https://youtrack.example.com\nYOUTRACK_TOKEN=your-permanent-token\n```\n\n## TypeScript Type Definitions\n\nYou can use [youtrack-workflow-api-types](https://github.com/udamir/youtrack-workflow-api-types) package and generated types for your project to write type-safe workflows.\n\n```bash\nnpm install --save-dev youtrack-workflow-api-types typescript\n```\n\nAdd `paths` to your project's `tsconfig.json` with following content:\n\n```json\n{\n  \"compilerOptions\": {\n    \"checkJs\": true,\n    \"allowJs\": true,\n    \"resolveJsonModule\": true,\n    \"moduleResolution\": \"node\",\n    \"target\": \"es2020\",\n    \"module\": \"commonjs\",\n    \"baseUrl\": \".\",\n    \"paths\": {\n      \"@jetbrains/youtrack-scripting-api\": [\"node_modules/youtrack-workflow-api-types\"],\n      \"@jetbrains/youtrack-scripting-api/*\": [\"node_modules/youtrack-workflow-api-types/*\"]\n    }\n  },\n  \"include\": [\n    \"**/*.js\"\n  ],\n  \"exclude\": [\n    \"node_modules\"\n  ]\n}\n```\n\nAdd [JSDoc annotations](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html) to your workflow files:\n\n```js\n/** @import { Issue } from '../types/demo' */ // Default location\n// or from custom location: '../custom-types/demo' if typesFolder is configured\n\nexports.rule = entities.Issue.onChange({\n  title: 'example',\n  action: (ctx) =\u003e {\n    /** @type {Issue} */\n    const issue = ctx.issue;    \n   \n    // Use typescript validation for issue fields and work items\n  }\n});\n```\n\n## Configuration in package.json\n\nYou can configure your workflow management in your project's `package.json` file using the `ytw` section:\n\n```json\n{\n  \"ytw\": {\n    \"linting\": {\n      \"enableEslint\": true,\n      \"enableTypeCheck\": false,\n      \"failOnWarnings\": false,\n      \"maxWarnings\": 10,\n      \"include\": [\"workflow1\", \"workflow2\"],\n      \"exclude\": [\"legacy-workflow\", \"experimental-workflow\"]\n    },\n    \"prepush\": \"your-script-command\",\n    \"postpush\": \"your-script-command\",\n    \"typesFolder\": \"./custom-types\"\n  }\n}\n```\n\n### Available options:\n\n#### Linting configuration:\n\n- `enableEslint` (boolean): Enable or disable ESLint checks during linting and sync commands.\n- `enableTypeCheck` (boolean): Enable or disable TypeScript type checking during linting and sync commands.\n- `failOnWarnings` (boolean): Whether lint warnings should cause the command to fail.\n- `maxWarnings` (number): Maximum number of warnings allowed before the linting fails.\n- `include` (string[]): Array of workflow names to include in linting. If specified, only these workflows will be linted.\n- `exclude` (string[]): Array of workflow names to exclude from linting. These workflows will never be linted, even if they're in the include list.\n\n#### Script hooks:\n\n- `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.\n- `postpush` (string): Script to run after successfully pushing a workflow to YouTrack.\n\n#### Type definitions:\n\n- `typesFolder` (string): Custom folder path for TypeScript type definitions generated by the `types` command. Defaults to `/types` if not specified. Can be relative (e.g., `\"./custom-types\"`) or absolute path.\n\nThese 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.\n\nExample usage:\n\n```json\n{\n  \"ytw\": {\n    \"prepush\": \"node scripts/validate-workflow.js\",\n    \"postpush\": \"node scripts/notify-team.js\"\n  }\n}\n```\n\n## Special Instructions for SSL Certificates\n\nIf 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.\n\nFor more information, [refer to the YouTrack documentation](https://www.jetbrains.com/help/youtrack/incloud/js-workflow-external-editor.html#special-instructions-ssl-certificates).\n\n## Support\n\n[Buy me a coffee](https://buymeacoffee.com/udamir)\n\n# License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fudamir%2Fyoutrack-workflow-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fudamir%2Fyoutrack-workflow-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fudamir%2Fyoutrack-workflow-cli/lists"}