# Linear on boxd

> Linear is a streamlined issue tracking and project planning tool for modern teams, featuring fast workflows, keyboard shortcuts, and GitHub integrations.

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

## From the shell

```sh
run auth linear      # once: prints a link to connect your account
run linear           # list its commands
run linear 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 { linear } from "@boxd/run";

const result = await linear.getCurrentUser();
console.log(result);

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

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

## Commands

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

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `archive-issue` | `linear.archiveIssue()` | `--issue-id` | 0 | Archives an existing Linear issue by its ID, removing it from active views while preserving its data for future reference |
| `archive-project` | `linear.archiveProject()` | `--project-id` | 0 | Archives an existing Linear project by its UUID, removing it from active views |
| `archive-project-update` | `linear.archiveProjectUpdate()` | `--project-update-id` | 0 | Archives a project update in Linear, hiding it from the default view while preserving its data |
| `create-attachment` | `linear.createAttachment()` | `--issue-id` `--title` `--url` | 1 | Creates a new attachment and associates it with a specific, existing Linear issue |
| `create-comment` | `linear.createComment()` | `--body` `--issueId` | 0 | Creates a new comment on a specified Linear issue |
| `create-comment-reaction` | `linear.createCommentReaction()` | `--comment-id` `--emoji` | 0 | Add a reaction to an existing Linear comment |
| `create-issue` | `linear.createIssue()` | `--team-id` `--title` | 10 | Creates a new issue in a specified Linear project and team, requiring team_id and title, and allowing optional properties like description, assignee, state, priority, cycle, and due date |
| `create-issue-relation` | `linear.createIssueRelation()` | `--issue-id` `--related-issue-id` `--relation-type` | 0 | Create a relationship between two Linear issues using the issueRelationCreate mutation |
| `create-label` | `linear.createLabel()` | `--color` `--name` `--team-id` | 1 | Creates a new label in Linear for a specified team, used to categorize and organize issues |
| `create-project` ·common | `linear.createProject()` | `--name` `--team-ids` | 7 | Creates a new Linear project with specified name and team associations |
| `create-project-milestone` ·common | `linear.createProjectMilestone()` | `--name` `--project-id` | 3 | Create a project milestone in Linear with a name and optional target date and sort order |
| `create-project-update` ·common | `linear.createProjectUpdate()` | `--body` `--project-id` | 2 | Create a project status update post for a Linear project |
| `create-team` ·common | `linear.createTeam()` | `--key` `--name` | 4 | Creates a new team in Linear with the specified name and key |
| `delete-issue` | `linear.deleteIssue()` | `--issue-id` | 0 | Archives an existing Linear issue by its ID, which is Linear's standard way of deleting issues; the operation is idempotent |
| `get-all-teams` ·deprecated | `linear.getAllTeams()` | — | 2 | Use ListLinearTeams instead (returns paginated payloads with members and projects); this tool returns simpler id/name-level data for all teams visible to the connected workspace with no server-side… |
| `get-attachment` | `linear.getAttachment()` | `--attachment-id` `--file-name` `--issue-id` | 0 | Downloads a specific attachment from a Linear issue; the `file_name` must include the correct file extension |
| `get-comment` | `linear.getComment()` | `--id` | 0 | Retrieves a single Linear comment by its unique ID |
| `get-current-user` ·common | `linear.getCurrentUser()` | — | 0 | Gets the currently authenticated user's ID, name, email, and other profile information, this is the account behind the API token, which may be a bot or service account rather than a human user |
| `get-cycles-by-team-id` | `linear.getCyclesByTeamId()` | `--team-id` | 2 | Retrieves all cycles for a specified Linear team ID; cycles are time-boxed work periods (like sprints) |
| `get-issue` | `linear.getIssue()` | `--issue-id` | 0 | Retrieves an existing Linear issue's comprehensive details, including id, identifier, title, description, timestamps, state, team, creator, attachments, comments (with user info and timestamps, use… |
| `get-issue-defaults` | `linear.getIssueDefaults()` | `--team-id` | 0 | Fetches a Linear team's default issue estimate and state, useful for pre-filling new issue forms |
| `get-project` | `linear.getProject()` | `--project-id` | 3 | Retrieves a single Linear project by its unique identifier |
| `get-project-update` | `linear.getProjectUpdate()` | `--id` | 0 | Retrieves a specific project update by its unique identifier |
| `list-comments` ·common | `linear.listComments()` | — | 4 | Lists comments from Linear workspace accessible to the authenticated user |
| `list-cycles` | `linear.listCycles()` | — | 2 | Retrieves all cycles (time-boxed sprint iterations) org-wide from the Linear account; no filters applied |
| `list-issue-drafts` | `linear.listIssueDrafts()` | — | 2 | List issue drafts |
| `list-issues` | `linear.listIssues()` | — | 7 | Lists non-archived Linear issues; if project_id is not specified, issues from all accessible projects are returned |
| `list-issues-by-team-id` | `linear.listIssuesByTeamId()` | `--team-id` | 3 | List all issues for a specific Linear team, scoped by team ID |
| `list-labels` | `linear.listLabels()` | — | 3 | Retrieves labels from Linear |
| `list-project-updates` ·common | `linear.listProjectUpdates()` | — | 2 | Retrieves all project updates from the Linear workspace |
| `list-projects` | `linear.listProjects()` | — | 2 | Retrieves all projects from the Linear account |
| `list-states` | `linear.listStates()` | `--team-id` | 2 | Retrieves all workflow states for a specified team in Linear, representing the stages an issue progresses through in that team's workflow |
| `list-teams` | `linear.listTeams()` | — | 3 | Retrieves all teams with their members and projects |
| `list-users` | `linear.listUsers()` | — | 2 | Lists all workspace users (not team-scoped) with their IDs, names, emails, and active status |
| `remove-issue-label` ·common | `linear.removeIssueLabel()` | `--issue-id` `--label-id` | 0 | Removes a specified label from an existing Linear issue using their IDs; successful even if the label isn't on the issue |
| `remove-reaction` ·common | `linear.removeReaction()` | `--reaction-id` | 0 | Remove a reaction on a comment |
| `resolve-comment` | `linear.resolveComment()` | `--id` | 0 | Marks a Linear comment as resolved |
| `run-query-or-mutation` ·common | `linear.runQueryOrMutation()` | `--query-or-mutation` | 1 | Execute any GraphQL query or mutation against Linear's API |
| `search-issues` ·common | `linear.searchIssues()` | `--query` | 3 | Search Linear issues using full-text search across identifier, title, and description |
| `unarchive-project-update` | `linear.unarchiveProjectUpdate()` | `--id` | 0 | Unarchive a previously archived project update in Linear |
| `unresolve-comment` | `linear.unresolveComment()` | `--comment-id` | 0 | Unresolves a previously resolved Linear comment, marking it as requiring attention again |
| `update-comment` | `linear.updateComment()` | `--body` `--comment-id` | 0 | Update an existing Linear comment's body text |
| `update-issue` ·common | `linear.updateIssue()` | `--issueId` | 12 | Updates an existing Linear issue using its `issue_id`; requires at least one other attribute for modification, and all provided entity IDs (for state, assignee, labels, etc.) must be valid UUIDs… |
| `update-project` ·common | `linear.updateProject()` | `--project-id` | 10 | Update an existing Linear project |
| `update-project-update` ·common | `linear.updateProjectUpdate()` | `--id` | 3 | Update an existing Linear project update post |
| `update-team` ·common | `linear.updateTeam()` | `--team-id` | 22 | Updates an existing Linear team's settings and configuration |
| `validate-credential` | `linear.validateCredential()` | — | 0 | Validates the Linear API credentials by checking if the authentication token can successfully query the current user |

## Triggers

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

| Event | Name | Required config | Description |
|---|---|---|---|
| `"comment-event"` | Comment Received Trigger | `team_id` | Triggered when a comment is received |
| `"issue-created"` | Issue Created Trigger | `team_id` | Triggered when a new issue is created |
| `"issue-updated"` | Issue Updated Trigger | `team_id` | Triggered when an issue is updated |
| `"private-team-comment-created"` | Private Team Comment Created | `team_id` | Fires when a new comment is posted on an issue in a private Linear team (polled with the connected user's token) |
| `"private-team-issue-created"` | Private Team Issue Created | `team_id` | Fires when a new issue appears in a private Linear team (polled with the connected user's token) |
| `"private-team-issue-properties-updated"` | Private Team Issue Properties Updated | `team_id` | Fires when properties on an issue change in a private Linear team (polled with the connected user's token) |
| `"project-created"` | Project Created | — | Fires when a new Linear project is created |
| `"project-properties-updated"` | Project Properties Updated | — | Fires when properties on a Linear project change (status, lead, target date, priority, etc.) |
| `"project-update-posted"` | Project Update Posted | — | Fires when a project status update is posted on the Linear project's Updates tab |
| `"public-team-comment-created"` | Public Team Comment Created | — | Fires when a new comment is posted on a *public-team* Linear issue |
| `"public-team-issue-created"` | Public Team Issue Created | — | Fires when a new issue is created in a Linear *public* team |
| `"public-team-issue-properties-updated"` | Public Team Issue Properties Updated | — | Fires when properties on a *public-team* Linear issue change (status, assignee, priority, labels, etc.) |

## 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.