Command-line helper that lets agents create, edit, and query Linear issues through inline GraphQL payloads sent via curl.

• bash 5+
• curl 7.58+
• jq 1.6+
• gh (for contributing)

1. Clone the repo and create a feature branch (GitHub Flow only).
2. Export LINEAR_API_KEY (create one in Linear). Optionally set LINEAR_TEAM_ID to your default team and LINEAR_API_ENDPOINT (defaults to https://api.linear.app/graphql).
3. Verify deps with bash --version, curl --version, and jq --version.

1. In Linear, go to Settings › Account › API keys, create a personal key with access to the workspace/teams you need, and copy the value (it should look like lin_api_...).
2. Store it securely, for example:

   mkdir -p ~/.config/linear_tool
   cat <<'EOF' > ~/.config/linear_tool/env
   export LINEAR_API_KEY=lin_api_xxxxxxxxx
   # Optional defaults
   export LINEAR_TEAM_ID=team_123ABC
   EOF
   chmod 600 ~/.config/linear_tool/env

   Then source it from your shell config: [[ -f ~/.config/linear_tool/env ]] && source ~/.config/linear_tool/env.
3. Confirm the key works before running the CLI:

   curl -sS https://api.linear.app/graphql \
     -H "Authorization: ${LINEAR_API_KEY}" \
     -H "Content-Type: application/json" \
     --data '{"query":"{ viewer { id email } }"}'

   A valid key returns a data.viewer object. If you see {"message":"Unauthorized"}, regenerate the key or ensure it is sourced in your shell.

The script enforces TDD-friendly error handling and requires LINEAR_API_KEY.

./linear.sh create [--team TEAM_ID] --title "Ship CLI" --description "Context" [--state STATE_ID] [--assignee USER_ID]
./linear.sh edit ISSUE_ID [--title "New title"] [--description "Updated"] [--state STATE_ID] [--assignee USER_ID]
./linear.sh query [--team TEAM_ID] [--state "In Progress"] [--assignee USER_ID] [--limit 20]

Successful create/edit commands print concise summaries plus the issue URL (create). Query prints rows formatted as IDENTIFIER | State | Title or No issues found when empty. The CLI exits non-zero if Linear returns HTTP or GraphQL errors (for example, an unauthorized API key), so agents immediately know when credentials or inputs are wrong.

When LINEAR_TEAM_ID is set, the CLI automatically applies it to create (required) and query commands so you can skip --team. Pass --team explicitly to override the environment default for a single call.

Always add or update a failing test before implementing a feature. Run the current suite with:

tests/run_tests.sh

The tests mock curl, capture outgoing GraphQL payloads, and verify summaries, so they double as documentation of the API contract.

• Follow TDD: write or update a failing test before implementing CLI behavior.
• Keep README and Todos.md accurate; log unimplemented requests as unchecked tasks.
• Never commit straight to main; open PRs from feature branches.