developing-linear-cli

name	developing-linear-cli
description	Develop and maintain the linear-cli codebase (commands, config/auth behavior, docs, tests, release metadata).

Developing linear-cli

linear-cli is a Bun + TypeScript CLI for Linear using raw GraphQL calls to https://api.linear.app/graphql.

Run and validate

bun run src/index.ts <command> <subcommand> [flags]
bun run lint
bun run typecheck
bun run test
bun run build

Always run lint + typecheck + test before committing.

Current architecture

• src/index.ts - CLI entrypoint (run() + top-level error handling)
• src/cli/app.ts - Commander program setup, global flags/options, help wiring
• src/cli/registry.ts - Registers all command groups
• src/cli/commands/** - CLI command definitions and option parsing
• src/commands/** - Command business logic and GraphQL operations
• src/commands/shared.ts - Shared command helpers (requireToken, output helpers, workspace context)
• src/config.ts - Global/local config loading, validation, merge precedence, auth resolution
• src/auth.ts - Login/logout/status token flows
• src/api.ts - GraphQL transport/error handling
• schemas/config.schema.json - Config schema used in persisted config

Config model

Global config path:

• ~/.config/linear-cli/config.json

Local config discovery (walk up from cwd):

• .agents/linear.json
• .linear.json
• .linear/config.json

Workspace/profile + local resolution is implemented in src/config.ts (loadMergedConfig, resolveAuth, workspace resolution helpers).

Command conventions

• Use Commander command modules under src/cli/commands/<resource>/...
• Keep API/query logic in src/commands/<resource>.ts
• Most read commands support --json; default output is table
• Use CliError for actionable user errors
• Use strict(...) helper for command definition consistency

Defaults and scope behavior

Global setters:

• linear config workspace <name>
• linear config team <key>

Local setters:

• same commands with --local
• linear auth use <name> --local sets project-local workspace

Release + versioning

• Use Changesets for release notes/version bumps
• Add a changeset for user-visible changes
• Keep README.md and CLI help text aligned with behavior

Maintenance checklist for command changes

1. Update command registration if adding/removing command files
2. Update README command examples/documentation
3. Add or update tests when behavior changes
4. Run bun run lint && bun run typecheck && bun run test
5. Add a changeset for user-visible changes