pi-linear

---

Linear integration for pi with 55+ tools covering issues, projects, documents, initiatives, comments, relations, and more. Includes multi-workspace auth and a per-tool settings overlay.

Prerequisites

You need a Linear API key. To create one:

1. Go to Linear Settings > Account > Security & Access > API
2. Click Create key and give it a name (e.g. "pi")
3. Under Permissions, select Only select permissions with Read and Write enabled. Leave Admin unchecked.
4. Under Team access, choose All teams you have access to or scope to specific teams if you prefer
5. Click Create and copy the key

Install

pi install npm:@alasano/pi-linear

Authentication

The extension auto-detects the LINEAR_API_KEY environment variable if set globally. No setup needed in that case.

For multi-workspace support or if you don't have the env var, use the /linear-auth command:

Command	Description
/linear-auth add <name>	Add a workspace with an API key (prompts for key)
/linear-auth remove <name>	Remove a workspace (shows selector if name omitted)
/linear-auth switch <name>	Switch active workspace (shows selector if name omitted)
/linear-auth status	Show current auth source and configured workspaces
/linear-auth	Same as status

When you add your first workspace, it becomes active automatically. Adding a second workspace prompts you to switch. After a /reload with two or more workspaces configured, the agent gets a linear_switch_workspace tool and can switch between them when asked.

Auth resolution order:

1. Active stored workspace (if any workspaces are configured)
2. LINEAR_API_KEY environment variable (fallback when no workspaces configured)
3. Interactive prompt (asks you to set up a key)

Credentials are stored at ~/.pi/agent/state/extensions/linear/credentials.json.

Tool settings

Run /linear-settings to open an overlay where you can choose the default output view and enable or disable tools by category or individually. Linear results default to a human-readable view, with full JSON available via Ctrl+O; you can flip the default to full JSON if you prefer. Disabled tools are removed from the LLM's context entirely. Preferences persist across sessions.

Tools (55)

Issues

Tool	Description
linear_list_issues	List issues with filters, pagination, and sort
linear_get_issue	Get full issue details by identifier (ENG-123) or id
linear_create_issue	Create an issue with full IssueCreateInput support
linear_update_issue	Update an issue with full IssueUpdateInput support
linear_delete_issue	Delete an issue (admins can permanently delete)
linear_archive_issue	Archive or trash an issue
linear_unarchive_issue	Restore an archived issue
linear_search_issues	Search issues by text, with optional comment search and team boost

Issue Labels

Tool	Description
linear_list_issue_labels	List issue labels with team filter
linear_create_issue_label	Create an issue label
linear_update_issue_label	Update an issue label
linear_delete_issue_label	Delete an issue label

Issue Statuses

Tool	Description
linear_list_issue_statuses	List workflow states (issue statuses)

Issue Relations

Tool	Description
linear_list_issue_relations	List issue relations
linear_create_issue_relation	Create a relation (blocks, duplicate, related, similar)
linear_update_issue_relation	Update a relation
linear_delete_issue_relation	Delete a relation

Projects

Tool	Description
linear_list_projects	List projects with filters, pagination, and sort
linear_get_project	Get full project details by id
linear_save_project	Create or update a project
linear_delete_project	Delete a project
linear_archive_project	Archive or trash a project
linear_unarchive_project	Restore an archived project

Project Labels

Tool	Description
linear_list_project_labels	List project labels
linear_create_project_label	Create a project label
linear_update_project_label	Update a project label
linear_delete_project_label	Delete a project label

Project Relations

Tool	Description
linear_list_project_relations	List project relations
linear_create_project_relation	Create a project relation
linear_update_project_relation	Update a project relation
linear_delete_project_relation	Delete a project relation

Documents

Tool	Description
linear_list_documents	List documents with filters and pagination
linear_get_document	Get full document details by id
linear_create_document	Create a document
linear_update_document	Update a document
linear_delete_document	Delete a document
linear_unarchive_document	Restore an archived document

Comments

Tool	Description
linear_list_comments	List comments with filters and pagination
linear_create_comment	Create a comment on an issue, project update, etc.
linear_update_comment	Update a comment
linear_delete_comment	Delete a comment

Initiatives

Tool	Description
linear_list_initiatives	List initiatives with filters, pagination, and sort
linear_get_initiative	Get full initiative details by id
linear_save_initiative	Create or update an initiative
linear_delete_initiative	Delete an initiative
linear_archive_initiative	Archive an initiative
linear_unarchive_initiative	Restore an archived initiative

Milestones

Tool	Description
linear_list_milestones	List project milestones
linear_get_milestone	Get milestone details by id
linear_save_milestone	Create or update a milestone
linear_delete_milestone	Delete a milestone

Teams

Tool	Description
linear_list_teams	List teams with workflow states
linear_get_team	Get team details by id

Users

Tool	Description
linear_list_users	List users
linear_get_user	Get user details by id

Workspaces

Tool	Description
linear_switch_workspace	Switch active workspace (only available with 2+ workspaces)

Requirements

• Pi interactive mode (settings overlay uses the widget API)