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.
Badge for your README
Markdown
[](/listings/dorkitude--linctl)HTML
<a href="/listings/dorkitude--linctl"><img src="/api/listings/dorkitude--linctl/badge.svg" alt="findsafeskills safety rating" /></a>Install
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)
- ---
- name: linctl
- 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.
- ---
- # linctl Agent Guide
- Use this skill when the user wants to inspect or modify Linear data through `linctl`.
- ## Quick Rules
- - Always verify auth before substantive work: `linctl auth status` or `linctl whoami`.
- - For read operations, prefer `--json` and parse results with `jq` when needed.
- - Before writing, inspect current state first (`get` / `list --json`).
- - Use command-specific help for exact flags and validation rules: `linctl <command> <subcommand> --help`.
- - Be explicit with filters; defaults can hide expected results.
- - Linear URLs work as entity references. Quote URLs containing `#`. Also GitHub pull
- request URLs, but only if it's attached to a Linear issue.
- ## High-Impact Gotchas
- - `issue list`, `issue search`, and `project list` default to `--newer-than 6_months_ago`.
- - `issue list` and `issue search` exclude completed/canceled by default.
- - `issue search` may also need `--include-archived` for archived matches.
- - `issue list --cycle current` can validly return no rows if no active cycle exists.
- - Parent/sub-issue links are set via `issue update --parent` (not `issue create`).
- - If results look incomplete, retry with:
- - `--newer-than all_time`
- - `--include-completed`
- - `--include-archived` (search)
- ## Auth + Credential Behavior
- - Interactive login: `linctl auth` (or `linctl auth login`).
- - Credentials are stored in `~/.linctl-auth.json`.
- - `LINCTL_API_KEY` overrides stored credentials.
- - Precedence: `LINCTL_API_KEY` > `~/.linctl-auth.json`.
- ## Core Workflow
- 1. Confirm identity and access.
- 2. Discover relevant entities (team key, issue ID, project ID, user email) via `list/search` with `--json`.
- 3. Read exact target with `get`.
- 4. Apply changes with `create/update/assign/comment/label/agent` commands.
- 5. Re-read target and summarize concrete outcome to the user.
- ## Command Map
- - Issues: `linctl issue ...`
- - Projects: `linctl project ...`
- - Teams: `linctl team ...` (includes `state list` and `state update`)
- - Users: `linctl user ...` and `linctl whoami`
- - Comments: `linctl comment ...`
- - Labels: `linctl label ...`
- - Agent Sessions: `linctl agent ...`
- - Auth: `linctl auth ...`
- - Dynamic MCP: `linctl mcp ...` (`sync`, `tools`, `call`)
- ## Suggested Read Patterns
- ```bash
- # Issues assigned to me, no date-limit surprise
- linctl issue list --assignee me --newer-than all_time --include-completed --json
- # Issues in current cycle (if cycle exists)
- linctl issue list --cycle current --limit 20 --json
- # Find issue by text, including archived/completed
- linctl issue search "<query>" --newer-than all_time --include-completed --include-archived --json
- # Project inventory without default date filter
- linctl project list --newer-than all_time --json
- # Create or update a project with the exact workspace-defined status.
- linctl project create --name "Custom Properties" --team END --lead me --status "Shaping"
- linctl project update <project-id> --status "Shaping"
- # Team labels for resolution/validation
- linctl label list --team <TEAM_KEY> --json
- # Team workflow states
- linctl team state list <TEAM_KEY> --json
- # Agent session status for an issue
- linctl agent <ISSUE_ID> --json
- # Dynamic schema-backed tool list and call
- linctl mcp sync
- linctl mcp tools --json
- linctl mcp call query.viewer
- ```
- ## Suggested Write Patterns
- ```bash
- # Update an issue after inspecting it
- linctl issue get LIN-123 --json
- linctl issue update LIN-123 --state "In Progress" --assignee me
- linctl issue get LIN-123 --json
- # Delegate issue to an agent/user
- linctl issue update LIN-123 --delegate "<displayName|email|name>"
- # Set labels by name/ID, or clear
- linctl issue update LIN-123 --labels bug,urgent
- linctl issue update LIN-123 --clear-labels
- # Attach PR or URL
- linctl issue attach LIN-123 --pr https://github.com/org/repo/pull/123
- linctl issue attach LIN-123 --url https://example.com/spec --title "Spec"
- # List/download issue attachment files and uploads links
- linctl issue attachment list LIN-123 --json
- linctl issue attachment download LIN-123 --all --output-dir ./downloads
- linctl issue get LIN-123 --download-attachments --output-dir ./downloads --json
- # Add execution note
- linctl comment create LIN-123 --body "Implemented and verified locally."
- # Comment lifecycle by comment ID
- linctl comment get <COMMENT_ID>
- linctl comment update <COMMENT_ID> --body "Updated note"
- linctl comment delete <COMMENT_ID>
- # Update a workflow state
- linctl team state update <STATE_ID> --name "Ready"
- # Mention delegated/active agent with message
- linctl agent mention LIN-123 "Please pick this up."
- ```
- ## Troubleshooting
- - `Not authenticated`: run `linctl auth` then `linctl auth status`.
- - Empty or partial lists: remove default filters (`--newer-than all_time`, `--include-completed`).
- - `unknown command` / `unknown flag`: binary is old; verify `linctl --version` and reinstall/upgrade.
- - Validation errors on flags: run the exact subcommand help and retry:
- - `linctl issue update --help`
- - `linctl project create --help`
- - `linctl comment update --help`
- - `linctl label create --help`
- - `linctl agent mention --help`
- ## Minimal Discovery Commands
- ```bash
- linctl --help
- linctl issue --help
- linctl project --help
- linctl team --help
- linctl user --help
- linctl comment --help
- linctl label --help
- linctl agent --help
- linctl auth --help
- ```
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)
- # linctl
- A command-line interface for the Linear API, built with Go and Cobra.
- ## Features
- - **Authentication**: personal API key auth (`linctl auth`), env-var override, and optional [`pass`](https://www.passwordstore.org/) credential storage.
- - **Issues**: list/search/get/create/update/assign with support for:
- - cycles, labels, delegation, projects/milestones, parent/sub-issue links
- - due dates, attachments, comments, and rich issue detail output
- - issue relations (blocks, blocked-by, related, duplicate, similar)
- - **Projects**: list/get/create/update/delete/archive.
- - **Teams**: list/get/members/state (list/update).
- - **Users**: list/get/me.
- - **Labels**: list/get/create/update/delete.
- - **Comments**: list/get/create/update/delete.
- - **Agent Sessions**: inspect issue agent session state and mention delegated/active agents.
- - **Raw GraphQL**: execute arbitrary Linear GraphQL using your `linctl` auth context.
- - **Dynamic MCP namespace**: discover and call schema-backed operations via `linctl mcp`.
- - **Output modes**: table, plaintext, and JSON.
- - **Sorting and time filters**: reusable list/search filtering patterns.
- - **Built-in docs**: `linctl docs`.
- - **Read-only smoke testing** support.
- ## Installation
- ### Homebrew (macOS/Linux)
- ```bash
- brew tap dorkitude/linctl
- brew install linctl
- linctl docs # Render the README.md
- ```
- ### Nix
- ```bash
- nix profile install github:dorkitude/linctl
- linctl docs # Render the README.md
- ```
- ### From Source
- ```bash
- 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
- ```bash
- 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
- ```
- ## Important: Default Filters
- **By default, `issue list`, `issue search`, and `project list` commands only show items created in the last 6 months!**
- This improves performance and prevents overwhelming data loads. To see older items:
- - Use `--newer-than 1_year_ago` for items from the last year
- - Use `--newer-than all_time` to see ALL items ever created
- - See the [Time-based Filtering](#-time-based-filtering) section for details
- **By default, `issue list` and `issue search` also filter out canceled and completed items. To see all items, use the `--include-completed` flag.**
- - Need archived matches? Add `--include-archived` when using `issue search`.
- ## Pasting URLs
- Paste Linear URLs anywhere `linctl` takes an issue, project, team or comment.
- ```bash
- linctl issue get https://linear.app/acme/issue/ENG-123/fix-the-thing
- linctl comment get 'https://linear.app/acme/issue/ENG-123/fix-the-thing#comment-b68a4bf5'
- linctl project get https://linear.app/acme/project/roadmap-d05c5c7e8a5c/overview
- linctl issue list --team https://linear.app/acme/team/ENG/active
- linctl issue get https://github.com/acme/api/pull/6153
- ```
- Quote URLs containing `#`. GitHub PR URLs will work as well, but only if one is
- attached to an existing Linear issue.
- ## Quick Start
- > **IMPORTANT** Agents like Claude Code, Cursor, and Gemini should use the `--json` flag on all read operations.
- ### 1. Authentication
- ```bash
- # Interactive authentication
- linctl auth
- # Check authentication status
- linctl auth status
- # Show current user
- linctl whoami
- # View full documentation
- linctl docs | less
- ```
- ### 2. Issue Management
- ```bash
- # List all issues
- linctl issue list
- # List issues assigned to you
- linctl issue list --assignee me
- # List issues in a specific state
- linctl issue list --state "In Progress"
- # List issues sorted by update date
- linctl issue list --sort updated
- # Filter issues by cycle
- linctl issue list --cycle current
- linctl issue list --cycle 42
- # Search issues using Linear's full-text index (shares the same filters as list)
- linctl issue search "login bug" --team ENG
- linctl issue search "customer:" --include-completed --include-archived
- # List recent issues (last 2 weeks instead of default 6 months)
- linctl issue list --newer-than 2_weeks_ago
- # List ALL issues ever created (override 6-month default)
- linctl issue list --newer-than all_time
- # List today's issues
- linctl issue list --newer-than 1_day_ago
- # Get issue details (now includes git branch, cycle, project, attachments, and comments)
- linctl issue get LIN-123
- linctl issue get LIN-123 --download-attachments --output-dir ./downloads
- # Create a new issue
- linctl issue create --title "Bug fix" --team ENG
- linctl issue create --title "Bug fix" --team ENG --project "Q1 Platform"
- linctl issue create --title "Bug fix" --team ENG --project "Q1 Platform" --project-milestone "Phase 1"
- linctl issue create --title "Bug fix" --team ENG --state "In Progress"
- linctl issue create --title "Bug fix" --team ENG --estimate 3
- linctl issue create --title "Bug fix" --team ENG --labels bug,urgent
- linctl issue create --title "Bug fix" --team ENG --delegate agent-runner
- # Assign issue to yourself
- linctl issue assign LIN-123
- # Update issue fields
- linctl issue update LIN-123 --title "New title"
- linctl issue update LIN-123 --description "Updated description"
- linctl issue update LIN-123 --assignee john.doe@company.com
- linctl issue update LIN-123 --assignee me # Assign to yourself
- linctl issue update LIN-123 --assignee unassigned # Remove assignee
- linctl issue update LIN-123 --state "In Progress"
- linctl issue update LIN-123 --priority 1 # 0=None, 1=Urgent, 2=High, 3=Normal, 4=Low
- linctl issue update LIN-123 --estimate 5 # Value depends on team estimation system
- linctl issue update LIN-123 --due-date "2024-12-31"
- linctl issue update LIN-123 --due-date "" # Remove due date
- linctl issue update LIN-123 --project "Q1 Platform"
- linctl issue update LIN-123 --project "none" # Remove project assignment
- linctl issue update LIN-123 --project "Q1 Platform" --project-milestone "Phase 1"
- linctl issue update LIN-123 --project-milestone "none" # Remove project milestone
- linctl issue update LIN-123 --labels bug,urgent
- linctl issue update LIN-123 --clear-labels
- linctl issue update LIN-123 --delegate agent-runner
- linctl issue update LIN-123 --delegate none # Remove delegate
- linctl issue update LIN-123 --parent LIN-100
- linctl issue update LIN-123 --parent none # Remove parent
- # Set up parent-child issue relationships
- linctl issue update LIN-124 --parent LIN-123 # Make LIN-124 a sub-issue of LIN-123
- linctl issue update LIN-125 --parent LIN-123 # Make LIN-125 also a sub-issue
- # Remove parent-child relationships
- linctl issue update LIN-124 --parent none
- # Update multiple fields at once
- linctl issue update LIN-123 --title "Critical Bug" --assignee me --priority 1 --project "Q1 Platform"
- # Attach a GitHub PR or external URL
- linctl issue attach LIN-123 --pr https://github.com/owner/repo/pull/456
- linctl issue attach LIN-123 --pr 456 # Resolves repo from git remote origin
- linctl issue attach LIN-123 --url https://example.com/spec --title "Spec"
- # List/download attachments and uploads.linear.app links
- linctl issue attachment list LIN-123
- linctl issue attachment download LIN-123 --all --output-dir ./downloads
- linctl issue attachment download LIN-123 --id ATTACHMENT-ID
- linctl issue attachment download LIN-123 --name spec.md --output ./spec.md
- # Manage issue relations (blocks, blocked-by, related, duplicate, similar)
- linctl issue relation list LIN-123
- linctl issue relation ls LIN-123 -j # JSON output
- linctl issue relation add LIN-123 --blocks LIN-456
- linctl issue relation add LIN-123 --blocked-by LIN-456
- linctl issue relation add LIN-123 --related LIN-456
- linctl issue relation add LIN-123 --duplicate LIN-456
- linctl issue relation add LIN-123 --similar LIN-456
- linctl issue relation remove RELATION-ID # Use ID from relation list
- ```
- ### 3. Project Management
- ```bash
- # List all projects (shows IDs)
- linctl project list
- # Filter projects by state
- linctl project list --state started
- # List projects created in the last month (instead of default 6 months)
- linctl project list --newer-than 1_month_ago
- # List ALL projects regardless of age
- linctl project list --newer-than all_time
- # Get project details (use ID from list command)
- linctl project get 65a77a62-ec5e-491e-b1d9-84aebee01b33
- # Create a project
- linctl project create --name "Q1 Platform" --team ENG --status "In Progress"
- # Update a project
- linctl project update PROJECT-ID --lead me --target-date 2026-06-30
- # Archive or delete a project
- linctl project delete PROJECT-ID
- linctl project delete PROJECT-ID --permanent --force
- ```
- ### 4. Team Management
- ```bash
- # List all teams
- linctl team list
- # Get team details
- linctl team get ENG
- # List team members
- linctl team members ENG
- # List workflow states for a team
- linctl team state list ENG
- # Update a workflow state
- linctl team state update STATE-ID --name "Ready" --color "#abc"
- ```
- ### 5. User Management
- ```bash
- # List all users
- linctl user list
- # Show only active users
- linctl user list --active
- # Get user details by email
- linctl user get john@example.com
- # Show your own profile
- linctl user me
- ```
- ### 6. Comments
- ```bash
- # List comments on an issue
- linctl comment list LIN-123
- # Add a comment to an issue
- linctl comment create LIN-123 --body "Fixed the authentication bug"
- # Get, update, and delete comments by ID
- linctl comment get COMMENT-ID
- linctl comment update COMMENT-ID --body "Updated comment body"
- linctl comment delete COMMENT-ID
- ```
- ### 7. Label Management
- ```bash
- # List labels for a team
- linctl label list --team ENG
- # Get a label by ID
- linctl label get LABEL-ID
- # Create a label
- linctl label create --team ENG --name bug --color "#ff0000"
- linctl label create --team ENG --name "backend" --is-group
- # Update a label
- linctl label update LABEL-ID --name "critical bug"
- # Delete a label
- linctl label delete LABEL-ID
- ```
- ### 8. Agent Sessions
- ```bash
- # View delegated/agent session state for an issue
- linctl agent ENG-80
- # Mention the delegated/active agent with a message
- linctl agent mention ENG-80 "Please investigate this failure"
- # Override target handle explicitly
- linctl agent mention ENG-80 --agent agent-runner "Please rerun tests"
- ```
- ### 9. Raw GraphQL (API Escape Hatch)
- ```bash
- # Direct query
- linctl graphql 'query { viewer { id name email } }'
- # From a .graphql file
- linctl graphql --file query.graphql
- # With inline variables JSON
- linctl graphql --query 'query($k:String!){ team(id:$k){ id key name } }' --variables '{"k":"ENG"}'
- # With variables file
- linctl graphql --file query.graphql --variables-file vars.json
- # Pipe query from stdin
- cat query.graphql | linctl graphql --variables '{"k":"ENG"}'
- ```
- ### 10. Dynamic MCP Tools (Schema-Driven)
- ```bash
- # Sync cache from live schema introspection (12h TTL)
- linctl mcp sync
- # List cached dynamic tools
- linctl mcp tools
- # Call a tool (full name)
- linctl mcp call query.viewer
- # Call a mutation with JSON arguments
- linctl mcp call mutation.issueCreate --json '{"input":{"title":"Fix login","teamId":"team-id"}}'
- # Override selection set for object return types
- linctl mcp call query.issue --json '{"id":"LIN-123"}' --selection '{ id identifier title state { name } }'
- ```
- ## Command Reference
- ### Global Flags
- - `--plaintext, -p`: Plain text output (non-interactive)
- - `--json, -j`: JSON output for scripting
- - `--help, -h`: Show help
- - `--version, -v`: Show version
- ### Authentication Commands
- ```bash
- linctl auth # Interactive authentication
- linctl auth login # Same as above
- linctl auth status # Check authentication status
- linctl auth logout # Clear stored credentials
- linctl whoami # Show current user
- ```
- ### GraphQL Command
- ```bash
- # Execute raw GraphQL operation
- linctl graphql [query] [flags]
- # Flags:
- -q, --query string Query/mutation string
- -f, --file string Path to a .graphql file
- --variables string Variables as JSON object string
- --variables-file string Path to JSON object file with variables
- ```
- ### MCP Commands
- ```bash
- # Refresh cache of dynamic tools discovered from Linear schema
- linctl mcp sync
- # List cached tools (name, args, return type)
- linctl mcp tools
- # Call by full name (`query.*` or `mutation.*`)
- linctl mcp call <tool-name> [flags]
- # Flags:
- --json string JSON object of tool arguments
- --selection string Override selection set for object/interface/union return types
- ```
- ### Issue Commands
- ```bash
- # List issues with filters
- linctl issue list [flags]
- linctl issue ls [flags] # Short alias
- # Flags:
- -a, --assignee string Filter by assignee (email or 'me')
- -c, --include-completed Include completed and canceled issues
- -s, --state string Filter by state name
- -t, --team string Filter by team key
- -r, --priority int Filter by priority (0-4, default: -1)
- -y, --cycle string Filter by cycle ('current' or cycle number)
- -l, --limit int Maximum results (default 50)
- -o, --sort string Sort order: linear (default), created, updated
- -n, --newer-than string Show items created after this time (default: 6_months_ago, use 'all_time' for no filter)
- # Get issue details (shows parent and sub-issues)
- linctl issue get <issue-id>
- linctl issue show <issue-id> # Alias
- # Flags:
- --download-attachments Download issue attachments and uploads.linear.app links from description/comments
- --output-dir string Directory for downloaded attachments when using --download-attachments (default ".")
- # Create issue
- linctl issue create [flags]
- linctl issue new [flags] # Alias
- # Flags:
- --title string Issue title (required)
- -d, --description string Issue description
- -t, --team string Team key (required)
- --priority int Priority 0-4 (default 3)
- -e, --estimate int Estimate points (depends on team's estimation system)
- -m, --assign-me Assign to yourself
- -s, --state string State name (e.g., 'Todo', 'In Progress')
- --delegate string Delegate to user/agent (email, name, or displayName)
- --labels strings Labels to assign (names or IDs, comma-separated)
- --project string Project name or ID to assign the issue to
- --project-milestone string Project milestone name or ID (requires --project)
- # Assign issue to yourself
- linctl issue assign <issue-id>
- # Update issue
- linctl issue update <issue-id> [flags]
- linctl issue edit <issue-id> [flags] # Alias
- # Flags:
- --title string New title
- -d, --description string New description
- -a, --assignee string Assignee (email, name, 'me', or 'unassigned')
- -s, --state string State name (e.g., 'Todo', 'In Progress', 'Done')
- --priority int Priority (0=None, 1=Urgent, 2=High, 3=Normal, 4=Low)
- -e, --estimate int Estimate points (depends on team's estimation system)
- --due-date string Due date (YYYY-MM-DD format, or empty to remove)
- --delegate string Delegate to user/agent (email, name, displayName, or 'none' to remove)
- --labels strings Replace labels with provided names or IDs (comma-separated)
- --clear-labels Remove all labels from the issue
- --parent string Parent issue ID/identifier (or 'none' to remove parent)
- --project string Project name or ID (or 'none' to remove project assignment)
- --project-milestone string Project milestone name or ID (or 'none' to remove milestone)
- # Attach URL/PR to issue
- linctl issue attach <issue-id> [flags]
- # Flags:
- --pr string GitHub PR URL or PR number
- --url string URL to attach
- --title string Attachment title (required with --url)
- --subtitle string Attachment subtitle
- --icon-url string Attachment icon URL
- # List attachment entries (canonical attachments + uploads links from markdown)
- linctl issue attachment list <issue-id>
- linctl issue attachment ls <issue-id> # Alias
- # Download attachment entries
- linctl issue attachment download <issue-id> [flags]
- # Flags:
- --all Download all attachment entries
- --id string Download by canonical attachment ID
- --name string Download by title or filename
- --output string Write a single download to this path
- --output-dir string Directory to save downloads (default ".")
- ```
- ### Issue Relation Commands
- ```bash
- # List all relations for an issue
- linctl issue relation list <issue-id>
- linctl issue relation ls <issue-id> # Alias
- # Add a relation between two issues
- linctl issue relation add <issue-id> [flags]
- linctl issue relation create <issue-id> [flags] # Alias
- # Flags (exactly one required):
- --blocks <issue-id> This issue blocks the specified issue
- --blocked-by <issue-id> This issue is blocked by the specified issue
- --related <issue-id> Mark issues as related
- --duplicate <issue-id> Mark this issue as a duplicate
- --similar <issue-id> Mark issues as similar
- # Remove a relation by its ID (from relation list output)
- linctl issue relation remove <relation-id>
- linctl issue relation rm <relation-id> # Alias
- linctl issue relation delete <relation-id> # Alias
- # Examples:
- linctl issue relation add LIN-123 --blocks LIN-456 # LIN-123 blocks LIN-456
- linctl issue relation add LIN-123 --blocked-by LIN-456 # LIN-123 is blocked by LIN-456
- linctl issue relation list LIN-123 -j # JSON output for scripting
- ```
- **Direction.** `--blocks` makes the issue you name in the command the blocker;
- `--blocked-by` makes it the blocked one. `relation list` describes each edge from
- the point of view of the issue you queried, so a single edge reads `blocks` from
- the blocker's end and `blocked by` from the other end, each line naming the
- issue at the far end. In `-j` output the raw shape is
- `issue --type--> relatedIssue`, i.e. for `"blocks"` the `issue` field is the
- blocker.
- ### Agent Commands
- ```bash
- # View agent delegation/session for an issue
- linctl agent <issue-id>
- # Mention delegated/active agent
- linctl agent mention <issue-id> <message...>
- # Optional flag:
- --agent string Agent handle override (defaults to delegated/active agent)
- ```
- ### Team Commands
- ```bash
- # List all teams with issue counts
- linctl team list
- linctl team ls # Alias
- # Flags:
- -l, --limit int Maximum results (default 50)
- -o, --sort string Sort order: linear (default), created, updated
- # Get team details
- linctl team get <team-key>
- linctl team show <team-key> # Alias
- # Examples:
- linctl team get ENG # Shows Engineering team details
- linctl team get DESIGN # Shows Design team details
- # List team members with roles and status
- linctl team members <team-key>
- # List workflow states (Backlog, Todo, In Progress, etc.)
- linctl team state list <team-key>
- # Update a workflow state
- linctl team state update <state-id> [flags]
- # Key flags:
- --name string New name for the state
- --color string New color (hex)
- --description string New description (empty string clears)
- # Examples:
- linctl team members ENG # Lists all Engineering team members
- linctl team state list ENG # Lists workflow states for Engineering
- linctl team state update abc123 --name "Ready" --color "#00ff00"
- ```
- ### Project Commands
- ```bash
- # List projects
- linctl project list [flags]
- linctl project ls [flags] # Alias
- # Flags:
- -t, --team string Filter by team key
- -s, --state string Filter by state (planned, started, paused, completed, canceled)
- -l, --limit int Maximum results (default 50)
- -o, --sort string Sort order: linear (default), created, updated
- -n, --newer-than string Show items created after this time (default: 6_months_ago)
- -c, --include-completed Include completed and canceled projects
- # Get project details
- linctl project get <project-id>
- linctl project show <project-id> # Alias
- # Create project
- linctl project create [flags]
- # Key flags:
- --name string Project name (required)
- -t, --team strings Team key(s) (required)
- -d, --description Description
- -s, --state project status name, ID, or legacy state type
- --status string named project status or ID (for example, Shaping)
- --lead email|name|me
- --start-date YYYY-MM-DD
- --target-date YYYY-MM-DD
- --color Hex color
- # Update project
- linctl project update <project-id> [flags]
- # Key flags:
- --name string
- -d, --description
- -s, --state project status name, ID, or legacy state type
- --status string named project status or ID (for example, Shaping)
- --lead email|name|me|none
- --start-date YYYY-MM-DD or empty to clear
- --target-date YYYY-MM-DD or empty to clear
- --color Hex color
- --content Project document body content
- # Delete/archive project
- linctl project delete <project-id> [flags]
- linctl project rm <project-id> [flags]
- linctl project remove <project-id> [flags]
- # Key flags:
- --permanent Permanently delete instead of archive
- -f, --force Skip confirmation prompt
- ```
- ### User Commands
- ```bash
- # List all users in workspace
- linctl user list [flags]
- linctl user ls [flags] # Alias
- # Flags:
- -a, --active Show only active users
- -l, --limit int Maximum results (default 50)
- -o, --sort string Sort order: linear (default), created, updated
- # Examples:
- linctl user list # List all users
- linctl user list --active # List only active users
- # Get user details by email
- linctl user get <email>
- linctl user show <email> # Alias
- # Examples:
- linctl user get john@example.com
- linctl user get jane.doe@company.com
- # Show current authenticated user
- linctl user me # Shows your profile with admin status
- ```
- ### Comment Commands
- ```bash
- # List all comments for an issue
- linctl comment list <issue-id> [flags]
- linctl comment ls <issue-id> [flags] # Alias
- # Flags:
- -l, --limit int Maximum results (default 50)
- -o, --sort string Sort order: linear (default), created, updated
- # Examples:
- linctl comment list LIN-123 # Shows all comments with timestamps
- linctl comment list LIN-456 -l 10 # Show latest 10 comments
- # Add comment to issue
- linctl comment create <issue-id> --body "Comment text"
- linctl comment add <issue-id> -b "Comment text" # Alias
- linctl comment new <issue-id> -b "Comment text" # Alias
- # Get/update/delete comment by ID
- linctl comment get <comment-id>
- linctl comment show <comment-id> # Alias
- linctl comment update <comment-id> --body "Updated text"
- linctl comment edit <comment-id> -b "Updated text" # Alias
- linctl comment delete <comment-id>
- linctl comment rm <comment-id> # Alias
- # Examples:
- linctl comment create LIN-123 --body "I've started working on this"
- linctl comment add LIN-123 -b "Fixed in commit abc123"
- linctl comment create LIN-456 --body "@john please review this PR"
- ```
- ### Label Commands
- ```bash
- # List labels for a team
- linctl label list --team <team-key>
- linctl label ls --team <team-key> # Alias
- # Get label details
- linctl label get <label-id>
- # Create label
- linctl label create --team <team-key> --name <name> [flags]
- # Key flags:
- --color string Hex color (e.g. #ff0000)
- --description string Description
- --is-group Create as a group label (organizes child labels)
- --parent string Parent label name or ID
- # Update label
- linctl label update <label-id> [flags]
- # Key flags:
- --name string
- --color string
- --description string Empty string clears description
- --parent string Parent label name or ID
- --clear-parent Remove parent label
- # Delete label
- linctl label delete <label-id>
- linctl label rm <label-id> # Alias
- linctl label remove <label-id> # Alias
- ```
- ## Output Formats
- ### Table Format (Default)
- ```bash
- linctl issue list
- ```
- ```
- ID Title State Assignee Team Priority
- LIN-123 Fix authentication In Progress john@co.com ENG High
- LIN-124 Update documentation Done jane@co.com DOC Normal
- ```
- ### Plaintext Format
- ```bash
- linctl issue list --plaintext
- ```
- ```
- # Issues
- ## BUG: Fix login button alignment
- - **ID**: FAK-123
- - **State**: In Progress
- - **Assignee**: Jane Doe
- - **Team**: WEB
- - **Created**: 2025-07-12
- - **URL**: https://linear.app/example/issue/FAK-123/bug-fix-login-button-alignment
- - **Description**: The login button on the main page is misaligned on mobile devices.
- Steps to reproduce:
- 1. Open the website on a mobile browser.
- 2. Navigate to the login page.
- 3. Observe the button alignment.
- ## FEAT: Add dark mode support
- - **ID**: FAK-124
- - **State**: Todo
- - **Assignee**: John Smith
- - **Team**: APP
- - **Created**: 2025-07-11
- - **URL**: https://linear.app/example/issue/FAK-124/feat-add-dark-mode-support
- - **Description**: Implement a dark mode theme for the entire application to improve user experience in low-light environments.
- ```
- ### JSON Format
- ```bash
- linctl issue list --json
- ```
- ```json
- [
- {
- "id": "LIN-123",
- "title": "Fix authentication",
- "state": "In Progress",
- "assignee": "john@co.com",
- "team": "ENG",
- "priority": "High"
- }
- ]
- ```
- ## Configuration
- Configuration is stored in `~/.linctl.yaml`:
- ```yaml
- # Default output format
- output: table
- # Default pagination limit
- limit: 50
- # API settings
- api:
- timeout: 30s
- retries: 3
- ```
- By default, authentication credentials are stored in `~/.linctl-auth.json`.
- Users of the external [`pass`](https://www.passwordstore.org/) password manager
- can opt in to GPG-backed credential storage with `LINCTL_PASS_NAME`.
- ## Authentication
- ### Personal API Key (Recommended)
- 1. Go to [Linear Settings > Security & Access](https://linear.app/<your-org>/settings/account/security)
- 2. Scroll to **Personal API keys** and create a new key
- 3. Run `linctl auth` and paste your key
- ### Temporary Override (Current Session)
- You can temporarily override stored credentials using the `LINCTL_API_KEY` environment variable. This is useful for:
- - CI/CD pipelines
- - Testing with a different account
- - One-off commands without modifying `~/.linctl-auth.json`
- ```bash
- # Override for a single command
- LINCTL_API_KEY="lin_api_..." linctl issue list
- # Override for the current shell session
- export LINCTL_API_KEY="lin_api_..."
- linctl whoami
- # Clear override
- unset LINCTL_API_KEY
- ```
- ### Storing the Key in `pass` (Optional)
- If you already use the external [`pass`](https://www.passwordstore.org/)
- password manager, set `LINCTL_PASS_NAME` to the entry name and `linctl` will
- read/write the key through `pass` instead of the JSON config file. If
- `LINCTL_PASS_NAME` is unset, this feature is disabled and existing auth behavior
- is unchanged.
- ```bash
- # One-time setup
- export LINCTL_PASS_NAME=linear-api-key
- linctl auth # stores via `pass insert -m -f -- linear-api-key`
- # Subsequent calls just work
- linctl whoami
- ```
- `linctl logout` removes the entry via `pass rm -f -- linear-api-key` and also
- removes any legacy `~/.linctl-auth.json` file if one exists.
- Precedence: `LINCTL_API_KEY` environment variable > `pass` (when
- `LINCTL_PASS_NAME` is set) > config file (`~/.linctl-auth.json`).
- ## Time-based Filtering
- **⚠️ 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.
- ### Using the --newer-than Flag
- The `--newer-than` (or `-n`) flag is available on `issue list` and `project list` commands:
- ```bash
- # Default behavior (last 6 months)
- linctl issue list
- # Show items from a specific time period
- linctl issue list --newer-than 2_weeks_ago
- linctl project list --newer-than 1_month_ago
- # Show ALL items regardless of age
- linctl issue list --newer-than all_time
- ```
- ### Supported Time Formats
- 1. **Relative time expressions**: `N_units_ago`
- - Units: `minutes`, `hours`, `days`, `weeks`, `months`, `years`
- - Examples: `30_minutes_ago`, `2_hours_ago`, `3_days_ago`, `1_week_ago`, `6_months_ago`
- 2. **Special values**:
- - `all_time` - Shows all items without any date filter
- - ISO dates - `2025-07-01` or `2025-07-01T15:30:00Z`
- 3. **Default value**: `6_months_ago` (when flag is not specified)
- ### Quick Reference
- | Time Expression | Description | Example Command |
- |----------------|-------------|-----------------|
- | *(no flag)* | Last 6 months (default) | `linctl issue list` |
- | `1_day_ago` | Last 24 hours | `linctl issue list --newer-than 1_day_ago` |
- | `1_week_ago` | Last 7 days | `linctl issue list --newer-than 1_week_ago` |
- | `2_weeks_ago` | Last 14 days | `linctl issue list --newer-than 2_weeks_ago` |
- | `1_month_ago` | Last month | `linctl issue list --newer-than 1_month_ago` |
- | `3_months_ago` | Last quarter | `linctl issue list --newer-than 3_months_ago` |
- | `6_months_ago` | Last 6 months | `linctl issue list --newer-than 6_months_ago` |
- | `1_year_ago` | Last year | `linctl issue list --newer-than 1_year_ago` |
- | `all_time` | No date filter | `linctl issue list --newer-than all_time` |
- | `2025-07-01` | Since specific date | `linctl issue list --newer-than 2025-07-01` |
- ### Common Use Cases
- ```bash
- # Recent activity - issues from last week
- linctl issue list --newer-than 1_week_ago
- # Sprint planning - issues from current month
- linctl issue list --newer-than 1_month_ago --state "Todo"
- # Quarterly review - all projects from last 3 months
- linctl project list --newer-than 3_months_ago
- # Historical analysis - ALL issues ever created
- linctl issue list --newer-than all_time --sort created
- # Today's issues
- linctl issue list --newer-than 1_day_ago
- # Combine with other filters
- linctl issue list --newer-than 2_weeks_ago --assignee me --sort updated
- ```
- ## Sorting Options
- All list commands support sorting with the `--sort` or `-o` flag:
- - **linear** (default): Linear's built-in sorting order (respects manual ordering in the UI)
- - **created**: Sort by creation date (newest first)
- - **updated**: Sort by last update date (most recently updated first)
- ### Examples
- ```bash
- # Get recently updated issues
- linctl issue list --sort updated
- # Get oldest projects first
- linctl project list --sort created
- # Get recently joined users
- linctl user list --sort created --active
- # Get latest comments on an issue
- linctl comment list LIN-123 --sort created
- # Combine sorting with filters
- linctl issue list --assignee me --state "In Progress" --sort updated
- # Combine time filtering with sorting
- linctl issue list --newer-than 1_week_ago --sort updated
- # Get all projects sorted by creation date
- linctl project list --newer-than all_time --sort created
- ```
- ### Performance Tips
- - The 6-month default filter significantly improves performance for large workspaces
- - Use specific time ranges when possible instead of `all_time`
- - Combine time filtering with other filters (assignee, state, team) for faster results
- ## Testing
- Current test paths:
- ```bash
- # Go unit tests
- go test ./...
- # CLI smoke tests
- make test
- # or:
- ./smoke_test.sh
- ```
- ## Scripting & Automation
- Use `--plaintext` or `--json` flags for scripting:
- ```bash
- #!/bin/bash
- # Get all urgent issues in JSON format
- urgent_issues=$(linctl issue list --priority 1 --json)
- # Parse with jq
- echo "$urgent_issues" | jq '.[] | select(.assignee == "me") | .id'
- # Plaintext output for simple parsing
- linctl issue list --assignee me --plaintext | cut -f1 | tail -n +2
- # Get issue count for different time periods
- echo "Last week: $(linctl issue list --newer-than 1_week_ago --json | jq '. | length')"
- echo "Last month: $(linctl issue list --newer-than 1_month_ago --json | jq '. | length')"
- echo "All time: $(linctl issue list --newer-than all_time --json | jq '. | length')"
- # Create and assign issue in one command
- linctl issue create --title "Fix bug" --team ENG --assign-me --json
- # Get all projects with progress
- linctl project list --json | jq '.[] | {name, progress}'
- # List all admin users
- linctl user list --json | jq '.[] | select(.admin == true) | {name, email}'
- # Get team member count
- linctl team members ENG --json | jq '. | length'
- # Export issue comments
- linctl comment list LIN-123 --json > issue-comments.json
- ```
- ## Real-World Examples
- ### Team Workflows
- ```bash
- # Find which team a user belongs to
- for team in $(linctl team list --json | jq -r '.[].key'); do
- echo "Checking team: $team"
- linctl team members $team --json | jq '.[] | select(.email == "john@example.com")'
- done
- # List all private teams
- linctl team list --json | jq '.[] | select(.private == true) | {key, name}'
- # Get teams with more than 50 issues
- linctl team list --json | jq '.[] | select(.issueCount > 50) | {key, name, issueCount}'
- ```
- ### User Management
- ```bash
- # Find inactive users
- linctl user list --json | jq '.[] | select(.active == false) | {name, email}'
- # Check if you're an admin
- linctl user me --json | jq '.admin'
- # List users who are admins but not the current user
- linctl user list --json | jq '.[] | select(.admin == true and .isMe == false) | .email'
- ```
- ### Issue Comments
- ```bash
- # Add a comment mentioning the issue is blocked
- linctl comment create LIN-123 --body "Blocked by LIN-456. Waiting for API changes."
- # Get all comments by a specific user
- linctl comment list LIN-123 --json | jq '.[] | select(.user.email == "john@example.com") | .body'
- # Count comments per issue
- for issue in LIN-123 LIN-124 LIN-125; do
- count=$(linctl comment list $issue --json | jq '. | length')
- echo "$issue: $count comments"
- done
- ```
- ### Project Tracking
- ```bash
- # List projects nearing completion (>80% progress)
- linctl project list --json | jq '.[] | select(.progress > 0.8) | {name, progress}'
- # Get all paused projects
- linctl project list --state paused
- # Show project timeline
- linctl project get PROJECT-ID --json | jq '{name, startDate, targetDate, progress}'
- ```
- ### Daily Standup Helper
- ```bash
- #!/bin/bash
- # Show my recent activity
- echo "=== My Issues ==="
- linctl issue list --assignee me --limit 10
- echo -e "\n=== Recent Comments ==="
- for issue in $(linctl issue list --assignee me --json | jq -r '.[].identifier'); do
- echo "Comments on $issue:"
- linctl comment list $issue --limit 3
- done
- ```
- ## Troubleshooting
- ### Authentication Issues
- ```bash
- # Check authentication status
- linctl auth status
- # Re-authenticate
- linctl auth logout
- linctl auth
- ```
- ### API Rate Limits
- Linear has the following rate limits:
- - Personal API Keys: 5,000 requests/hour
- ### Common Errors
- - `Not authenticated`: Run `linctl auth` first
- - `Team not found`: Use team key (e.g., "ENG") not display name
- - `Invalid priority`: Use numbers 0-4 (0=None, 1=Urgent, 2=High, 3=Normal, 4=Low)
- ### Time Filtering Issues
- - **Missing old issues?** Remember that list commands default to showing only the last 6 months
- - Solution: Use `--newer-than all_time` to see all issues
- - **Invalid time expression?** Check the format: `N_units_ago` (e.g., `3_weeks_ago`)
- - Valid units: `minutes`, `hours`, `days`, `weeks`, `months`, `years`
- - **Performance issues?** Avoid using `all_time` on large workspaces
- - Solution: Use specific time ranges like `--newer-than 1_year_ago`
- ## Contributing
- 1. Fork the repository
- 2. Create a feature branch
- 3. Make your changes
- 4. Add tests
- 5. Submit a pull request
- See CONTRIBUTING.md for a detailed release checklist and the Homebrew tap auto-bump workflow.
- ## License
- MIT License - see [LICENSE](LICENSE) file for details.
- ## Links
- - [Linear API Documentation](https://developers.linear.app/)
- - [GitHub Repository](https://github.com/dorkitude/linctl)
- - [Issue Tracker](https://github.com/dorkitude/linctl/issues)
- ---
- **Built with ❤️ using Go, Cobra, and the Linear API**
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.