mirror of
https://github.com/prdlk/dotfiles.git
synced 2026-11-03 11:37:36 +00:00
Prad Nukala
6406208b35
- 16 cross-shell utilities converted to sh/bash chezmoi executables: ai c2p cp-appid extract_agents fab gdc gh-sonr-org-migrate ghg-clone ghn gho git-summary launch_omp_livediff_overlay lc-elir mdcp mdp pj (ghg-clone not named ghg: unrelated cargo binary owns that name) - cwd/history helpers stay per-shell: yy c cd clip-last + ghg/ghn/gho cd-wrappers in bash/functions/ and zsh/functions/, loaded by rc files - fish keeps only shell-state functions; converted ones now hit PATH - cp-appid ignore gating moved to .local/bin path - dot_agents/skills: 82 skills materialized from dotstate storage so dot_claude skill symlinks resolve on fresh bootstrap; dotstate profile/symlinks.json released .agents/skills .bashrc .zshrc
154 lines
4.8 KiB
Markdown
154 lines
4.8 KiB
Markdown
---
|
|
name: linear-cli
|
|
description: Manage Linear issues from the command line using the linear cli. This skill allows automating linear management.
|
|
allowed-tools: Bash(linear:*), Bash(curl:*)
|
|
---
|
|
|
|
# Linear CLI
|
|
|
|
A CLI to manage Linear issues from the command line, with git and jj integration.
|
|
|
|
## Prerequisites
|
|
|
|
The `linear` command must be available on PATH. To check:
|
|
|
|
```bash
|
|
linear --version
|
|
```
|
|
|
|
If not installed globally, you can run it without installing via npx:
|
|
|
|
```bash
|
|
npx @schpet/linear-cli --version
|
|
```
|
|
|
|
All subsequent commands can be prefixed with `npx @schpet/linear-cli` in place of `linear`. Otherwise, follow the install instructions at:\
|
|
https://github.com/schpet/linear-cli?tab=readme-ov-file#install
|
|
|
|
## Best Practices for Markdown Content
|
|
|
|
When working with issue descriptions or comment bodies that contain markdown, **always prefer using file-based flags** instead of passing content as command-line arguments:
|
|
|
|
- Use `--description-file` for `issue create` and `issue update` commands
|
|
- Use `--body-file` for `comment add` and `comment update` commands
|
|
|
|
**Why use file-based flags:**
|
|
|
|
- Ensures proper formatting in the Linear web UI
|
|
- Avoids shell escaping issues with newlines and special characters
|
|
- Prevents literal `\n` sequences from appearing in markdown
|
|
- Makes it easier to work with multi-line content
|
|
|
|
**Example workflow:**
|
|
|
|
```bash
|
|
# Write markdown to a temporary file
|
|
cat > /tmp/description.md <<'EOF'
|
|
## Summary
|
|
|
|
- First item
|
|
- Second item
|
|
|
|
## Details
|
|
|
|
This is a detailed description with proper formatting.
|
|
EOF
|
|
|
|
# Create issue using the file
|
|
linear issue create --title "My Issue" --description-file /tmp/description.md
|
|
|
|
# Or for comments
|
|
linear issue comment add ENG-123 --body-file /tmp/comment.md
|
|
```
|
|
|
|
**Only use inline flags** (`--description`, `--body`) for simple, single-line content.
|
|
|
|
## Available Commands
|
|
|
|
Compact command list, generated from `linear --help`:
|
|
|
|
```bash
|
|
{{COMMANDS}}
|
|
```
|
|
|
|
## Reference Documentation
|
|
|
|
{{REFERENCE_TOC}}
|
|
|
|
For curated examples of organization features (initiatives, labels, projects, bulk operations), see [organization-features](references/organization-features.md).
|
|
|
|
## Discovering Options
|
|
|
|
To see available subcommands and flags, run `--help` on any command:
|
|
|
|
```bash
|
|
linear --help
|
|
linear issue --help
|
|
linear issue list --help
|
|
linear issue create --help
|
|
```
|
|
|
|
Each command has detailed help output describing all available flags and options.
|
|
|
|
Some commands have required flags that aren't obvious. Notable examples:
|
|
|
|
- `issue list` requires a sort order — provide it via `--sort` (valid values: `manual`, `priority`), the `issue_sort` config option, or the `LINEAR_ISSUE_SORT` env var. Also requires `--team <key>` unless the team can be inferred from the directory — if unknown, run `linear team list` first.
|
|
- `--no-pager` is only supported on `issue list` — passing it to other commands like `project list` will error.
|
|
|
|
## Using the Linear GraphQL API Directly
|
|
|
|
**Prefer the CLI for all supported operations.** The `api` command should only be used as a fallback for queries not covered by the CLI.
|
|
|
|
### Check the schema for available types and fields
|
|
|
|
Write the schema to a tempfile, then search it:
|
|
|
|
```bash
|
|
linear schema -o "${TMPDIR:-/tmp}/linear-schema.graphql"
|
|
grep -i "cycle" "${TMPDIR:-/tmp}/linear-schema.graphql"
|
|
grep -A 30 "^type Issue " "${TMPDIR:-/tmp}/linear-schema.graphql"
|
|
```
|
|
|
|
### Make a GraphQL request
|
|
|
|
**Important:** GraphQL queries containing non-null type markers (e.g. `String` followed by an exclamation mark) must be passed via heredoc stdin to avoid escaping issues. Simple queries without those markers can be passed inline.
|
|
|
|
```bash
|
|
# Simple query (no type markers, so inline is fine)
|
|
linear api '{ viewer { id name email } }'
|
|
|
|
# Query with variables — use heredoc to avoid escaping issues
|
|
linear api --variable teamId=abc123 <<'GRAPHQL'
|
|
query($teamId: String!) { team(id: $teamId) { name } }
|
|
GRAPHQL
|
|
|
|
# Search issues by text
|
|
linear api --variable term=onboarding <<'GRAPHQL'
|
|
query($term: String!) { searchIssues(term: $term, first: 20) { nodes { identifier title state { name } } } }
|
|
GRAPHQL
|
|
|
|
# Numeric and boolean variables
|
|
linear api --variable first=5 <<'GRAPHQL'
|
|
query($first: Int!) { issues(first: $first) { nodes { title } } }
|
|
GRAPHQL
|
|
|
|
# Complex variables via JSON
|
|
linear api --variables-json '{"filter": {"state": {"name": {"eq": "In Progress"}}}}' <<'GRAPHQL'
|
|
query($filter: IssueFilter!) { issues(filter: $filter) { nodes { title } } }
|
|
GRAPHQL
|
|
|
|
# Pipe to jq for filtering
|
|
linear api '{ issues(first: 5) { nodes { identifier title } } }' | jq '.data.issues.nodes[].title'
|
|
```
|
|
|
|
### Advanced: Using curl directly
|
|
|
|
For cases where you need full HTTP control, use `linear auth token`:
|
|
|
|
```bash
|
|
curl -s -X POST https://api.linear.app/graphql \
|
|
-H "Content-Type: application/json" \
|
|
-H "Authorization: $(linear auth token)" \
|
|
-d '{"query": "{ viewer { id } }"}'
|
|
```
|