cli

Documentation

Overview

Package cli implements the command-line interface for the Linear CLI.

Architecture

The CLI is built using the Cobra framework and follows a modular command structure.

The root command is defined in root.go, which serves as the entry point and coordinates all subcommands. Each major entity (issues, cycles, projects, etc.) has its own file:

• root.go - Root command and global flags (entry point)
• auth.go - Authentication commands (login, logout, status)
• issues.go - Issue management (list, get, create, update, comment, link)
• cycles.go - Cycle operations (list, get, analyze)
• projects.go - Project management (list, get, create, update)
• search.go - Unified search across entities with dependency filtering
• deps.go - Dependency graph visualization
• skills.go - Claude Code skill management
• init.go - Team configuration
• onboard.go - Setup status and quick start guide

Common Patterns

## Team Resolution

Commands that require team context follow a consistent resolution order:

1. Explicit --team flag
2. Default team from .linear.yaml (set via 'linear init')
3. Error if neither is provided

Use GetDefaultTeam to retrieve the configured default team.

## Limit Validation

All list commands support --limit flags with consistent validation:

• Default: 25 results
• Maximum: 250 results (Linear API limit)
• Values <= 0 default to 25
• Values > 250 return an error

Use [validateAndNormalizeLimit] for consistent validation.

## Error Handling

Standardized error messages are defined in errors.go:

• ErrTeamRequired - For missing team context
• Use errors.New() for constant messages (not fmt.Errorf)

## Flag Descriptions

Reusable flag descriptions are centralized in flags.go:

• TeamFlagDescription - Standard team flag help text

## Helpers

Common utilities in helpers.go:

• [hasStdinPipe] - Detect piped input
• [readStdin] - Read from stdin
• [parseCommaSeparated] - Parse comma-separated values
• [getDescriptionFromFlagOrStdin] - Get text from flag or pipe
• [uploadAndAppendAttachments] - Upload files and generate markdown
• [validateAndNormalizeLimit] - Validate --limit flags
• [looksLikeCycleNumber] - Detect numeric cycle IDs

Dependency Management

The search command supports powerful dependency filtering:

• --blocked-by ID - Find issues blocked by a specific issue
• --blocks ID - Find issues blocking a specific issue
• --has-blockers - Find all blocked issues
• --has-dependencies - Find issues with prerequisites
• --has-circular-deps - Detect circular dependency chains
• --max-depth N - Filter by dependency chain depth

The deps command visualizes dependency graphs using Mermaid syntax.

Service Layer

Commands interact with Linear via the service layer (internal/service):

• IssueService - Issue operations
• CycleService - Cycle analytics and retrieval
• ProjectService - Project management
• SearchService - Unified search with dependency filters
• DepsService - Dependency graph analysis
• UserService - User resolution (name/email → ID)

Services are obtained via helper functions:

• [getLinearClient]
• [getIssueService]
• [getCycleService]
• [getProjectService]
• [getSearchService]
• [getDepsService]
• [getUserService]

State Management

The CLI is stateless between invocations. Each command:

1. Creates a fresh linear.Client from stored OAuth tokens
2. Constructs service layer instances as needed
3. Executes the operation
4. Exits

State persisted between runs:

• OAuth tokens (via token.Storage in ~/.linear/)
• Team defaults (via ConfigManager in .linear.yaml)

Configuration

Team defaults are stored in .linear.yaml via ConfigManager. OAuth tokens are stored securely via token.Storage.

Testing

Each command file has corresponding tests in *_test.go. See test files for examples of command validation and flag parsing.

Index

• Constants
• Variables
• func Execute()
• func GetDefaultTeam() string
• func NewCmdWithDeps(deps *Dependencies, cmdFactory func() *cobra.Command) *cobra.Command
• func NewRootCmd() *cobra.Command
• func NewTestClient(token string) *linear.Client
• func ResolutionError(resourceType, value, specificCommand string) error
• type DepEdge
• type DepNode
• type Dependencies
  • func NewDependencies(client *linear.Client) *Dependencies
  • func NewTestDependencies(client *linear.Client) *Dependencies
• type IssueSearchOptions
• type ProjectConfig
  • func LoadProjectConfig() (*ProjectConfig, error)

Constants

const (
	// DefaultLimit is the default number of results to return
	DefaultLimit = 25
	// MaxLimit is the maximum number of results allowed by the Linear API
	MaxLimit = 250
)

const (
	// ErrTeamRequired is returned when a team is required but not provided
	ErrTeamRequired = "--team is required (or run 'linear init' to set a default)"
)

Standard error messages

const (
	// TeamFlagDescription is the standard description for the --team flag
	TeamFlagDescription = "Team ID or key (uses .linear.yaml default)"
)

Flag descriptions - centralized to ensure consistency across commands

Variables

var (

	// Version is set via ldflags at build time
	Version = "dev"
)

Functions

func Execute

func Execute()

Execute runs the CLI with dependency injection

func GetDefaultTeam

func GetDefaultTeam() string

GetDefaultTeam returns the default team from config, or empty string

func NewCmdWithDeps

func NewCmdWithDeps(deps *Dependencies, cmdFactory func() *cobra.Command) *cobra.Command

NewCmdWithDeps creates a command with dependencies injected for testing This allows tests to provide mock dependencies

func NewRootCmd

func NewRootCmd() *cobra.Command

NewRootCmd creates the root command for the 'linear' CLI

func NewTestClient

func NewTestClient(token string) *linear.Client

NewTestClient creates a Linear client with a test token Use this with a mock server for integration tests

func ResolutionError

func ResolutionError(resourceType, value, specificCommand string) error

ResolutionError creates a standard error message when auto-resolution fails

Types

type DepEdge

type DepEdge struct {
	From string // blocks
	To   string // is blocked by
	Type string
}

DepEdge represents a directed edge (dependency) in the graph

type DepNode

type DepNode struct {
	ID         string
	Identifier string
	Title      string
	State      string
}

DepNode represents a node in the dependency graph

type Dependencies

type Dependencies struct {
	// Client is the Linear API client
	Client *linear.Client

	// Services provide business logic and formatting
	Issues     service.IssueServiceInterface
	Cycles     service.CycleServiceInterface
	Projects   service.ProjectServiceInterface
	Search     service.SearchServiceInterface
	Teams      service.TeamServiceInterface
	Users      service.UserServiceInterface
	TaskExport service.TaskExportServiceInterface
}

Dependencies holds all injectable dependencies for CLI commands This enables testing by allowing mock implementations to be injected

func NewDependencies

func NewDependencies(client *linear.Client) *Dependencies

NewDependencies creates dependencies with real implementations

func NewTestDependencies

func NewTestDependencies(client *linear.Client) *Dependencies

NewTestDependencies creates a Dependencies instance for testing Uses the provided client (which can be a mock or test client)

type IssueSearchOptions

type IssueSearchOptions struct {
	TextQuery   string
	Team        string
	State       string
	Priority    int
	Assignee    string
	Cycle       string
	Labels      string
	BlockedBy   string
	Blocks      string
	HasBlockers bool
	HasDeps     bool
	HasCircular bool
	DepthMax    int
	Limit       int
	Format      string
	Output      string
}

IssueSearchOptions holds all parameters for issue search

type ProjectConfig

type ProjectConfig struct {
	Team string `yaml:"team"`
}

ProjectConfig represents the .linear.yaml config file

func LoadProjectConfig

func LoadProjectConfig() (*ProjectConfig, error)

LoadProjectConfig loads the .linear.yaml config from current or parent directories