Shortcut CLI Skill
Manage Shortcut stories, epics, objectives, iterations, docs, labels, teams, and more via the short CLI tool.
Instructions
When invoked with /shortcut $ARGUMENTS:
1. Check Prerequisites
Verify the short CLI is installed and authenticated:
which short && short --version
- If not found: Guide user through installation (see Prerequisites), then STOP
- If found but version < 5.0.0: Warn user to upgrade (
brew upgrade shortcut-cli or npm update -g @shortcut-cli/shortcut-cli)
- If found and >= 5.0.0: Continue to step 2
2. Parse $ARGUMENTS
Route based on argument pattern (in priority order):
| Pattern |
Action |
| No arguments |
Show help menu with available commands |
URL containing /story/<id> |
Extract numeric ID, run short story <id> |
URL containing /epic/<id> |
Extract numeric ID, run short epic view <id> |
search <text> |
Run short search -t "<text>" |
my |
Run short search -o me |
list |
Run short search (no filters) |
create |
Ask for entity type + details, run create command (see references/commands.md ## Create) |
objectives [...] |
Route to objectives commands (see references/commands.md ## Objectives) |
teams [...] |
Route to teams commands (see references/commands.md ## Teams) |
iterations [...] |
Route to iterations commands (see references/commands.md ## Iterations) |
docs [...] |
Route to docs commands (see references/commands.md ## Docs) |
labels [...] |
Route to labels commands (see references/commands.md ## Labels) |
workflows |
Run short workflows |
projects |
Run short projects |
story <id> <subcommand> |
Route to story subcommands: history, comments, tasks, relations (see references/commands.md ## Stories) |
| Numeric value |
Treat as story ID, run short story <id> |
Create supports stories, epics, iterations, objectives, docs, and labels — see references/commands.md for each.
Always quote user-provided strings and escape double quotes in input.
3. Present Results
- Story/epic details: Show ID, title, state, owner, description, URL
- Search results: Numbered list with ID, title, state
- Creation: Success message with new item URL
- Lists (teams, labels, iterations, etc.): Clean formatted table
Suggest relevant follow-up actions after presenting results.
4. Handle Errors
| Error |
Detection |
Response |
| CLI not found |
which short empty |
Show installation instructions, do NOT auto-install |
| Auth failure |
"unauthorized" or "invalid token" |
Guide user to run short install |
| Not found |
"not found" in output |
Confirm ID, suggest search |
| Network error |
Timeout or connection error |
Ask user to check connection |
| Node.js version |
ESM/import errors or "unsupported engine" |
User needs Node.js >= 20.19.0 |
Prerequisites
- Node.js >= 20.19.0 (required by shortcut-cli v5+)
# Install via Homebrew (preferred)
brew install shortcut-cli
# Or via npm (fallback)
npm install -g @shortcut-cli/shortcut-cli
# Verify version (expect >= 5.0.0)
short --version
# Authenticate
short install
# Or: export SHORTCUT_API_TOKEN="your-api-token"
Reference
| Task |
Reference |
| CLI commands (stories, epics, objectives, iterations, docs, labels, teams, search, create, API) |
references/commands.md — use ## Section headers to find specific command families |
| Shortcut API spec |
references/shortcut.swagger.json |
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: hefgi-shortcut-cli-skill-shortcut3description: Shortcut CLI Skill4---56# Shortcut CLI Skill78Manage Shortcut stories, epics, objectives, iterations, docs, labels, teams, and more via the `short` CLI tool.910## Instructions1112When invoked with `/shortcut $ARGUMENTS`:1314### 1. Check Prerequisites1516Verify the `short` CLI is installed and authenticated:1718```bash19which short && short --version20```2122- If not found: Guide user through installation (see Prerequisites), then STOP23- If found but version < 5.0.0: Warn user to upgrade (`brew upgrade shortcut-cli` or `npm update -g @shortcut-cli/shortcut-cli`)24- If found and >= 5.0.0: Continue to step 22526### 2. Parse $ARGUMENTS2728Route based on argument pattern (in priority order):2930| Pattern | Action |31|---------|--------|32| No arguments | Show help menu with available commands |33| URL containing `/story/<id>` | Extract numeric ID, run `short story <id>` |34| URL containing `/epic/<id>` | Extract numeric ID, run `short epic view <id>` |35| `search <text>` | Run `short search -t "<text>"` |36| `my` | Run `short search -o me` |37| `list` | Run `short search` (no filters) |38| `create` | Ask for entity type + details, run create command (see `references/commands.md ## Create`) |39| `objectives [...]` | Route to objectives commands (see `references/commands.md ## Objectives`) |40| `teams [...]` | Route to teams commands (see `references/commands.md ## Teams`) |41| `iterations [...]` | Route to iterations commands (see `references/commands.md ## Iterations`) |42| `docs [...]` | Route to docs commands (see `references/commands.md ## Docs`) |43| `labels [...]` | Route to labels commands (see `references/commands.md ## Labels`) |44| `workflows` | Run `short workflows` |45| `projects` | Run `short projects` |46| `story <id> <subcommand>` | Route to story subcommands: history, comments, tasks, relations (see `references/commands.md ## Stories`) |47| Numeric value | Treat as story ID, run `short story <id>` |4849Create supports stories, epics, iterations, objectives, docs, and labels — see `references/commands.md` for each.5051Always quote user-provided strings and escape double quotes in input.5253### 3. Present Results5455- Story/epic details: Show ID, title, state, owner, description, URL56- Search results: Numbered list with ID, title, state57- Creation: Success message with new item URL58- Lists (teams, labels, iterations, etc.): Clean formatted table5960Suggest relevant follow-up actions after presenting results.6162### 4. Handle Errors6364| Error | Detection | Response |65|-------|-----------|----------|66| CLI not found | `which short` empty | Show installation instructions, do NOT auto-install |67| Auth failure | "unauthorized" or "invalid token" | Guide user to run `short install` |68| Not found | "not found" in output | Confirm ID, suggest search |69| Network error | Timeout or connection error | Ask user to check connection |70| Node.js version | ESM/import errors or "unsupported engine" | User needs Node.js >= 20.19.0 |7172## Prerequisites7374- **Node.js >= 20.19.0** (required by shortcut-cli v5+)7576```bash77# Install via Homebrew (preferred)78brew install shortcut-cli7980# Or via npm (fallback)81npm install -g @shortcut-cli/shortcut-cli8283# Verify version (expect >= 5.0.0)84short --version8586# Authenticate87short install88# Or: export SHORTCUT_API_TOKEN="your-api-token"89```9091## Reference9293| Task | Reference |94|------|-----------|95| CLI commands (stories, epics, objectives, iterations, docs, labels, teams, search, create, API) | `references/commands.md` — use `## Section` headers to find specific command families |96| Shortcut API spec | `references/shortcut.swagger.json` |9798---99> Converted and distributed by [TomeVault](https://tomevault.io/claim/hefgi) — claim your Tome and manage your conversions.100<!-- tomevault:4.0:skill_md:2026-04-11 -->
tomevault-io