Pi extension for interacting with Linear via the Linear SDK.
pi install @aliou/pi-linear
The extension requires a Linear API key. Get one at https://linear.app/settings/api.
Run /linear:auth in pi to add/edit/remove workspace credentials.
Run /linear:settings to manage workspaces and extension toggles.
export LINEAR_API_KEY=lin_api_...If no key is found, the extension disables its tools and shows a warning at session start.
| Command | Description |
|---|---|
/linear:auth |
Add, edit, or remove workspace credentials |
/linear:settings |
Configure workspaces and extension settings |
/linear:start [ISSUE_ID] |
Start implementation flow; opens issue picker when no id is provided |
/linear:browse |
Tabbed browser (Issues, Projects, Milestones) inspired by Linear navigation |
| Field | Type | Default | Description |
|---|---|---|---|
enabled |
boolean |
true |
Enable or disable the extension |
defaultWorkspace |
string |
auto | Preferred workspace key |
startUpdateState |
"ask"|"true"|"false" |
"ask" |
Default behavior for issue-start state transition |
startCreateBranch |
"ask"|"true"|"false" |
"ask" |
Default behavior for issue-start branch creation |
workspaces |
record |
{} |
Workspace profiles keyed by org urlKey |
workspaces.<key>.apiKey |
string |
— | Workspace API key |
workspaces.<key>.orgName |
string |
— | Workspace display label |
workspaces.<key>.defaultTeamKey |
string |
— | Default team key used when team args are omitted |
apiKey |
string |
legacy | Legacy flat key; auto-migrated into workspaces.default |
Manage Linear issues and issue-scoped resources.
| Action | Description |
|---|---|
list |
List issues, with optional filters like team, project, state, assignee, and label |
search |
Full-text search across issues |
show |
Show a single issue by ID or identifier (for example ENG-123), including sub-issues |
create |
Create a new issue in a team |
update |
Update an existing issue, including project milestone assignment |
comments_list |
List comments for an issue |
comment_create |
Create a comment on an issue |
comment_update |
Update a comment |
comment_delete |
Delete a comment |
attachments_list |
List issue attachments |
attachment_create |
Attach a URL to an issue |
relations_list |
List issue relations, with optional inverse relations |
relation_create |
Create an issue relation like blocks, blocked_by, duplicate, related, or similar |
relation_update |
Update an issue relation |
relation_delete |
Delete an issue relation |
documents_list |
List documents linked to an issue |
Common issue fields include:
teamId,teamKeyprojectIdprojectMilestoneIdstateId(resolve vialinear_team_states)assigneeId(resolve vialinear_people)labelId,labelIdspriority,dueDate,estimate,parentId
Start implementation from a Linear issue.
- Input:
id(required), optionalupdateState,createBranch,allowDirty - Behavior:
- can update issue status to
In Progress(orStartedfallback) - can create a local branch from Linear suggested
branchName(fallback generated from issue id/title) - if git tree is dirty, stops and asks for explicit confirmation (
allowDirty: true) - if current branch is not default branch, warns but still creates the branch
- can update issue status to
Manage Linear projects and project relations.
| Action | Description |
|---|---|
list |
List projects, with optional filters like team, status, and lead |
show |
Show a single project by ID |
create |
Create a new project |
update |
Update an existing project |
relations_list |
List relations for a project |
relation_create |
Create a project relation |
relation_update |
Update a project relation |
relation_delete |
Delete a project relation |
Manage project milestones.
| Action | Description |
|---|---|
list |
List milestones for a project. Requires projectId |
show |
Show a milestone by milestoneId |
create |
Create a milestone in a project. Requires projectId |
update |
Update a milestone by milestoneId |
delete |
Delete a milestone by milestoneId |
Milestone fields include:
projectIdmilestoneIdnamedescriptiontargetDatesortOrder
Manage Linear documents.
| Action | Description |
|---|---|
list |
List documents in the workspace, optionally scoped by issueId or projectId |
show |
Show a document by ID |
create |
Create a document, optionally linked to an issue or project |
update |
Update a document |
delete |
Delete a document |
| Action | Description |
|---|---|
list |
List active teams in the workspace |
List workspace members for assignment.
| Action | Description |
|---|---|
list |
List active people in the workspace with IDs usable as assigneeId |
List workflow states for teams.
| Action | Description |
|---|---|
list |
List team states, optionally filtered by teamId or teamKey; use returned IDs as stateId |
- Use issue identifiers like
ENG-123when you have them. - Prefer scoped list and search requests to keep results small and precise.
- For issue milestone assignment, use
projectMilestoneId. - URL attachments are supported directly. Local file upload is not exposed as a first-class helper yet.
