Skip to content

Commit 28efbcb

Browse files
schpetschpet
committed
update skill template with dense command reference overview
All subcommands are now shown one-per-line with all their flags, replacing the previous top-level-only command list. Universal flags (-h/--help and -w/--workspace) are omitted since they apply everywhere. Updates generate-docs.ts to extract flags from help text and recursively collect leaf subcommands for the dense format.
1 parent 91866c0 commit 28efbcb

4 files changed

Lines changed: 143 additions & 38 deletions

File tree

‎skills/linear-cli/SKILL.md‎

Lines changed: 71 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -57,23 +57,79 @@ linear issue comment add ENG-123 --body-file /tmp/comment.md
5757

5858
**Only use inline flags** (`--description`, `--body`) for simple, single-line content.
5959

60-
## Available Commands
60+
## Command Reference
61+
62+
All subcommands with flags (omitting universal `-h/--help` and `-w/--workspace`):
6163

6264
```
63-
linear auth # Manage Linear authentication
64-
linear issue # Manage Linear issues
65-
linear team # Manage Linear teams
66-
linear project # Manage Linear projects
67-
linear project-update # Manage project status updates
68-
linear cycle # Manage Linear team cycles
69-
linear milestone # Manage Linear project milestones
70-
linear initiative # Manage Linear initiatives
71-
linear initiative-update # Manage initiative status updates (timeline posts)
72-
linear label # Manage Linear issue labels
73-
linear document # Manage Linear documents
74-
linear config # Interactively generate .linear.toml configuration
75-
linear schema # Print the GraphQL schema to stdout
76-
linear api # Make a raw GraphQL API request
65+
linear auth login [--key <key>] # Add a workspace credential
66+
linear auth logout [--force] # Remove a workspace credential
67+
linear auth list # List configured workspaces
68+
linear auth default # Set the default workspace
69+
linear auth token # Print the configured API token
70+
linear auth whoami # Print information about the authenticated user
71+
linear issue id # Print the issue based on the current git branch
72+
linear issue list [--state <state>] [--all-states] [--assignee <assignee>] [--all-assignees] [--unassigned] [--sort <sort>] [--team <team>] [--project <project>] [--cycle <cycle>] [--limit <limit>] [--web] [--app] [--no-pager] # List your issues
73+
linear issue title # Print the issue title
74+
linear issue start [--all-assignees] [--unassigned] [--from-ref <fromRef>] [--branch <branch>] # Start working on an issue
75+
linear issue view [--web] [--app] [--no-comments] [--no-pager] [--json] [--no-download] # View issue details (default) or open in browser/app
76+
linear issue url # Print the issue URL
77+
linear issue describe [--references] # Print the issue title and Linear-issue trailer
78+
linear issue commits # Show all commits for a Linear issue (jj only)
79+
linear issue pull-request [--base <branch>] [--draft] [--title <title>] [--web] [--head <branch>] # Create a GitHub pull request with issue details
80+
linear issue delete [--confirm] [--bulk <ids...>] [--bulk-file <file>] [--bulk-stdin] # Delete an issue
81+
linear issue create [--start] [--assignee <assignee>] [--due-date <dueDate>] [--parent <parent>] [--priority <priority>] [--estimate <estimate>] [--description <description>] [--description-file <path>] [--label <label>] [--team <team>] [--project <project>] [--state <state>] [--milestone <milestone>] [--cycle <cycle>] [--no-use-default-template] [--no-interactive] [--title <title>] # Create a linear issue
82+
linear issue update [--assignee <assignee>] [--due-date <dueDate>] [--parent <parent>] [--priority <priority>] [--estimate <estimate>] [--description <description>] [--description-file <path>] [--label <label>] [--team <team>] [--project <project>] [--state <state>] [--milestone <milestone>] [--cycle <cycle>] [--title <title>] # Update a linear issue
83+
linear issue comment add [--body <text>] [--body-file <path>] [--parent <id>] [--attach <filepath>] # Add a comment to an issue or reply to a comment
84+
linear issue comment delete # Delete a comment
85+
linear issue comment update [--body <text>] [--body-file <path>] # Update an existing comment
86+
linear issue comment list [--json] # List comments for an issue
87+
linear issue attach [--title <title>] [--comment <body>] # Attach a file to an issue
88+
linear issue relation add # Add a relation between two issues
89+
linear issue relation delete # Delete a relation between two issues
90+
linear issue relation list # List relations for an issue
91+
linear team create [--name <name>] [--description <description>] [--key <key>] [--private] [--no-interactive] # Create a linear team
92+
linear team delete [--move-issues <targetTeam>] [--force] # Delete a Linear team
93+
linear team list [--web] [--app] # List teams
94+
linear team id # Print the configured team id
95+
linear team autolinks # Configure GitHub repository autolinks for Linear issues with this team prefix
96+
linear team members [--all] # List team members
97+
linear project list [--team <team>] [--all-teams] [--status <status>] [--web] [--app] [--json] # List projects
98+
linear project view [--web] [--app] # View project details
99+
linear project create [--name <name>] [--description <description>] [--team <team>] [--lead <lead>] [--status <status>] [--start-date <startDate>] [--target-date <targetDate>] [--initiative <initiative>] [--interactive] [--json] # Create a new Linear project
100+
linear project update [--name <name>] [--description <description>] [--status <status>] [--lead <lead>] [--start-date <startDate>] [--target-date <targetDate>] [--team <team>] # Update a Linear project
101+
linear project delete [--force] # Delete (trash) a Linear project
102+
linear project-update create [--body <body>] [--body-file <path>] [--health <health>] [--interactive] # Create a new status update for a project
103+
linear project-update list [--json] [--limit <limit>] # List status updates for a project
104+
linear cycle list [--team <team>] # List cycles for a team
105+
linear cycle view [--team <team>] # View cycle details
106+
linear milestone list [--project <projectId>] # List milestones for a project
107+
linear milestone view # View milestone details
108+
linear milestone create [--project <projectId>] [--name <name>] [--description <description>] [--target-date <date>] # Create a new project milestone
109+
linear milestone update [--name <name>] [--description <description>] [--target-date <date>] [--sort-order <value>] [--project <projectId>] # Update an existing project milestone
110+
linear milestone delete [--force] # Delete a project milestone
111+
linear initiative list [--status <status>] [--all-statuses] [--owner <owner>] [--web] [--app] [--json] [--archived] # List initiatives
112+
linear initiative view [--web] [--app] [--json] # View initiative details
113+
linear initiative create [--name <name>] [--description <description>] [--status <status>] [--owner <owner>] [--target-date <targetDate>] [--color <color>] [--icon <icon>] [--interactive] # Create a new Linear initiative
114+
linear initiative archive [--force] [--bulk <ids...>] [--bulk-file <file>] [--bulk-stdin] # Archive a Linear initiative
115+
linear initiative update [--name <name>] [--description <description>] [--status <status>] [--owner <owner>] [--target-date <targetDate>] [--color <color>] [--icon <icon>] [--interactive] # Update a Linear initiative
116+
linear initiative unarchive [--force] # Unarchive a Linear initiative
117+
linear initiative delete [--force] [--bulk <ids...>] [--bulk-file <file>] [--bulk-stdin] # Permanently delete a Linear initiative
118+
linear initiative add-project [--sort-order <sortOrder>] # Link a project to an initiative
119+
linear initiative remove-project [--force] # Unlink a project from an initiative
120+
linear initiative-update create [--body <body>] [--body-file <path>] [--health <health>] [--interactive] # Create a new status update for an initiative
121+
linear initiative-update list [--json] [--limit <limit>] # List status updates for an initiative
122+
linear label list [--team <teamKey>] [--all] [--json] # List issue labels
123+
linear label create [--name <name>] [--color <color>] [--description <description>] [--team <teamKey>] [--interactive] # Create a new issue label
124+
linear label delete [--team <teamKey>] [--force] # Delete an issue label
125+
linear document list [--project <project>] [--issue <issue>] [--json] [--limit <limit>] # List documents
126+
linear document view [--raw] [--web] [--json] # View a document's content
127+
linear document create [--title <title>] [--content <content>] [--content-file <path>] [--project <project>] [--issue <issue>] [--icon <icon>] [--interactive] # Create a new document
128+
linear document update [--title <title>] [--content <content>] [--content-file <path>] [--icon <icon>] [--edit] # Update an existing document
129+
linear document delete [--yes] [--bulk <ids...>] [--bulk-file <file>] [--bulk-stdin] # Delete a document (moves to trash)
130+
linear config # Interactively generate .linear.toml configuration
131+
linear schema [--json] [--output <file>] # Print the GraphQL schema to stdout
132+
linear api [--variable <variable>] [--variables-json <json>] [--paginate] [--silent] # Make a raw GraphQL API request
77133
```
78134

79135
## Reference Documentation

‎skills/linear-cli/SKILL.template.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,9 @@ linear issue comment add ENG-123 --body-file /tmp/comment.md
5757

5858
**Only use inline flags** (`--description`, `--body`) for simple, single-line content.
5959

60-
## Available Commands
60+
## Command Reference
61+
62+
All subcommands with flags (omitting universal `-h/--help` and `-w/--workspace`):
6163

6264
{{COMMANDS}}
6365

‎skills/linear-cli/references/issue.md‎

Lines changed: 16 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -67,23 +67,22 @@ Description:
6767
6868
Options:
6969
70-
-h, --help - Show this help.
71-
-w, --workspace <slug> - Target workspace (uses credentials)
72-
-s, --state <state> - Filter by issue state (can be repeated for multiple states) (Default: [ "unstarted" ], Values: "triage", "backlog",
73-
"unstarted", "started", "completed", "canceled")
74-
--all-states - Show issues from all states
75-
--assignee <assignee> - Filter by assignee (username)
76-
-A, --all-assignees - Show issues for all assignees
77-
-U, --unassigned - Show only unassigned issues
78-
--sort <sort> - Sort order (can also be set via LINEAR_ISSUE_SORT) (Values: "manual", "priority")
79-
--team <team> - Team to list issues for (if not your default team)
80-
--project <project> - Filter by project name
81-
--cycle <cycle> - Filter by cycle name, number, or 'active'
82-
--milestone <milestone> - Filter by project milestone name (requires --project)
83-
--limit <limit> - Maximum number of issues to fetch (default: 50, use 0 for unlimited) (Default: 50)
84-
-w, --web - Open in web browser
85-
-a, --app - Open in Linear.app
86-
--no-pager - Disable automatic paging for long output
70+
-h, --help - Show this help.
71+
-w, --workspace <slug> - Target workspace (uses credentials)
72+
-s, --state <state> - Filter by issue state (can be repeated for multiple states) (Default: [ "unstarted" ], Values: "triage", "backlog",
73+
"unstarted", "started", "completed", "canceled")
74+
--all-states - Show issues from all states
75+
--assignee <assignee> - Filter by assignee (username)
76+
-A, --all-assignees - Show issues for all assignees
77+
-U, --unassigned - Show only unassigned issues
78+
--sort <sort> - Sort order (can also be set via LINEAR_ISSUE_SORT) (Values: "manual", "priority")
79+
--team <team> - Team to list issues for (if not your default team)
80+
--project <project> - Filter by project name
81+
--cycle <cycle> - Filter by cycle name, number, or 'active'
82+
--limit <limit> - Maximum number of issues to fetch (default: 50, use 0 for unlimited) (Default: 50)
83+
-w, --web - Open in web browser
84+
-a, --app - Open in Linear.app
85+
--no-pager - Disable automatic paging for long output
8786
```
8887

8988
### title

‎skills/linear-cli/scripts/generate-docs.ts‎

Lines changed: 53 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -291,16 +291,64 @@ function generateIndex(commands: CommandInfo[]): string {
291291
return lines.join("\n") + "\n"
292292
}
293293

294+
function extractCompactFlags(helpText: string): string {
295+
const flagParts: string[] = []
296+
const lines = helpText.split("\n")
297+
let inOptions = false
298+
299+
for (const line of lines) {
300+
if (/^Options:/.test(line)) {
301+
inOptions = true
302+
continue
303+
}
304+
if (inOptions) {
305+
if (/^(Commands:|Examples:|Arguments:)/.test(line)) break
306+
if (!line.match(/^ {2}-/)) continue
307+
// Match: "-X, --long-name" or "--long-name" or "-X" optionally followed by <arg>
308+
const m = line.match(
309+
/^ {2,}(-[a-zA-Z](?:,\s+--[-a-zA-Z0-9]+)*|--[-a-zA-Z0-9]+)(?:\s+<([^>]+)>)?/,
310+
)
311+
if (!m) continue
312+
const flagStr = m[1].trim()
313+
const argStr = m[2]
314+
// Skip universal flags: -h/--help and --workspace
315+
if (flagStr.includes("--help")) continue
316+
if (flagStr.includes("--workspace")) continue
317+
// Prefer long form for readability
318+
const longMatch = flagStr.match(/--[-a-zA-Z0-9]+/)
319+
const primaryFlag = longMatch
320+
? longMatch[0]
321+
: flagStr.split(",")[0].trim()
322+
const part = argStr ? `${primaryFlag} <${argStr}>` : primaryFlag
323+
flagParts.push(`[${part}]`)
324+
}
325+
}
326+
327+
return flagParts.join(" ")
328+
}
329+
330+
function getAllLeafCommands(
331+
cmd: CommandInfo,
332+
): { name: string; description: string; help: string }[] {
333+
if (cmd.subcommands.length === 0) {
334+
return [{ name: cmd.name, description: cmd.description, help: cmd.help }]
335+
}
336+
return cmd.subcommands.flatMap(getAllLeafCommands)
337+
}
338+
294339
function generateCommandsSection(commands: CommandInfo[]): string {
295340
const lines: string[] = []
296341
lines.push("```")
297342

298-
// Find max command name length for alignment
299-
const maxLen = Math.max(...commands.map((c) => c.name.length))
300-
301343
for (const cmd of commands) {
302-
const padding = " ".repeat(maxLen - cmd.name.length + 2)
303-
lines.push(`linear ${cmd.name}${padding}# ${cmd.description}`)
344+
const leafCmds = getAllLeafCommands(cmd)
345+
for (const leaf of leafCmds) {
346+
const flags = extractCompactFlags(leaf.help)
347+
const cmdStr = flags
348+
? `linear ${leaf.name} ${flags}`
349+
: `linear ${leaf.name}`
350+
lines.push(`${cmdStr} # ${leaf.description}`)
351+
}
304352
}
305353

306354
lines.push("```")

0 commit comments

Comments
 (0)