Skip to content

AGENTS.md

Latest commit

 

History

History
57 lines (49 loc) · 3.82 KB

AGENTS.md

File metadata and controls

57 lines (49 loc) · 3.82 KB

Linear Integration

Use linear-cli for all Linear.app operations. Do not use Linear MCP tools.

Commands

  • linear-cli i list - List issues
  • linear-cli i list -t TEAM - List team's issues
  • linear-cli i create "Title" -t TEAM - Create issue
  • linear-cli i get LIN-123 - View issue details
  • linear-cli i get LIN-1 LIN-2 LIN-3 - Batch fetch multiple issues
  • linear-cli i get LIN-123 --output json - View as JSON
  • linear-cli i update LIN-123 -s Done - Update status
  • linear-cli i start LIN-123 --checkout - Start work (assign + branch)
  • linear-cli g pr LIN-123 - Create GitHub PR
  • linear-cli g pr LIN-123 --draft - Create draft PR
  • linear-cli s issues "query" - Search issues
  • linear-cli context - Get current issue from git branch
  • linear-cli update - Check for and install the latest CLI release
  • linear-cli cm list ISSUE_ID --output json - Get comments as JSON
  • linear-cli up fetch URL -f file.png - Download attachments

Agent-Friendly Flags

  • --output json - Machine-readable output
  • --compact - Compact JSON output (no pretty formatting)
  • --fields a,b,c - Limit JSON output to selected fields (supports dot paths)
  • --sort field - Sort JSON array output by field (default: identifier/id)
  • --order asc|desc - Sort order for JSON array output
  • --quiet or -q - Suppress decorative output
  • --id-only - Output only created/updated ID
  • --api-key KEY - Override API key for this invocation
  • --dry-run - Preview without executing (create)
  • -d - - Read description from stdin

Exit Codes

  • 0 = Success
  • 1 = General error
  • 2 = Not found
  • 3 = Auth error
  • 4 = Rate limited

Notes

  • Set LINEAR_CLI_OUTPUT=json to default all output to JSON
  • Errors with --output json return {"error": true, "message": "...", "code": N, "details": {...}, "retry_after": N}
  • linear-cli i create/update accept --data JSON input (use - for stdin)
  • linear-cli agent prints agent-focused capabilities and examples
  • linear-cli update --check reports current vs latest release without installing
  • JSON samples live in docs/json/
  • Use --help on any command for full options

Failure Modes

Pager leaves terminal in a bad state after a successful command

symptom evidence root cause wrong instinct corrected default behavior where the lesson belongs next
On macOS, a successful table-output command can leave the shell acting raw-ish until reset or stty sane. stty -a after the command may show pendin; piping through an external pager can avoid the symptom. Auto-pager cleanup depended on a guard Drop, but async_main called std::process::exit, which skips destructors entirely. The pager path also redirected stdout with dup2 without restoring the original fd on teardown. Tweaking LESS, PAGER, or termios flags first. When touching pager code, preserve a saved stdout fd, restore it before pager shutdown, and return an exit code to main instead of calling std::process::exit while cleanup guards are still in scope. Keep this note in AGENTS.md and add/keep a Unix regression test around stdout redirection in src/main.rs.
A published GitHub release exists, but cargo binstall or release-asset based installs cannot find binaries. gh release view shows a tag but zero assets; recent Release workflow runs fail immediately. The release workflow can be healthy in-repo but still never upload assets if the GitHub Actions account is locked externally, such as a billing lock. Debugging the packaging script first or assuming cargo-binstall metadata is wrong. Check the latest Release workflow run and GitHub account status before changing updater or packaging code; keep a Cargo install fallback in the CLI updater. Keep this note in AGENTS.md and re-verify release assets on the next patch release.