# Jira on boxd

> A tool for bug tracking, issue tracking, and agile project management.

- Page: https://boxd.sh/integrations/jira/
- CLI: `run jira` (100 commands, 61 marked common)
- SDK: `import { jira } from "@boxd/run"`; every parameter and response type is at `@boxd/run/jira`
- Triggers: 3
- Connect: `run auth jira` (Sign in with Jira), or https://app.boxd.sh/integrations/detail/jira
- All integrations: https://boxd.sh/integrations/ (Markdown: https://boxd.sh/integrations/index.md)

## From the shell

```sh
run auth jira      # once: prints a link to connect your account
run jira           # list its commands
run jira get-current-user
```

Parameters are flags (`--flag value`); object and array parameters take a JSON string. Output is YAML, or JSON with `--json`. Calls use your own connection; `--scope <name>` uses a connection shared with your team.

## From a script

```ts
import { jira } from "@boxd/run";

const result = await jira.getCurrentUser({});
console.log(result);

jira.on("new-project", async (event) => {
  // New Project: runs on this machine, once per event
  console.log(event);
});
```

Run it with `run jira.run.ts`. A script that calls `.on()` keeps running as a job and handles each event.

## Commands

Required flags are listed; `run jira <command> --help` lists the optional ones. "common" marks what `run jira` shows without `--all`.

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `add-attachment` ·common | `jira.addAttachment()` | `--file-to-upload` `--issue-key` | 0 | Uploads and attaches a file to a Jira issue |
| `add-comment` ·common | `jira.addComment()` | `--comment` `--issue-id-or-key` | 3 | Adds a comment using Atlassian Document Format (ADF) for rich text to an existing Jira issue |
| `add-user-to-group` ·common | `jira.addUserToGroup()` | `--account-id` | 2 | Adds a user to a Jira group |
| `add-users-to-project-role` ·common | `jira.addUsersToProjectRole()` | `--project-id-or-key` `--role-id` | 3 | Adds users and optionally groups to a project role |
| `add-watcher-to-issue` ·common | `jira.addWatcherToIssue()` | `--account-id` `--issue-id-or-key` | 0 | Adds a user to an issue's watcher list by account ID |
| `add-worklog` ·common | `jira.addWorklog()` | `--issue-id-or-key` | 11 | Add a worklog entry to a Jira issue |
| `analyse-expression` | `jira.analyseExpression()` | `--expressions` | 2 | Analyses Jira expressions for syntax validation, type checking, and complexity analysis |
| `assign-issue` ·common | `jira.assignIssue()` | `--issue-id-or-key` | 2 | Assigns a Jira issue to a user, default assignee, or unassigns; supports email/name lookup |
| `bulk-create-issue` ·common | `jira.bulkCreateIssue()` | `--issues` | 0 | Creates multiple Jira issues (up to 50 per call) with full feature support including markdown, assignee resolution, and priority handling |
| `check-permissions` | `jira.checkPermissions()` | — | 3 | Check user permissions for global and project-level operations in Jira |
| `create-board` ·common | `jira.createBoard()` | `--name` `--type` | 2 | Creates a new Jira board (kanban, scrum, or agility) with optional filter and location configuration |
| `create-group` ·common | `jira.createGroup()` | `--name` | 0 | Creates a new group in Jira with the specified name |
| `create-issue` ·common | `jira.createIssue()` | `--issue-type` `--project-key` `--summary` | 14 | Creates a new Jira issue (e.g., bug, task, story) in a specified project |
| `create-issue-link` ·common | `jira.createIssueLink()` | `--inward-issue-key` `--outward-issue-key` | 3 | Links two Jira issues using a specified link type with optional comment |
| `create-jql-autocompletedata` | `jira.createJqlAutocompletedata()` | — | 2 | Retrieves JQL autocomplete reference data including reserved words, field names, and function names |
| `create-project` ·common | `jira.createProject()` | `--key` `--lead-account-id` `--name` `--project-template-key` `--project-type-key` | 9 | Creates a new Jira project with required lead, template, and type configuration |
| `create-sprint` ·common | `jira.createSprint()` | `--name` `--origin-board-id` | 4 | Creates a new sprint on a Jira board with optional start/end dates and goal |
| `create-version` ·common | `jira.createVersion()` | `--name` `--projectId` | 6 | Creates a new version for releases or milestones in a Jira project |
| `delete-attachment` | `jira.deleteAttachment()` | `--attachment-id` | 0 | Permanently deletes an attachment from Jira by its ID |
| `delete-comment` | `jira.deleteComment()` | `--id` `--issueIdOrKey` | 0 | Deletes a specific comment from a Jira issue using its ID and the issue's ID/key; requires user permission to delete comments on the issue |
| `delete-issue` ·common | `jira.deleteIssue()` | `--issue-id-or-key` | 1 | Permanently and irreversibly deletes a Jira issue by its ID or key |
| `delete-version` | `jira.deleteVersion()` | `--version-id` | 2 | Deletes a Jira version and optionally reassigns its issues |
| `delete-worklog` | `jira.deleteWorklog()` | `--issue-id-or-key` `--worklog-id` | 5 | Deletes a worklog from a Jira issue with estimate adjustment options |
| `edit-issue` ·common | `jira.editIssue()` | `--issue-id-or-key` | 14 | Updates an existing Jira issue with field values and operations |
| `evaluate-expression` | `jira.evaluateExpression()` | `--expression` | 2 | Evaluate Jira expressions using the enhanced search API |
| `fetch-bulk-issues` ·common | `jira.fetchBulkIssues()` | `--issueIdsOrKeys` | 4 | Bulk fetch multiple Jira issues by their IDs or keys (max 100 per call) |
| `find-users` ·common ·deprecated | `jira.findUsers()` | — | 5 | Use find-users2 instead |
| `find-users-for-picker` | `jira.findUsersForPicker()` | `--query` | 5 | Find users for picker components by matching query against user attributes like display name and email |
| `find-users2` | `jira.findUsers2()` | — | 6 | Find users in Jira by query string, account ID, or property search |
| `get-all-groups` ·common | `jira.getAllGroups()` | — | 2 | Retrieves a page of groups from the Jira instance |
| `get-all-issue-type-schemes` | `jira.getAllIssueTypeSchemes()` | — | 3 | Retrieves all Jira issue type schemes with optional filtering and pagination |
| `get-all-projects` ·common | `jira.getAllProjects()` | — | 10 | Retrieves all visible projects using the modern paginated Jira API with server-side filtering and pagination support |
| `get-all-statuses` | `jira.getAllStatuses()` | — | 0 | Retrieves all issue statuses associated with workflows from Jira |
| `get-all-users` ·common | `jira.getAllUsers()` | — | 2 | Retrieves all users from the Jira instance including active, inactive, app accounts, and system accounts, with pagination support |
| `get-attachment` ·common | `jira.getAttachment()` | `--attachment-id` `--file-name` | 0 | Retrieves the binary content of a Jira attachment by ID |
| `get-attachment-meta` ·common | `jira.getAttachmentMeta()` | — | 0 | Retrieve Jira attachment settings including upload limits and enabled status |
| `get-comment` | `jira.getComment()` | `--comment-id` `--issue-id-or-key` | 1 | Retrieves a specific comment by ID from a Jira issue with optional expansions |
| `get-components` ·common | `jira.getComponents()` | — | 5 | Retrieve components from Jira projects with search and filtering |
| `get-create-metadata-issue-type-fields` ·common | `jira.getCreateMetadataIssueTypeFields()` | `--issueTypeId` `--projectIdOrKey` | 2 | Retrieve field metadata for a specific issue type in a project |
| `get-current-user` ·common | `jira.getCurrentUser()` | — | 1 | Retrieves detailed information about the currently authenticated Jira user |
| `get-dashboards` ·common | `jira.getDashboards()` | — | 3 | List and search Jira dashboards visible to the current user |
| `get-favorite-filters` ·common | `jira.getFavoriteFilters()` | — | 1 | Retrieve favorite filters for the current user |
| `get-fields` ·common | `jira.getFields()` | — | 3 | Retrieve Jira issue fields metadata |
| `get-fields-paginated` ·common | `jira.getFieldsPaginated()` | — | 8 | Retrieve Jira fields in pages |
| `get-filter` ·common | `jira.getFilter()` | `--id` | 2 | Retrieves a specific Jira saved filter by ID, including its JQL and sharing metadata, to reuse in subsequent searches |
| `get-group` ·common | `jira.getGroup()` | — | 3 | Retrieves details of a specific Jira group by name or ID |
| `get-info` | `jira.getInfo()` | — | 0 | Retrieves runtime information for the Jira Service Management instance |
| `get-issue` ·common | `jira.getIssue()` | `--issue-key` | 5 | Retrieves a Jira issue by ID or key with customizable fields and expansions |
| `get-issue-create-metadata` ·common ·deprecated | `jira.getIssueCreateMetadata()` | — | 5 | Use get-create-metadata-issue-type-fields instead |
| `get-issue-edit-metadata` ·common | `jira.getIssueEditMetadata()` | `--issue-id-or-key` | 2 | Retrieve editable fields for a Jira issue |
| `get-issue-link-types` | `jira.getIssueLinkTypes()` | — | 0 | Retrieves all configured issue link types from Jira |
| `get-issue-picker-suggestions` ·common | `jira.getIssuePickerSuggestions()` | — | 6 | Get issue picker suggestions from Jira |
| `get-issue-property` | `jira.getIssueProperty()` | `--issue-id-or-key` `--property-key` | 0 | Retrieves a custom property from a Jira issue by key |
| `get-issue-resolutions` | `jira.getIssueResolutions()` | — | 0 | Retrieves all available issue resolution types from Jira |
| `get-issue-types` ·common | `jira.getIssueTypes()` | — | 0 | Retrieves all Jira issue types available to the user using the modern API v3 endpoint; results vary based on 'Administer Jira' global or 'Browse projects' project permissions |
| `get-issue-watchers` | `jira.getIssueWatchers()` | `--issue-id-or-key` | 0 | Retrieves users watching a Jira issue for update notifications |
| `get-issue-worklogs` ·deprecated | `jira.getIssueWorklogs()` | `--issue-id-or-key` | 4 | Use get-worklog instead |
| `get-jql-autocompletedata` | `jira.getJqlAutocompletedata()` | — | 0 | Retrieve JQL autocomplete reference data |
| `get-jql-autocompletedata-suggestions` | `jira.getJqlAutocompletedataSuggestions()` | — | 4 | Get JQL field auto-complete suggestions |
| `get-my-permissions` ·common | `jira.getMyPermissions()` | `--permissions` | 7 | Retrieve the user's permissions in Jira |
| `get-mypreferences-locale` | `jira.getMypreferencesLocale()` | — | 0 | Retrieve the locale preference of the currently authenticated Jira user |
| `get-permissions` | `jira.getPermissions()` | — | 0 | Retrieve all available Jira permissions |
| `get-permitted-projects` | `jira.getPermittedProjects()` | `--permissions` | 0 | Retrieve projects where the current user has specific permissions |
| `get-project` ·common | `jira.getProject()` | `--project-id-or-key` | 2 | Retrieves details of a Jira project by its ID or key |
| `get-project-roles` ·common | `jira.getProjectRoles()` | `--project-id-or-key` | 0 | Retrieves all available roles for a Jira project |
| `get-project-templates` ·common | `jira.getProjectTemplates()` | — | 1 | Retrieves available Jira project templates for creating projects |
| `get-project-type` | `jira.getProjectType()` | `--project-type-key` | 0 | Retrieves detailed information about a specific Jira project type by its key |
| `get-project-versions` | `jira.getProjectVersions()` | `--project-id-or-key` | 1 | Retrieves all versions for a Jira project with optional expansion |
| `get-recent-projects` ·common | `jira.getRecentProjects()` | — | 2 | Retrieves a list of projects recently accessed by the authenticated user |
| `get-remote-issue-links` | `jira.getRemoteIssueLinks()` | `--issue-id-or-key` | 1 | Retrieves links from a Jira issue to external resources |
| `get-server-info` ·common | `jira.getServerInfo()` | — | 0 | Retrieve Jira instance server information |
| `get-service-desk-request-type-fields` ·common | `jira.getServiceDeskRequestTypeFields()` | `--requestTypeId` `--serviceDeskId` | 0 | Retrieve JSM request type field metadata for filling out portal requests |
| `get-sprint` ·common | `jira.getSprint()` | `--sprint-id` | 0 | Retrieves detailed information about a specific sprint by its ID |
| `get-system-avatars` | `jira.getSystemAvatars()` | `--type` | 0 | Retrieve all system avatars for a specific type (issuetype, project, user, or priority) |
| `get-transitions` ·common | `jira.getTransitions()` | `--issue-id-or-key` | 5 | Retrieves available workflow transitions for a Jira issue |
| `get-universal-avatar-type-owner` | `jira.getUniversalAvatarTypeOwner()` | `--entityId` `--type` | 0 | Retrieve all avatars (system and custom) for a specific type and entity in Jira |
| `get-universal-avatar-view-type` | `jira.getUniversalAvatarViewType()` | `--type` | 2 | Retrieve the default avatar image for a specific type (project, issuetype, or priority) from Jira |
| `get-user-groups` ·common | `jira.getUserGroups()` | `--account-id` | 0 | Retrieves all groups for a specific Jira user by account ID |
| `get-view-type-avatar` | `jira.getViewTypeAvatar()` | `--id` `--type` | 2 | Retrieve a specific avatar image by type and ID from Jira |
| `get-votes` | `jira.getVotes()` | `--issue-id-or-key` | 0 | Fetches voting details for a Jira issue; requires voting to be enabled in Jira's general settings |
| `get-worklog` | `jira.getWorklog()` | `--issue-id-or-key` | 5 | Retrieves worklogs for a specified Jira issue |
| `list-all-projects` ·common ·deprecated | `jira.listAllProjects()` | — | 3 | Use get-all-projects instead |
| `list-boards` ·common | `jira.listBoards()` | — | 7 | Retrieves paginated Jira boards with filtering and sorting options |
| `list-comments` | `jira.listComments()` | `--ids` | 1 | Retrieve multiple comments by their IDs in a single request |
| `list-filters` ·common | `jira.listFilters()` | — | 11 | Search and list Jira saved filters (saved searches) visible to the current user |
| `list-groups-picker` ·common | `jira.listGroupsPicker()` | — | 5 | Search and list groups using Jira's picker endpoint |
| `list-issue-comments` ·common | `jira.listIssueComments()` | `--issue-id-or-key` | 4 | Retrieves paginated comments from a Jira issue with optional ordering |
| `list-project-types` | `jira.listProjectTypes()` | — | 0 | Retrieves all Jira project types available in the instance |
| `list-sprints` ·common | `jira.listSprints()` | `--board-id` | 3 | Retrieves paginated sprints from a Jira board with optional state filtering |
| `move-issue-to-sprint` ·common | `jira.moveIssueToSprint()` | `--issues` `--sprint-id` | 3 | Moves one or more Jira issues to a specified active sprint |
| `parse-jql-queries` | `jira.parseJqlQueries()` | `--queries` | 1 | Parse and validate JQL queries, returning their abstract syntax tree structure along with any errors or warnings |
| `remove-user-from-group` ·common | `jira.removeUserFromGroup()` | `--account-id` | 2 | Removes a user from a Jira group |
| `remove-user-from-project-role` ·common | `jira.removeUserFromProjectRole()` | `--project-id-or-key` `--role-id` | 2 | Removes a user or group from a project role |
| `remove-watcher-from-issue` | `jira.removeWatcherFromIssue()` | `--account-id` `--issue-id-or-key` | 0 | Removes a user from an issue's watcher list by account ID |
| `search-approximate-count` | `jira.searchApproximateCount()` | `--jql` | 0 | Count issues matching a JQL query using approximate count endpoint |
| `search-dashboards` ·common | `jira.searchDashboards()` | — | 11 | Search for Jira dashboards with filtering, sorting, and pagination support |
| `search-for-issues-using-jql-get` ·common | `jira.searchForIssuesUsingJqlGet()` | — | 9 | Searches for Jira issues using JQL with pagination and field selection |
| `search-for-issues-using-jql-post` ·common ·deprecated | `jira.searchForIssuesUsingJqlPost()` | — | 8 | Use search-issues instead |
| `search-issues` ·common | `jira.searchIssues()` | — | 17 | Advanced Jira issue search supporting structured filters and raw JQL |
| `send-notification-for-issue` | `jira.sendNotificationForIssue()` | `--issue-id-or-key` `--subject` `--text-body` `--to` | 2 | Sends a customized email notification for a Jira issue |

## Triggers

`jira.on("<event>", handler)` in a script; required config goes before the handler as an object.

| Event | Name | Required config | Description |
|---|---|---|---|
| `"new-issue"` | New Issue | `project_key` | Fires when a new issue is created in the Jira project you configure |
| `"new-project"` | New Project | — | Triggered when a new project is added in Jira |
| `"updated-issue"` | Updated Issue | `project_key` | Fires when an existing issue is changed in the Jira project you configure, for example its status, assignee, or any other field on the issu |

## Docs

- [run CLI](https://docs.boxd.sh/cli/run): Call connected integrations from the shell, connect new ones, and run automations.
- [Quickstart](https://docs.boxd.sh/guides/integrations/quickstart): Connect an integration, call it from the shell, and turn a script into an automation.
- [Connections](https://docs.boxd.sh/guides/integrations/connections): Connect an account once, for yourself or for your whole organization.
- [Scripts](https://docs.boxd.sh/guides/automations/scripts): Typed integrations, triggers, schedules and state in a .run.ts file.
- [Jobs](https://docs.boxd.sh/guides/automations/jobs): How a script becomes a background job: states, retries, sleep and wake.
- [Beyond the catalog](https://docs.boxd.sh/guides/automations/beyond-the-catalog): Reach your own APIs, databases and cloud accounts from a script.