# Hefgi Shortcut CLI Skill Shortcut

> Shortcut CLI Skill

- Skill: `tomevault-io/hefgi-shortcut-cli-skill-shortcut` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/hefgi-shortcut-cli-skill-shortcut`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/hefgi-shortcut-cli-skill-shortcut/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/hefgi-shortcut-cli-skill-shortcut

---


# 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:

```bash
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+)

```bash
# 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](https://tomevault.io/claim/hefgi) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->