An agent-native Linear runtime for the current v3 execution model, with stable JSON contracts, startup discovery, dry-run previews, timeout-aware write semantics, source-adjacent intake, and git/jj workflow integration.
When using this CLI from an agent runtime, prefer this order:
linear capabilities; use --compat v1 only when an older consumer still expects the trimmed legacy shape--json--dry-run --json when availableoperation, receipt, and error.detailserror.details instead of parsing styled terminal textPrompt-driven human/debug flows are secondary and explicit. When a command supports prompts or editor entry, pass --profile human-debug --interactive; otherwise missing required inputs fail fast.
Agent-safe execution semantics are now the default runtime behavior. --text and --profile human-debug are the explicit human/debug escape hatches for maintainers, and --profile agent-safe remains accepted for compatibility with older automation.
When upstream tooling hands the runtime a normalized Slack, ticket, or similar source envelope, prefer --context-file, add --apply-triage if that envelope already contains deterministic team/state/label hints, and choose --autonomy-policy explicitly when the wrapper needs suggest-only or preview-required staging.
Recommended supporting docs:
The linear command must be available on PATH. To check:
linear --version
If not installed, follow the instructions at:\
https://github.com/kyaukyuai/linear-cli?tab=readme-ov-file#install
When working with issue descriptions or comment bodies that contain markdown, prefer file-based flags for existing files and stdin for generated pipeline content:
--description-file for issue create and issue update commands when the content already exists on disk--body-file for comment add and comment update commands when the content already exists on diskcat description.md | linear issue create --title "My Issue" --team ENGWhy avoid large inline flags:
\n sequences from appearing in markdownExample workflow:
# 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 pipe generated markdown directly
cat /tmp/description.md | linear issue create --title "My Issue" --team ENG
# 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.
linear auth # Manage Linear authentication
linear issue # Manage Linear issues
linear team # Manage Linear teams
linear project # Manage Linear projects
linear project-update # Manage project status updates
linear cycle # Manage Linear team cycles
linear milestone # Manage Linear project milestones
linear initiative # Manage Linear initiatives
linear initiative-update # Manage initiative status updates (timeline posts)
linear label # Manage Linear issue labels
linear document # Manage Linear documents
linear notification # Manage Linear notifications
linear webhook # Manage Linear webhooks
linear workflow-state # Manage Linear workflow states
linear user # Manage Linear users
linear project-label # Manage Linear project labels
linear config # Interactively generate .linear.toml configuration
linear schema # Print the GraphQL schema to stdout
linear api # Make a raw GraphQL API request
linear capabilities # Describe the agent-facing command surface
linear resolve # Resolve references without mutating Linear
For curated examples of organization features (initiatives, labels, projects, bulk operations), see organization-features.
To see available subcommands and flags, run --help on any command:
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.
For machine-readable discovery, prefer:
linear capabilities
linear capabilities --compat v1
Prefer the CLI for all supported operations. The api command should only be used as a fallback for queries not covered by the CLI.
Write the schema to a tempfile, then search it:
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"
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.
# 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'
For cases where you need full HTTP control, use linear auth token:
curl -s -X POST https://api.linear.app/graphql \
-H "Content-Type: application/json" \
-H "Authorization: $(linear auth token)" \
-d '{"query": "{ viewer { id } }"}'
共 4 个版本