Skip to content
Back to search

linctl

Use linctl to read and update Linear issues, projects, teams, users, labels, comments, and agent sessions from the terminal. Prefer JSON reads, validate auth first, and use command-specific --help for exact flags.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dorkitude--linctl/badge.svg)](/listings/dorkitude--linctl)

HTML

<a href="/listings/dorkitude--linctl"><img src="/api/listings/dorkitude--linctl/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Homebrew (macOS/Linux)

brew tap dorkitude/linctl
brew install linctl
linctl docs      # Render the README.md

Nix

nix profile install github:dorkitude/linctl
linctl docs      # Render the README.md

From Source

git clone https://github.com/dorkitude/linctl.git
cd linctl
make deps        # Install dependencies
make build       # Build the binary
make install     # Install to /usr/local/bin (requires sudo)
linctl docs      # Render the README.md

For Development

git clone https://github.com/dorkitude/linctl.git
cd linctl
make deps        # Install dependencies
go run main.go   # Run directly without building
make dev         # Or build and run in development mode
make test        # Run smoke tests
make lint        # Run linter
make fmt         # Format code
linctl docs      # Render the README.md

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 156 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: linctl
  3. description: Use linctl to read and update Linear issues, projects, teams, users, labels, comments, and agent sessions from the terminal. Prefer JSON reads, validate auth first, and use command-specific --help for exact flags.
  4. ---
  5. # linctl Agent Guide
  6. Use this skill when the user wants to inspect or modify Linear data through `linctl`.
  7. ## Quick Rules
  8. - Always verify auth before substantive work: `linctl auth status` or `linctl whoami`.
  9. - For read operations, prefer `--json` and parse results with `jq` when needed.
  10. - Before writing, inspect current state first (`get` / `list --json`).
  11. - Use command-specific help for exact flags and validation rules: `linctl <command> <subcommand> --help`.
  12. - Be explicit with filters; defaults can hide expected results.
  13. - Linear URLs work as entity references. Quote URLs containing `#`. Also GitHub pull
  14. request URLs, but only if it's attached to a Linear issue.
  15. ## High-Impact Gotchas
  16. - `issue list`, `issue search`, and `project list` default to `--newer-than 6_months_ago`.
  17. - `issue list` and `issue search` exclude completed/canceled by default.
  18. - `issue search` may also need `--include-archived` for archived matches.
  19. - `issue list --cycle current` can validly return no rows if no active cycle exists.
  20. - Parent/sub-issue links are set via `issue update --parent` (not `issue create`).
  21. - If results look incomplete, retry with:
  22. - `--newer-than all_time`
  23. - `--include-completed`
  24. - `--include-archived` (search)
  25. ## Auth + Credential Behavior
  26. - Interactive login: `linctl auth` (or `linctl auth login`).
  27. - Credentials are stored in `~/.linctl-auth.json`.
  28. - `LINCTL_API_KEY` overrides stored credentials.
  29. - Precedence: `LINCTL_API_KEY` > `~/.linctl-auth.json`.
  30. ## Core Workflow
  31. 1. Confirm identity and access.
  32. 2. Discover relevant entities (team key, issue ID, project ID, user email) via `list/search` with `--json`.
  33. 3. Read exact target with `get`.
  34. 4. Apply changes with `create/update/assign/comment/label/agent` commands.
  35. 5. Re-read target and summarize concrete outcome to the user.
  36. ## Command Map
  37. - Issues: `linctl issue ...`
  38. - Projects: `linctl project ...`
  39. - Teams: `linctl team ...` (includes `state list` and `state update`)
  40. - Users: `linctl user ...` and `linctl whoami`
  41. - Comments: `linctl comment ...`
  42. - Labels: `linctl label ...`
  43. - Agent Sessions: `linctl agent ...`
  44. - Auth: `linctl auth ...`
  45. - Dynamic MCP: `linctl mcp ...` (`sync`, `tools`, `call`)
  46. ## Suggested Read Patterns
  47. ```bash
  48. # Issues assigned to me, no date-limit surprise
  49. linctl issue list --assignee me --newer-than all_time --include-completed --json
  50. # Issues in current cycle (if cycle exists)
  51. linctl issue list --cycle current --limit 20 --json
  52. # Find issue by text, including archived/completed
  53. linctl issue search "<query>" --newer-than all_time --include-completed --include-archived --json
  54. # Project inventory without default date filter
  55. linctl project list --newer-than all_time --json
  56. # Create or update a project with the exact workspace-defined status.
  57. linctl project create --name "Custom Properties" --team END --lead me --status "Shaping"
  58. linctl project update <project-id> --status "Shaping"
  59. # Team labels for resolution/validation
  60. linctl label list --team <TEAM_KEY> --json
  61. # Team workflow states
  62. linctl team state list <TEAM_KEY> --json
  63. # Agent session status for an issue
  64. linctl agent <ISSUE_ID> --json
  65. # Dynamic schema-backed tool list and call
  66. linctl mcp sync
  67. linctl mcp tools --json
  68. linctl mcp call query.viewer
  69. ```
  70. ## Suggested Write Patterns
  71. ```bash
  72. # Update an issue after inspecting it
  73. linctl issue get LIN-123 --json
  74. linctl issue update LIN-123 --state "In Progress" --assignee me
  75. linctl issue get LIN-123 --json
  76. # Delegate issue to an agent/user
  77. linctl issue update LIN-123 --delegate "<displayName|email|name>"
  78. # Set labels by name/ID, or clear
  79. linctl issue update LIN-123 --labels bug,urgent
  80. linctl issue update LIN-123 --clear-labels
  81. # Attach PR or URL
  82. linctl issue attach LIN-123 --pr https://github.com/org/repo/pull/123
  83. linctl issue attach LIN-123 --url https://example.com/spec --title "Spec"
  84. # List/download issue attachment files and uploads links
  85. linctl issue attachment list LIN-123 --json
  86. linctl issue attachment download LIN-123 --all --output-dir ./downloads
  87. linctl issue get LIN-123 --download-attachments --output-dir ./downloads --json
  88. # Add execution note
  89. linctl comment create LIN-123 --body "Implemented and verified locally."
  90. # Comment lifecycle by comment ID
  91. linctl comment get <COMMENT_ID>
  92. linctl comment update <COMMENT_ID> --body "Updated note"
  93. linctl comment delete <COMMENT_ID>
  94. # Update a workflow state
  95. linctl team state update <STATE_ID> --name "Ready"
  96. # Mention delegated/active agent with message
  97. linctl agent mention LIN-123 "Please pick this up."
  98. ```
  99. ## Troubleshooting
  100. - `Not authenticated`: run `linctl auth` then `linctl auth status`.
  101. - Empty or partial lists: remove default filters (`--newer-than all_time`, `--include-completed`).
  102. - `unknown command` / `unknown flag`: binary is old; verify `linctl --version` and reinstall/upgrade.
  103. - Validation errors on flags: run the exact subcommand help and retry:
  104. - `linctl issue update --help`
  105. - `linctl project create --help`
  106. - `linctl comment update --help`
  107. - `linctl label create --help`
  108. - `linctl agent mention --help`
  109. ## Minimal Discovery Commands
  110. ```bash
  111. linctl --help
  112. linctl issue --help
  113. linctl project --help
  114. linctl team --help
  115. linctl user --help
  116. linctl comment --help
  117. linctl label --help
  118. linctl agent --help
  119. linctl auth --help
  120. ```
README.md · README · 1,117 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # linctl
  2. A command-line interface for the Linear API, built with Go and Cobra.
  3. ## Features
  4. - **Authentication**: personal API key auth (`linctl auth`), env-var override, and optional [`pass`](https://www.passwordstore.org/) credential storage.
  5. - **Issues**: list/search/get/create/update/assign with support for:
  6. - cycles, labels, delegation, projects/milestones, parent/sub-issue links
  7. - due dates, attachments, comments, and rich issue detail output
  8. - issue relations (blocks, blocked-by, related, duplicate, similar)
  9. - **Projects**: list/get/create/update/delete/archive.
  10. - **Teams**: list/get/members/state (list/update).
  11. - **Users**: list/get/me.
  12. - **Labels**: list/get/create/update/delete.
  13. - **Comments**: list/get/create/update/delete.
  14. - **Agent Sessions**: inspect issue agent session state and mention delegated/active agents.
  15. - **Raw GraphQL**: execute arbitrary Linear GraphQL using your `linctl` auth context.
  16. - **Dynamic MCP namespace**: discover and call schema-backed operations via `linctl mcp`.
  17. - **Output modes**: table, plaintext, and JSON.
  18. - **Sorting and time filters**: reusable list/search filtering patterns.
  19. - **Built-in docs**: `linctl docs`.
  20. - **Read-only smoke testing** support.
  21. ## Installation
  22. ### Homebrew (macOS/Linux)
  23. ```bash
  24. brew tap dorkitude/linctl
  25. brew install linctl
  26. linctl docs # Render the README.md
  27. ```
  28. ### Nix
  29. ```bash
  30. nix profile install github:dorkitude/linctl
  31. linctl docs # Render the README.md
  32. ```
  33. ### From Source
  34. ```bash
  35. git clone https://github.com/dorkitude/linctl.git
  36. cd linctl
  37. make deps # Install dependencies
  38. make build # Build the binary
  39. make install # Install to /usr/local/bin (requires sudo)
  40. linctl docs # Render the README.md
  41. ```
  42. ### For Development
  43. ```bash
  44. git clone https://github.com/dorkitude/linctl.git
  45. cd linctl
  46. make deps # Install dependencies
  47. go run main.go # Run directly without building
  48. make dev # Or build and run in development mode
  49. make test # Run smoke tests
  50. make lint # Run linter
  51. make fmt # Format code
  52. linctl docs # Render the README.md
  53. ```
  54. ## Important: Default Filters
  55. **By default, `issue list`, `issue search`, and `project list` commands only show items created in the last 6 months!**
  56. This improves performance and prevents overwhelming data loads. To see older items:
  57. - Use `--newer-than 1_year_ago` for items from the last year
  58. - Use `--newer-than all_time` to see ALL items ever created
  59. - See the [Time-based Filtering](#-time-based-filtering) section for details
  60. **By default, `issue list` and `issue search` also filter out canceled and completed items. To see all items, use the `--include-completed` flag.**
  61. - Need archived matches? Add `--include-archived` when using `issue search`.
  62. ## Pasting URLs
  63. Paste Linear URLs anywhere `linctl` takes an issue, project, team or comment.
  64. ```bash
  65. linctl issue get https://linear.app/acme/issue/ENG-123/fix-the-thing
  66. linctl comment get 'https://linear.app/acme/issue/ENG-123/fix-the-thing#comment-b68a4bf5'
  67. linctl project get https://linear.app/acme/project/roadmap-d05c5c7e8a5c/overview
  68. linctl issue list --team https://linear.app/acme/team/ENG/active
  69. linctl issue get https://github.com/acme/api/pull/6153
  70. ```
  71. Quote URLs containing `#`. GitHub PR URLs will work as well, but only if one is
  72. attached to an existing Linear issue.
  73. ## Quick Start
  74. > **IMPORTANT** Agents like Claude Code, Cursor, and Gemini should use the `--json` flag on all read operations.
  75. ### 1. Authentication
  76. ```bash
  77. # Interactive authentication
  78. linctl auth
  79. # Check authentication status
  80. linctl auth status
  81. # Show current user
  82. linctl whoami
  83. # View full documentation
  84. linctl docs | less
  85. ```
  86. ### 2. Issue Management
  87. ```bash
  88. # List all issues
  89. linctl issue list
  90. # List issues assigned to you
  91. linctl issue list --assignee me
  92. # List issues in a specific state
  93. linctl issue list --state "In Progress"
  94. # List issues sorted by update date
  95. linctl issue list --sort updated
  96. # Filter issues by cycle
  97. linctl issue list --cycle current
  98. linctl issue list --cycle 42
  99. # Search issues using Linear's full-text index (shares the same filters as list)
  100. linctl issue search "login bug" --team ENG
  101. linctl issue search "customer:" --include-completed --include-archived
  102. # List recent issues (last 2 weeks instead of default 6 months)
  103. linctl issue list --newer-than 2_weeks_ago
  104. # List ALL issues ever created (override 6-month default)
  105. linctl issue list --newer-than all_time
  106. # List today's issues
  107. linctl issue list --newer-than 1_day_ago
  108. # Get issue details (now includes git branch, cycle, project, attachments, and comments)
  109. linctl issue get LIN-123
  110. linctl issue get LIN-123 --download-attachments --output-dir ./downloads
  111. # Create a new issue
  112. linctl issue create --title "Bug fix" --team ENG
  113. linctl issue create --title "Bug fix" --team ENG --project "Q1 Platform"
  114. linctl issue create --title "Bug fix" --team ENG --project "Q1 Platform" --project-milestone "Phase 1"
  115. linctl issue create --title "Bug fix" --team ENG --state "In Progress"
  116. linctl issue create --title "Bug fix" --team ENG --estimate 3
  117. linctl issue create --title "Bug fix" --team ENG --labels bug,urgent
  118. linctl issue create --title "Bug fix" --team ENG --delegate agent-runner
  119. # Assign issue to yourself
  120. linctl issue assign LIN-123
  121. # Update issue fields
  122. linctl issue update LIN-123 --title "New title"
  123. linctl issue update LIN-123 --description "Updated description"
  124. linctl issue update LIN-123 --assignee john.doe@company.com
  125. linctl issue update LIN-123 --assignee me # Assign to yourself
  126. linctl issue update LIN-123 --assignee unassigned # Remove assignee
  127. linctl issue update LIN-123 --state "In Progress"
  128. linctl issue update LIN-123 --priority 1 # 0=None, 1=Urgent, 2=High, 3=Normal, 4=Low
  129. linctl issue update LIN-123 --estimate 5 # Value depends on team estimation system
  130. linctl issue update LIN-123 --due-date "2024-12-31"
  131. linctl issue update LIN-123 --due-date "" # Remove due date
  132. linctl issue update LIN-123 --project "Q1 Platform"
  133. linctl issue update LIN-123 --project "none" # Remove project assignment
  134. linctl issue update LIN-123 --project "Q1 Platform" --project-milestone "Phase 1"
  135. linctl issue update LIN-123 --project-milestone "none" # Remove project milestone
  136. linctl issue update LIN-123 --labels bug,urgent
  137. linctl issue update LIN-123 --clear-labels
  138. linctl issue update LIN-123 --delegate agent-runner
  139. linctl issue update LIN-123 --delegate none # Remove delegate
  140. linctl issue update LIN-123 --parent LIN-100
  141. linctl issue update LIN-123 --parent none # Remove parent
  142. # Set up parent-child issue relationships
  143. linctl issue update LIN-124 --parent LIN-123 # Make LIN-124 a sub-issue of LIN-123
  144. linctl issue update LIN-125 --parent LIN-123 # Make LIN-125 also a sub-issue
  145. # Remove parent-child relationships
  146. linctl issue update LIN-124 --parent none
  147. # Update multiple fields at once
  148. linctl issue update LIN-123 --title "Critical Bug" --assignee me --priority 1 --project "Q1 Platform"
  149. # Attach a GitHub PR or external URL
  150. linctl issue attach LIN-123 --pr https://github.com/owner/repo/pull/456
  151. linctl issue attach LIN-123 --pr 456 # Resolves repo from git remote origin
  152. linctl issue attach LIN-123 --url https://example.com/spec --title "Spec"
  153. # List/download attachments and uploads.linear.app links
  154. linctl issue attachment list LIN-123
  155. linctl issue attachment download LIN-123 --all --output-dir ./downloads
  156. linctl issue attachment download LIN-123 --id ATTACHMENT-ID
  157. linctl issue attachment download LIN-123 --name spec.md --output ./spec.md
  158. # Manage issue relations (blocks, blocked-by, related, duplicate, similar)
  159. linctl issue relation list LIN-123
  160. linctl issue relation ls LIN-123 -j # JSON output
  161. linctl issue relation add LIN-123 --blocks LIN-456
  162. linctl issue relation add LIN-123 --blocked-by LIN-456
  163. linctl issue relation add LIN-123 --related LIN-456
  164. linctl issue relation add LIN-123 --duplicate LIN-456
  165. linctl issue relation add LIN-123 --similar LIN-456
  166. linctl issue relation remove RELATION-ID # Use ID from relation list
  167. ```
  168. ### 3. Project Management
  169. ```bash
  170. # List all projects (shows IDs)
  171. linctl project list
  172. # Filter projects by state
  173. linctl project list --state started
  174. # List projects created in the last month (instead of default 6 months)
  175. linctl project list --newer-than 1_month_ago
  176. # List ALL projects regardless of age
  177. linctl project list --newer-than all_time
  178. # Get project details (use ID from list command)
  179. linctl project get 65a77a62-ec5e-491e-b1d9-84aebee01b33
  180. # Create a project
  181. linctl project create --name "Q1 Platform" --team ENG --status "In Progress"
  182. # Update a project
  183. linctl project update PROJECT-ID --lead me --target-date 2026-06-30
  184. # Archive or delete a project
  185. linctl project delete PROJECT-ID
  186. linctl project delete PROJECT-ID --permanent --force
  187. ```
  188. ### 4. Team Management
  189. ```bash
  190. # List all teams
  191. linctl team list
  192. # Get team details
  193. linctl team get ENG
  194. # List team members
  195. linctl team members ENG
  196. # List workflow states for a team
  197. linctl team state list ENG
  198. # Update a workflow state
  199. linctl team state update STATE-ID --name "Ready" --color "#abc"
  200. ```
  201. ### 5. User Management
  202. ```bash
  203. # List all users
  204. linctl user list
  205. # Show only active users
  206. linctl user list --active
  207. # Get user details by email
  208. linctl user get john@example.com
  209. # Show your own profile
  210. linctl user me
  211. ```
  212. ### 6. Comments
  213. ```bash
  214. # List comments on an issue
  215. linctl comment list LIN-123
  216. # Add a comment to an issue
  217. linctl comment create LIN-123 --body "Fixed the authentication bug"
  218. # Get, update, and delete comments by ID
  219. linctl comment get COMMENT-ID
  220. linctl comment update COMMENT-ID --body "Updated comment body"
  221. linctl comment delete COMMENT-ID
  222. ```
  223. ### 7. Label Management
  224. ```bash
  225. # List labels for a team
  226. linctl label list --team ENG
  227. # Get a label by ID
  228. linctl label get LABEL-ID
  229. # Create a label
  230. linctl label create --team ENG --name bug --color "#ff0000"
  231. linctl label create --team ENG --name "backend" --is-group
  232. # Update a label
  233. linctl label update LABEL-ID --name "critical bug"
  234. # Delete a label
  235. linctl label delete LABEL-ID
  236. ```
  237. ### 8. Agent Sessions
  238. ```bash
  239. # View delegated/agent session state for an issue
  240. linctl agent ENG-80
  241. # Mention the delegated/active agent with a message
  242. linctl agent mention ENG-80 "Please investigate this failure"
  243. # Override target handle explicitly
  244. linctl agent mention ENG-80 --agent agent-runner "Please rerun tests"
  245. ```
  246. ### 9. Raw GraphQL (API Escape Hatch)
  247. ```bash
  248. # Direct query
  249. linctl graphql 'query { viewer { id name email } }'
  250. # From a .graphql file
  251. linctl graphql --file query.graphql
  252. # With inline variables JSON
  253. linctl graphql --query 'query($k:String!){ team(id:$k){ id key name } }' --variables '{"k":"ENG"}'
  254. # With variables file
  255. linctl graphql --file query.graphql --variables-file vars.json
  256. # Pipe query from stdin
  257. cat query.graphql | linctl graphql --variables '{"k":"ENG"}'
  258. ```
  259. ### 10. Dynamic MCP Tools (Schema-Driven)
  260. ```bash
  261. # Sync cache from live schema introspection (12h TTL)
  262. linctl mcp sync
  263. # List cached dynamic tools
  264. linctl mcp tools
  265. # Call a tool (full name)
  266. linctl mcp call query.viewer
  267. # Call a mutation with JSON arguments
  268. linctl mcp call mutation.issueCreate --json '{"input":{"title":"Fix login","teamId":"team-id"}}'
  269. # Override selection set for object return types
  270. linctl mcp call query.issue --json '{"id":"LIN-123"}' --selection '{ id identifier title state { name } }'
  271. ```
  272. ## Command Reference
  273. ### Global Flags
  274. - `--plaintext, -p`: Plain text output (non-interactive)
  275. - `--json, -j`: JSON output for scripting
  276. - `--help, -h`: Show help
  277. - `--version, -v`: Show version
  278. ### Authentication Commands
  279. ```bash
  280. linctl auth # Interactive authentication
  281. linctl auth login # Same as above
  282. linctl auth status # Check authentication status
  283. linctl auth logout # Clear stored credentials
  284. linctl whoami # Show current user
  285. ```
  286. ### GraphQL Command
  287. ```bash
  288. # Execute raw GraphQL operation
  289. linctl graphql [query] [flags]
  290. # Flags:
  291. -q, --query string Query/mutation string
  292. -f, --file string Path to a .graphql file
  293. --variables string Variables as JSON object string
  294. --variables-file string Path to JSON object file with variables
  295. ```
  296. ### MCP Commands
  297. ```bash
  298. # Refresh cache of dynamic tools discovered from Linear schema
  299. linctl mcp sync
  300. # List cached tools (name, args, return type)
  301. linctl mcp tools
  302. # Call by full name (`query.*` or `mutation.*`)
  303. linctl mcp call <tool-name> [flags]
  304. # Flags:
  305. --json string JSON object of tool arguments
  306. --selection string Override selection set for object/interface/union return types
  307. ```
  308. ### Issue Commands
  309. ```bash
  310. # List issues with filters
  311. linctl issue list [flags]
  312. linctl issue ls [flags] # Short alias
  313. # Flags:
  314. -a, --assignee string Filter by assignee (email or 'me')
  315. -c, --include-completed Include completed and canceled issues
  316. -s, --state string Filter by state name
  317. -t, --team string Filter by team key
  318. -r, --priority int Filter by priority (0-4, default: -1)
  319. -y, --cycle string Filter by cycle ('current' or cycle number)
  320. -l, --limit int Maximum results (default 50)
  321. -o, --sort string Sort order: linear (default), created, updated
  322. -n, --newer-than string Show items created after this time (default: 6_months_ago, use 'all_time' for no filter)
  323. # Get issue details (shows parent and sub-issues)
  324. linctl issue get <issue-id>
  325. linctl issue show <issue-id> # Alias
  326. # Flags:
  327. --download-attachments Download issue attachments and uploads.linear.app links from description/comments
  328. --output-dir string Directory for downloaded attachments when using --download-attachments (default ".")
  329. # Create issue
  330. linctl issue create [flags]
  331. linctl issue new [flags] # Alias
  332. # Flags:
  333. --title string Issue title (required)
  334. -d, --description string Issue description
  335. -t, --team string Team key (required)
  336. --priority int Priority 0-4 (default 3)
  337. -e, --estimate int Estimate points (depends on team's estimation system)
  338. -m, --assign-me Assign to yourself
  339. -s, --state string State name (e.g., 'Todo', 'In Progress')
  340. --delegate string Delegate to user/agent (email, name, or displayName)
  341. --labels strings Labels to assign (names or IDs, comma-separated)
  342. --project string Project name or ID to assign the issue to
  343. --project-milestone string Project milestone name or ID (requires --project)
  344. # Assign issue to yourself
  345. linctl issue assign <issue-id>
  346. # Update issue
  347. linctl issue update <issue-id> [flags]
  348. linctl issue edit <issue-id> [flags] # Alias
  349. # Flags:
  350. --title string New title
  351. -d, --description string New description
  352. -a, --assignee string Assignee (email, name, 'me', or 'unassigned')
  353. -s, --state string State name (e.g., 'Todo', 'In Progress', 'Done')
  354. --priority int Priority (0=None, 1=Urgent, 2=High, 3=Normal, 4=Low)
  355. -e, --estimate int Estimate points (depends on team's estimation system)
  356. --due-date string Due date (YYYY-MM-DD format, or empty to remove)
  357. --delegate string Delegate to user/agent (email, name, displayName, or 'none' to remove)
  358. --labels strings Replace labels with provided names or IDs (comma-separated)
  359. --clear-labels Remove all labels from the issue
  360. --parent string Parent issue ID/identifier (or 'none' to remove parent)
  361. --project string Project name or ID (or 'none' to remove project assignment)
  362. --project-milestone string Project milestone name or ID (or 'none' to remove milestone)
  363. # Attach URL/PR to issue
  364. linctl issue attach <issue-id> [flags]
  365. # Flags:
  366. --pr string GitHub PR URL or PR number
  367. --url string URL to attach
  368. --title string Attachment title (required with --url)
  369. --subtitle string Attachment subtitle
  370. --icon-url string Attachment icon URL
  371. # List attachment entries (canonical attachments + uploads links from markdown)
  372. linctl issue attachment list <issue-id>
  373. linctl issue attachment ls <issue-id> # Alias
  374. # Download attachment entries
  375. linctl issue attachment download <issue-id> [flags]
  376. # Flags:
  377. --all Download all attachment entries
  378. --id string Download by canonical attachment ID
  379. --name string Download by title or filename
  380. --output string Write a single download to this path
  381. --output-dir string Directory to save downloads (default ".")
  382. ```
  383. ### Issue Relation Commands
  384. ```bash
  385. # List all relations for an issue
  386. linctl issue relation list <issue-id>
  387. linctl issue relation ls <issue-id> # Alias
  388. # Add a relation between two issues
  389. linctl issue relation add <issue-id> [flags]
  390. linctl issue relation create <issue-id> [flags] # Alias
  391. # Flags (exactly one required):
  392. --blocks <issue-id> This issue blocks the specified issue
  393. --blocked-by <issue-id> This issue is blocked by the specified issue
  394. --related <issue-id> Mark issues as related
  395. --duplicate <issue-id> Mark this issue as a duplicate
  396. --similar <issue-id> Mark issues as similar
  397. # Remove a relation by its ID (from relation list output)
  398. linctl issue relation remove <relation-id>
  399. linctl issue relation rm <relation-id> # Alias
  400. linctl issue relation delete <relation-id> # Alias
  401. # Examples:
  402. linctl issue relation add LIN-123 --blocks LIN-456 # LIN-123 blocks LIN-456
  403. linctl issue relation add LIN-123 --blocked-by LIN-456 # LIN-123 is blocked by LIN-456
  404. linctl issue relation list LIN-123 -j # JSON output for scripting
  405. ```
  406. **Direction.** `--blocks` makes the issue you name in the command the blocker;
  407. `--blocked-by` makes it the blocked one. `relation list` describes each edge from
  408. the point of view of the issue you queried, so a single edge reads `blocks` from
  409. the blocker's end and `blocked by` from the other end, each line naming the
  410. issue at the far end. In `-j` output the raw shape is
  411. `issue --type--> relatedIssue`, i.e. for `"blocks"` the `issue` field is the
  412. blocker.
  413. ### Agent Commands
  414. ```bash
  415. # View agent delegation/session for an issue
  416. linctl agent <issue-id>
  417. # Mention delegated/active agent
  418. linctl agent mention <issue-id> <message...>
  419. # Optional flag:
  420. --agent string Agent handle override (defaults to delegated/active agent)
  421. ```
  422. ### Team Commands
  423. ```bash
  424. # List all teams with issue counts
  425. linctl team list
  426. linctl team ls # Alias
  427. # Flags:
  428. -l, --limit int Maximum results (default 50)
  429. -o, --sort string Sort order: linear (default), created, updated
  430. # Get team details
  431. linctl team get <team-key>
  432. linctl team show <team-key> # Alias
  433. # Examples:
  434. linctl team get ENG # Shows Engineering team details
  435. linctl team get DESIGN # Shows Design team details
  436. # List team members with roles and status
  437. linctl team members <team-key>
  438. # List workflow states (Backlog, Todo, In Progress, etc.)
  439. linctl team state list <team-key>
  440. # Update a workflow state
  441. linctl team state update <state-id> [flags]
  442. # Key flags:
  443. --name string New name for the state
  444. --color string New color (hex)
  445. --description string New description (empty string clears)
  446. # Examples:
  447. linctl team members ENG # Lists all Engineering team members
  448. linctl team state list ENG # Lists workflow states for Engineering
  449. linctl team state update abc123 --name "Ready" --color "#00ff00"
  450. ```
  451. ### Project Commands
  452. ```bash
  453. # List projects
  454. linctl project list [flags]
  455. linctl project ls [flags] # Alias
  456. # Flags:
  457. -t, --team string Filter by team key
  458. -s, --state string Filter by state (planned, started, paused, completed, canceled)
  459. -l, --limit int Maximum results (default 50)
  460. -o, --sort string Sort order: linear (default), created, updated
  461. -n, --newer-than string Show items created after this time (default: 6_months_ago)
  462. -c, --include-completed Include completed and canceled projects
  463. # Get project details
  464. linctl project get <project-id>
  465. linctl project show <project-id> # Alias
  466. # Create project
  467. linctl project create [flags]
  468. # Key flags:
  469. --name string Project name (required)
  470. -t, --team strings Team key(s) (required)
  471. -d, --description Description
  472. -s, --state project status name, ID, or legacy state type
  473. --status string named project status or ID (for example, Shaping)
  474. --lead email|name|me
  475. --start-date YYYY-MM-DD
  476. --target-date YYYY-MM-DD
  477. --color Hex color
  478. # Update project
  479. linctl project update <project-id> [flags]
  480. # Key flags:
  481. --name string
  482. -d, --description
  483. -s, --state project status name, ID, or legacy state type
  484. --status string named project status or ID (for example, Shaping)
  485. --lead email|name|me|none
  486. --start-date YYYY-MM-DD or empty to clear
  487. --target-date YYYY-MM-DD or empty to clear
  488. --color Hex color
  489. --content Project document body content
  490. # Delete/archive project
  491. linctl project delete <project-id> [flags]
  492. linctl project rm <project-id> [flags]
  493. linctl project remove <project-id> [flags]
  494. # Key flags:
  495. --permanent Permanently delete instead of archive
  496. -f, --force Skip confirmation prompt
  497. ```
  498. ### User Commands
  499. ```bash
  500. # List all users in workspace
  501. linctl user list [flags]
  502. linctl user ls [flags] # Alias
  503. # Flags:
  504. -a, --active Show only active users
  505. -l, --limit int Maximum results (default 50)
  506. -o, --sort string Sort order: linear (default), created, updated
  507. # Examples:
  508. linctl user list # List all users
  509. linctl user list --active # List only active users
  510. # Get user details by email
  511. linctl user get <email>
  512. linctl user show <email> # Alias
  513. # Examples:
  514. linctl user get john@example.com
  515. linctl user get jane.doe@company.com
  516. # Show current authenticated user
  517. linctl user me # Shows your profile with admin status
  518. ```
  519. ### Comment Commands
  520. ```bash
  521. # List all comments for an issue
  522. linctl comment list <issue-id> [flags]
  523. linctl comment ls <issue-id> [flags] # Alias
  524. # Flags:
  525. -l, --limit int Maximum results (default 50)
  526. -o, --sort string Sort order: linear (default), created, updated
  527. # Examples:
  528. linctl comment list LIN-123 # Shows all comments with timestamps
  529. linctl comment list LIN-456 -l 10 # Show latest 10 comments
  530. # Add comment to issue
  531. linctl comment create <issue-id> --body "Comment text"
  532. linctl comment add <issue-id> -b "Comment text" # Alias
  533. linctl comment new <issue-id> -b "Comment text" # Alias
  534. # Get/update/delete comment by ID
  535. linctl comment get <comment-id>
  536. linctl comment show <comment-id> # Alias
  537. linctl comment update <comment-id> --body "Updated text"
  538. linctl comment edit <comment-id> -b "Updated text" # Alias
  539. linctl comment delete <comment-id>
  540. linctl comment rm <comment-id> # Alias
  541. # Examples:
  542. linctl comment create LIN-123 --body "I've started working on this"
  543. linctl comment add LIN-123 -b "Fixed in commit abc123"
  544. linctl comment create LIN-456 --body "@john please review this PR"
  545. ```
  546. ### Label Commands
  547. ```bash
  548. # List labels for a team
  549. linctl label list --team <team-key>
  550. linctl label ls --team <team-key> # Alias
  551. # Get label details
  552. linctl label get <label-id>
  553. # Create label
  554. linctl label create --team <team-key> --name <name> [flags]
  555. # Key flags:
  556. --color string Hex color (e.g. #ff0000)
  557. --description string Description
  558. --is-group Create as a group label (organizes child labels)
  559. --parent string Parent label name or ID
  560. # Update label
  561. linctl label update <label-id> [flags]
  562. # Key flags:
  563. --name string
  564. --color string
  565. --description string Empty string clears description
  566. --parent string Parent label name or ID
  567. --clear-parent Remove parent label
  568. # Delete label
  569. linctl label delete <label-id>
  570. linctl label rm <label-id> # Alias
  571. linctl label remove <label-id> # Alias
  572. ```
  573. ## Output Formats
  574. ### Table Format (Default)
  575. ```bash
  576. linctl issue list
  577. ```
  578. ```
  579. ID Title State Assignee Team Priority
  580. LIN-123 Fix authentication In Progress john@co.com ENG High
  581. LIN-124 Update documentation Done jane@co.com DOC Normal
  582. ```
  583. ### Plaintext Format
  584. ```bash
  585. linctl issue list --plaintext
  586. ```
  587. ```
  588. # Issues
  589. ## BUG: Fix login button alignment
  590. - **ID**: FAK-123
  591. - **State**: In Progress
  592. - **Assignee**: Jane Doe
  593. - **Team**: WEB
  594. - **Created**: 2025-07-12
  595. - **URL**: https://linear.app/example/issue/FAK-123/bug-fix-login-button-alignment
  596. - **Description**: The login button on the main page is misaligned on mobile devices.
  597. Steps to reproduce:
  598. 1. Open the website on a mobile browser.
  599. 2. Navigate to the login page.
  600. 3. Observe the button alignment.
  601. ## FEAT: Add dark mode support
  602. - **ID**: FAK-124
  603. - **State**: Todo
  604. - **Assignee**: John Smith
  605. - **Team**: APP
  606. - **Created**: 2025-07-11
  607. - **URL**: https://linear.app/example/issue/FAK-124/feat-add-dark-mode-support
  608. - **Description**: Implement a dark mode theme for the entire application to improve user experience in low-light environments.
  609. ```
  610. ### JSON Format
  611. ```bash
  612. linctl issue list --json
  613. ```
  614. ```json
  615. [
  616. {
  617. "id": "LIN-123",
  618. "title": "Fix authentication",
  619. "state": "In Progress",
  620. "assignee": "john@co.com",
  621. "team": "ENG",
  622. "priority": "High"
  623. }
  624. ]
  625. ```
  626. ## Configuration
  627. Configuration is stored in `~/.linctl.yaml`:
  628. ```yaml
  629. # Default output format
  630. output: table
  631. # Default pagination limit
  632. limit: 50
  633. # API settings
  634. api:
  635. timeout: 30s
  636. retries: 3
  637. ```
  638. By default, authentication credentials are stored in `~/.linctl-auth.json`.
  639. Users of the external [`pass`](https://www.passwordstore.org/) password manager
  640. can opt in to GPG-backed credential storage with `LINCTL_PASS_NAME`.
  641. ## Authentication
  642. ### Personal API Key (Recommended)
  643. 1. Go to [Linear Settings > Security & Access](https://linear.app/<your-org>/settings/account/security)
  644. 2. Scroll to **Personal API keys** and create a new key
  645. 3. Run `linctl auth` and paste your key
  646. ### Temporary Override (Current Session)
  647. You can temporarily override stored credentials using the `LINCTL_API_KEY` environment variable. This is useful for:
  648. - CI/CD pipelines
  649. - Testing with a different account
  650. - One-off commands without modifying `~/.linctl-auth.json`
  651. ```bash
  652. # Override for a single command
  653. LINCTL_API_KEY="lin_api_..." linctl issue list
  654. # Override for the current shell session
  655. export LINCTL_API_KEY="lin_api_..."
  656. linctl whoami
  657. # Clear override
  658. unset LINCTL_API_KEY
  659. ```
  660. ### Storing the Key in `pass` (Optional)
  661. If you already use the external [`pass`](https://www.passwordstore.org/)
  662. password manager, set `LINCTL_PASS_NAME` to the entry name and `linctl` will
  663. read/write the key through `pass` instead of the JSON config file. If
  664. `LINCTL_PASS_NAME` is unset, this feature is disabled and existing auth behavior
  665. is unchanged.
  666. ```bash
  667. # One-time setup
  668. export LINCTL_PASS_NAME=linear-api-key
  669. linctl auth # stores via `pass insert -m -f -- linear-api-key`
  670. # Subsequent calls just work
  671. linctl whoami
  672. ```
  673. `linctl logout` removes the entry via `pass rm -f -- linear-api-key` and also
  674. removes any legacy `~/.linctl-auth.json` file if one exists.
  675. Precedence: `LINCTL_API_KEY` environment variable > `pass` (when
  676. `LINCTL_PASS_NAME` is set) > config file (`~/.linctl-auth.json`).
  677. ## Time-based Filtering
  678. **⚠️ Default Behavior**: To improve performance and prevent overwhelming data loads, list commands **only show items created in the last 6 months by default**. This is especially important for large workspaces.
  679. ### Using the --newer-than Flag
  680. The `--newer-than` (or `-n`) flag is available on `issue list` and `project list` commands:
  681. ```bash
  682. # Default behavior (last 6 months)
  683. linctl issue list
  684. # Show items from a specific time period
  685. linctl issue list --newer-than 2_weeks_ago
  686. linctl project list --newer-than 1_month_ago
  687. # Show ALL items regardless of age
  688. linctl issue list --newer-than all_time
  689. ```
  690. ### Supported Time Formats
  691. 1. **Relative time expressions**: `N_units_ago`
  692. - Units: `minutes`, `hours`, `days`, `weeks`, `months`, `years`
  693. - Examples: `30_minutes_ago`, `2_hours_ago`, `3_days_ago`, `1_week_ago`, `6_months_ago`
  694. 2. **Special values**:
  695. - `all_time` - Shows all items without any date filter
  696. - ISO dates - `2025-07-01` or `2025-07-01T15:30:00Z`
  697. 3. **Default value**: `6_months_ago` (when flag is not specified)
  698. ### Quick Reference
  699. | Time Expression | Description | Example Command |
  700. |----------------|-------------|-----------------|
  701. | *(no flag)* | Last 6 months (default) | `linctl issue list` |
  702. | `1_day_ago` | Last 24 hours | `linctl issue list --newer-than 1_day_ago` |
  703. | `1_week_ago` | Last 7 days | `linctl issue list --newer-than 1_week_ago` |
  704. | `2_weeks_ago` | Last 14 days | `linctl issue list --newer-than 2_weeks_ago` |
  705. | `1_month_ago` | Last month | `linctl issue list --newer-than 1_month_ago` |
  706. | `3_months_ago` | Last quarter | `linctl issue list --newer-than 3_months_ago` |
  707. | `6_months_ago` | Last 6 months | `linctl issue list --newer-than 6_months_ago` |
  708. | `1_year_ago` | Last year | `linctl issue list --newer-than 1_year_ago` |
  709. | `all_time` | No date filter | `linctl issue list --newer-than all_time` |
  710. | `2025-07-01` | Since specific date | `linctl issue list --newer-than 2025-07-01` |
  711. ### Common Use Cases
  712. ```bash
  713. # Recent activity - issues from last week
  714. linctl issue list --newer-than 1_week_ago
  715. # Sprint planning - issues from current month
  716. linctl issue list --newer-than 1_month_ago --state "Todo"
  717. # Quarterly review - all projects from last 3 months
  718. linctl project list --newer-than 3_months_ago
  719. # Historical analysis - ALL issues ever created
  720. linctl issue list --newer-than all_time --sort created
  721. # Today's issues
  722. linctl issue list --newer-than 1_day_ago
  723. # Combine with other filters
  724. linctl issue list --newer-than 2_weeks_ago --assignee me --sort updated
  725. ```
  726. ## Sorting Options
  727. All list commands support sorting with the `--sort` or `-o` flag:
  728. - **linear** (default): Linear's built-in sorting order (respects manual ordering in the UI)
  729. - **created**: Sort by creation date (newest first)
  730. - **updated**: Sort by last update date (most recently updated first)
  731. ### Examples
  732. ```bash
  733. # Get recently updated issues
  734. linctl issue list --sort updated
  735. # Get oldest projects first
  736. linctl project list --sort created
  737. # Get recently joined users
  738. linctl user list --sort created --active
  739. # Get latest comments on an issue
  740. linctl comment list LIN-123 --sort created
  741. # Combine sorting with filters
  742. linctl issue list --assignee me --state "In Progress" --sort updated
  743. # Combine time filtering with sorting
  744. linctl issue list --newer-than 1_week_ago --sort updated
  745. # Get all projects sorted by creation date
  746. linctl project list --newer-than all_time --sort created
  747. ```
  748. ### Performance Tips
  749. - The 6-month default filter significantly improves performance for large workspaces
  750. - Use specific time ranges when possible instead of `all_time`
  751. - Combine time filtering with other filters (assignee, state, team) for faster results
  752. ## Testing
  753. Current test paths:
  754. ```bash
  755. # Go unit tests
  756. go test ./...
  757. # CLI smoke tests
  758. make test
  759. # or:
  760. ./smoke_test.sh
  761. ```
  762. ## Scripting & Automation
  763. Use `--plaintext` or `--json` flags for scripting:
  764. ```bash
  765. #!/bin/bash
  766. # Get all urgent issues in JSON format
  767. urgent_issues=$(linctl issue list --priority 1 --json)
  768. # Parse with jq
  769. echo "$urgent_issues" | jq '.[] | select(.assignee == "me") | .id'
  770. # Plaintext output for simple parsing
  771. linctl issue list --assignee me --plaintext | cut -f1 | tail -n +2
  772. # Get issue count for different time periods
  773. echo "Last week: $(linctl issue list --newer-than 1_week_ago --json | jq '. | length')"
  774. echo "Last month: $(linctl issue list --newer-than 1_month_ago --json | jq '. | length')"
  775. echo "All time: $(linctl issue list --newer-than all_time --json | jq '. | length')"
  776. # Create and assign issue in one command
  777. linctl issue create --title "Fix bug" --team ENG --assign-me --json
  778. # Get all projects with progress
  779. linctl project list --json | jq '.[] | {name, progress}'
  780. # List all admin users
  781. linctl user list --json | jq '.[] | select(.admin == true) | {name, email}'
  782. # Get team member count
  783. linctl team members ENG --json | jq '. | length'
  784. # Export issue comments
  785. linctl comment list LIN-123 --json > issue-comments.json
  786. ```
  787. ## Real-World Examples
  788. ### Team Workflows
  789. ```bash
  790. # Find which team a user belongs to
  791. for team in $(linctl team list --json | jq -r '.[].key'); do
  792. echo "Checking team: $team"
  793. linctl team members $team --json | jq '.[] | select(.email == "john@example.com")'
  794. done
  795. # List all private teams
  796. linctl team list --json | jq '.[] | select(.private == true) | {key, name}'
  797. # Get teams with more than 50 issues
  798. linctl team list --json | jq '.[] | select(.issueCount > 50) | {key, name, issueCount}'
  799. ```
  800. ### User Management
  801. ```bash
  802. # Find inactive users
  803. linctl user list --json | jq '.[] | select(.active == false) | {name, email}'
  804. # Check if you're an admin
  805. linctl user me --json | jq '.admin'
  806. # List users who are admins but not the current user
  807. linctl user list --json | jq '.[] | select(.admin == true and .isMe == false) | .email'
  808. ```
  809. ### Issue Comments
  810. ```bash
  811. # Add a comment mentioning the issue is blocked
  812. linctl comment create LIN-123 --body "Blocked by LIN-456. Waiting for API changes."
  813. # Get all comments by a specific user
  814. linctl comment list LIN-123 --json | jq '.[] | select(.user.email == "john@example.com") | .body'
  815. # Count comments per issue
  816. for issue in LIN-123 LIN-124 LIN-125; do
  817. count=$(linctl comment list $issue --json | jq '. | length')
  818. echo "$issue: $count comments"
  819. done
  820. ```
  821. ### Project Tracking
  822. ```bash
  823. # List projects nearing completion (>80% progress)
  824. linctl project list --json | jq '.[] | select(.progress > 0.8) | {name, progress}'
  825. # Get all paused projects
  826. linctl project list --state paused
  827. # Show project timeline
  828. linctl project get PROJECT-ID --json | jq '{name, startDate, targetDate, progress}'
  829. ```
  830. ### Daily Standup Helper
  831. ```bash
  832. #!/bin/bash
  833. # Show my recent activity
  834. echo "=== My Issues ==="
  835. linctl issue list --assignee me --limit 10
  836. echo -e "\n=== Recent Comments ==="
  837. for issue in $(linctl issue list --assignee me --json | jq -r '.[].identifier'); do
  838. echo "Comments on $issue:"
  839. linctl comment list $issue --limit 3
  840. done
  841. ```
  842. ## Troubleshooting
  843. ### Authentication Issues
  844. ```bash
  845. # Check authentication status
  846. linctl auth status
  847. # Re-authenticate
  848. linctl auth logout
  849. linctl auth
  850. ```
  851. ### API Rate Limits
  852. Linear has the following rate limits:
  853. - Personal API Keys: 5,000 requests/hour
  854. ### Common Errors
  855. - `Not authenticated`: Run `linctl auth` first
  856. - `Team not found`: Use team key (e.g., "ENG") not display name
  857. - `Invalid priority`: Use numbers 0-4 (0=None, 1=Urgent, 2=High, 3=Normal, 4=Low)
  858. ### Time Filtering Issues
  859. - **Missing old issues?** Remember that list commands default to showing only the last 6 months
  860. - Solution: Use `--newer-than all_time` to see all issues
  861. - **Invalid time expression?** Check the format: `N_units_ago` (e.g., `3_weeks_ago`)
  862. - Valid units: `minutes`, `hours`, `days`, `weeks`, `months`, `years`
  863. - **Performance issues?** Avoid using `all_time` on large workspaces
  864. - Solution: Use specific time ranges like `--newer-than 1_year_ago`
  865. ## Contributing
  866. 1. Fork the repository
  867. 2. Create a feature branch
  868. 3. Make your changes
  869. 4. Add tests
  870. 5. Submit a pull request
  871. See CONTRIBUTING.md for a detailed release checklist and the Homebrew tap auto-bump workflow.
  872. ## License
  873. MIT License - see [LICENSE](LICENSE) file for details.
  874. ## Links
  875. - [Linear API Documentation](https://developers.linear.app/)
  876. - [GitHub Repository](https://github.com/dorkitude/linctl)
  877. - [Issue Tracker](https://github.com/dorkitude/linctl/issues)
  878. ---
  879. **Built with ❤️ using Go, Cobra, and the Linear API**

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.