A fast, ergonomic command-line interface for the Shortcut project management API.

• Full API coverage — stories, epics, iterations, labels, objectives, categories, groups, projects, documents, custom fields, and more
• Interactive wizards — login prompts for your token; story/epic creation walks you through required fields
• Git integration — generate branch names from stories and create commits prefixed with [sc-ID]
• Shortcut Template Language (STL) — declare stories, epics, and tasks in YAML and apply them in one command
• Flexible output — --json, --toon, --quiet, --format "{id} {name}", --dry-run, and color control
• Local caching — workspace members, epic states, and workflow data are cached and refreshed on miss
• Per-project config — each project directory gets its own token and cache under ~/.shortcut/
• Secure token storage — API tokens are written with 0600 permissions

Dependency updates are managed by Renovate using .github/renovate.json5:

• Weekly update window (early Monday morning) to keep noise low
• Grouped non-major updates for Cargo crates and GitHub Actions
• Automatic merge for safe patch/minor updates
• Major updates require manual dashboard approval
• Weekly lockfile maintenance and separate security alert handling

brew tap MrFrydae/tap
brew install shortcut

shortcut init                  # Set up config directory for the current project
shortcut login                 # Authenticate with your Shortcut API token
shortcut story list            # List stories in your workspace
shortcut story create          # Create a story (interactive)
shortcut search stories "bug"  # Search across stories

Run shortcut <command> --help for full flag documentation.

story branch generates a branch name from a story's type and title. story commit prefixes your message with the Shortcut story ID.

# Generate a branch name from story 12345
shortcut story branch --id 12345
# feature/sc-12345/add-user-authentication

# Create and checkout the branch
shortcut story branch --id 12345 --checkout

# Override the type prefix
shortcut story branch --id 12345 --prefix hotfix

# Commit with auto-detected story ID from branch name
shortcut story commit -m "fix login redirect"
# [sc-12345] fix login redirect

# Explicit story ID
shortcut story commit --id 12345 -m "fix login redirect"

# Pass extra args to git commit
shortcut story commit -m "fix login redirect" -- --no-verify

Every command supports these global flags:

Output mode precedence: --json > --toon > --quiet > --format > Human (default).

shortcut story list --json
shortcut story list --toon
shortcut story list --quiet
shortcut story list --format "{id} - {name} ({type})"
shortcut story create --dry-run

For CI/non-interactive environments, you can authenticate with:

export SHORTCUT_API_TOKEN="<your-token>"
shortcut story list

SHORTCUT_API_TOKEN takes precedence over a stored project token file.

Declare stories, epics, and related entities in a .shortcut.yml file and apply them in one command.

version: 1

meta:
  description: Sprint kickoff stories

vars:
  sprint_name: "Sprint 42"
  team_epic: "Backend Improvements"

operations:
  - action: create
    entity: epic
    alias: epic
    fields:
      name: "$var(team_epic)"

  - action: create
    entity: story
    alias: parent
    fields:
      epic_id: "$ref(epic)"
      name: "Design API schema for $var(sprint_name)"
      type: feature
      description: >
        Draft the OpenAPI spec for the new endpoints
        and get sign-off from the team before implementation.

  - action: create
    entity: story
    alias: tasks
    repeat:
      - name: "Implement endpoint scaffolding"
        type: feature
        tasks:
          - description: "Create route handlers"
          - description: "Add request validation"
      - name: "Write integration tests"
        type: chore
    fields:
      parent_story_id: "$ref(parent)"

shortcut template validate my-template.shortcut.yml   # Validate without executing
shortcut template run my-template.shortcut.yml         # Execute the template
shortcut template run my-template.shortcut.yml --dry-run  # Preview API calls
shortcut template sync my-template.shortcut.yml --confirm  # Reconcile template with prior state
shortcut template sync my-template.shortcut.yml --prune --confirm  # Also delete orphans from state

Features: variables ($var()), cross-operation references ($ref()), repeat blocks for batch creation, parent/child story relationships, inline tasks, block scalar descriptions, and configurable error handling (on_error: continue).

See STL_SPEC.md for the full specification.

~/.shortcut/
└── projects/
    └── <hash>/
        ├── token                       # API token (chmod 0600)
        └── cache/
            ├── epic_state_cache.json   # state name → ID mapping
            └── member_cache.json       # @mention → UUID mapping

# Bash
shortcut completions bash > ~/.local/share/bash-completion/completions/shortcut

# Zsh
shortcut completions zsh > ~/.zfunc/_shortcut

# Fish
shortcut completions fish > ~/.config/fish/completions/shortcut.fish

cargo build          # Build
cargo test           # Run tests
cargo fmt --check    # Check formatting
cargo clippy         # Lint

Use the release helper script to cut a new semver release with one command:

scripts/release.sh 0.0.12

What it does:

• Updates the package version in Cargo.toml
• Regenerates Cargo.lock and verifies it includes the new shortcut-cli version
• Runs cargo build --locked --release locally
• Commits Cargo.toml + Cargo.lock and pushes main
• Triggers CI on main; release runs only after CI succeeds
• Release workflow extracts v<version> from Cargo.toml, creates the tag, and publishes artifacts from the CI run
• Publishes detailed release notes listing all non-merge commits since the previous release tag

AGPL-3.0