DOCSEARCHbyAlgolia
Submit Docs

linctl CLI

repository·master·Indexed 41 days ago

https://github.com/dorkitude/linctl

A command-line interface for the Linear API designed for developers and AI agents. It provides high-level abstractions for managing issues, projects, teams, and users, alongside low-level access via raw GraphQL and a dynamic Model Context Protocol (MCP) interface.

Tokens
29.6K
Snippets
127
Records
166
Agent score
48%

What's inside linctl

  1. Overview of Linear Webhooks

    master

    Linear webhooks provide HTTP push notifications when data is created or updated within an Organization. They allow for integrations and custom workflows based on real-time data changes.

    Key Characteristics

    • Scope: Webhooks are specific to an Organization and can be configured for all public teams or a single specific team.
    • Permissions: Only workspace admins or OAuth applications with the admin scope can create or read webhooks.
    • Supported Models: Webhooks are available for Issues, Issue attachments, Issue comments, Issue labels, Comment reactions, Projects, Project updates, and Cycles.
    • Additional Types: Includes Issue SLA and OAuthApp revoked events.

  2. Key features of the Linear TypeScript SDK

    master

    The SDK provides a high-level interface for Linear's GraphQL API with the following capabilities:

    • Fully typed GraphQL operations: Leverages TypeScript for end-to-end type safety.
    • Built-in pagination handling: Simplifies navigating large datasets.
    • Real-time subscriptions support: Enables listening to live updates.
    • Comprehensive error handling: Structured way to manage API failures.
    • GraphQL-based: Built directly on top of Linear's GraphQL API.

  3. Review current linctl command coverage

    master

    As of the current branch, linctl provides coverage for the following resources:

    • issue: list, search, get, assign, create, and update.
      • Update flows support project linking (--project), project milestone linking (--project-milestone), and parent-child linking (--parent).
    • project: list, get, create, update, and delete (deleting archives by default; use --permanent for permanent deletion).
    • comment: list and create.
    • team: list, get, and members.
    • user: list, get, and me.
    • auth: login, status, and logout.

  4. Avoid default filters in read operations

    master

    Many list and search commands in linctl apply restrictive default filters that may cause results to appear missing. If you receive empty or incomplete lists, explicitly override these defaults:

    • Date Limit: Commands like issue list, issue search, and project list default to --newer-than 6_months_ago. Use --newer-than all_time to see all records.
    • Completion Status: issue list and issue search exclude completed or canceled issues by default. Use --include-completed to include them.
    • Archived Status: issue search excludes archived issues by default. Use --include-archived to find them.

  6. Use metadata and dynamic date formatting in attachments

    master

    Attachments support rich metadata and dynamic formatting to enhance how they appear in the UI:

    Metadata

    • Key-Value Pairs: You can store integration-related information in a metadata object. This is currently only exposed via the API.
    • Rich Features: Metadata supports rendering titles, messages (with optional subject, body, and timestamp), and attribute lists.

    Date Formatting

    Subtitles can use dynamic variables for relative time formatting:

    • {variableName__since}: Formats as a human-readable string like "2 days ago".
    • {variableName__relativeTimestamp}: Provides relative timestamp formatting.

  7. Query Issues and Manage Relations

    master

    Issues are a core domain. You can query them using filters and ordering.

    Issue Relations

    Relations are directional. In the schema:

    • IssueRelation.issue: The source issue (the one originating the relation).
    • IssueRelation.relatedIssue: The target issue (the one being acted upon).

    Example: type: "blocks"

    • issue blocks relatedIssue (The issue is the blocker).

    Example: type: "duplicate"

    • issue is a duplicate of relatedIssue.

    IssueRelationCreateInput accepts both UUIDs and issue identifiers (e.g., ENG-123).

    query Issues($filter: IssueFilter, $orderBy: IssueOrderBy, $first: Int, $after: String) {
  issues(filter: $filter, orderBy: $orderBy, first: $first, after: $after) {
    nodes {
      id
      identifier
      title
      priority
      state { id name type color }
      team { id key name }
      assignee { id name email }
      createdAt
      updatedAt
    }
    pageInfo { hasNextPage endCursor }
  }
}

mutation IssueRelationCreate($input: IssueRelationCreateInput!) {
  issueRelationCreate(input: $input) {
    success
    issueRelation {
      id
      type
      issue { id identifier }
      relatedIssue { id identifier }
    }
  }
}

  8. Understand linctl default filters and time constraints

    master

    To optimize performance, linctl applies default filters to list and search commands:

    1. Time Limit: issue list, issue search, and project list only show items created in the last 6 months by default. To override this, use:

      • --newer-than 1_year_ago
      • --newer-than all_time (to see everything)
      • --newer-than 1_day_ago

    2. Status Filter: issue list and issue search filter out canceled and completed items by default. To include them, use:

      • --include-completed
      • --include-archived (specifically for issue search)

  9. Understand Linear API rate limits

    master

    Linear employs a leaky bucket algorithm for rate limiting. Limits are applied based on your authentication method and request type.

    API Request Limits

    • Authenticated Requests (API Key): 1,500 requests per hour (associated with the authenticated user).
    • OAuth App: 1,200 requests per hour per user/app.
    • Unauthenticated Requests: 60 requests per hour (associated with the originating IP address).

    Complexity Limits

    In addition to request counts, Linear limits the 'complexity' of queries:

    • Authenticated Requests (API Key): 250,000 complexity points per hour.
    • Unauthenticated Requests: 10,000 complexity points per hour.
    • Maximum Query Complexity: A single query cannot exceed 10,000 points.

  10. Understand the scope of linctl vs. Linear API documentation

    master

    The documentation snapshots in this repository describe Linear's API capabilities in general, rather than the specific feature surface of the linctl CLI.

    While these files provide useful background for understanding the underlying API (such as OAuth flows or webhooks), they may include topics that are not yet exposed as top-level commands in linctl. Always use linctl --help and the main README.md to verify current CLI command availability.

  11. How Linear handles API deprecations

    master
    Linear does not use traditional API versioning. Instead, it leverages the evolving nature of GraphQL to manage changes. When significant changes occur, Linear follows a proactive approach: they reach out to developers, provide transition time, and may leave non-functioning stubs in the schema to prevent immediate breakage of existing queries or mutations.

  12. Key concepts of Linear Attachments

    master

    Attachments in Linear allow you to link external resources to issues. They are designed primarily for API developers and integrations.

    Core behaviors include:

    • URL-based Identity: Unique URLs are the central identifier for attachments.
    • Idempotency: Creating an attachment with a URL that already exists on a specific issue will update the existing attachment rather than creating a duplicate.
    • Queryability: You can query both attachments and their associated issues using the attachment's URL.