Shortcut CLI

A command-line interface for interacting with the Shortcut (formerly Clubhouse) REST API v3.

Features

• 🚀 OpenAPI-Driven: Automatically generated from Shortcut’s OpenAPI specification
• 🔧 Full CRUD Support: Create, read, update, and delete Stories, Epics, Iterations, and more
• 🎯 Generic Invoke: Call any API endpoint directly with operation-id and JSON parameters
• 📚 Built-in Documentation: Explore API endpoints and schemas without leaving the terminal
• 🎨 Pretty Output: Colorful, formatted output for better readability
• ⚡ High Performance: Async HTTP with http-kit

Installation

Prerequisites

• Clojure 1.12+
• Java 11+
• Babashka (for build tasks)

Build from Source

# Clone the repository
git clone https://github.com/your-username/shortcut-cli.git
cd shortcut-cli

# Build the uberjar
bb build-jar

# Run the CLI
java -jar target/shortcut-cli.jar --help

Configuration

Set your Shortcut API token as an environment variable:

export SHORTCUT_TOKEN="your-api-token-here"

You can get your API token from Shortcut Settings > API Tokens.

Logging

The CLI uses μ/log for structured event logging. To enable logging:

export MULOG_ENABLED=true

This will output structured JSON logs to the console showing API requests, errors, and more. See LOGGING.md for detailed configuration options including file output, Elasticsearch, CloudWatch, and Kafka publishers.

Usage

General Command Structure

shortcut-cli [command] [subcommand] [options]

Documentation Commands

List All API Endpoints

shortcut-cli doc endpoint

Shows a table of all available API operations with their URLs, methods, and operation IDs.

View Specific Endpoint Details

shortcut-cli doc endpoint getStory

Shows detailed information about a specific API operation.

List All API Schemas

shortcut-cli doc schema

Shows all available data schemas in the API.

View Specific Schema

shortcut-cli doc schema Story

Shows the structure and fields of a specific schema.

Generic API Invocation

Call any API endpoint directly:

shortcut-cli invoke --operation getStory --params '{"story-public-id": 12345}'

Short form:

shortcut-cli invoke -o getCurrentMemberInfo -p '{}'

Story Management

Create a Story

shortcut-cli story add \
  --name "Implement user authentication" \
  --description "Add OAuth2 support" \
  --story-type feature \
  --project-id 123 \
  --epic-id 456 \
  --estimate 5

View a Story

shortcut-cli story view 12345

List All Stories

shortcut-cli story list

Delete a Story

shortcut-cli story delete 12345

Epic Management

Create an Epic

shortcut-cli epic create \
  --name "Q4 Authentication Epic" \
  --description "Complete authentication overhaul" \
  --state "in progress" \
  --milestone-id 789

Update an Epic

shortcut-cli epic update \
  --id 456 \
  --name "Updated Epic Name" \
  --state "done"

View an Epic

shortcut-cli epic view 456

List All Epics

shortcut-cli epic list

Delete an Epic

shortcut-cli epic delete 456

List Stories in an Epic

shortcut-cli epic stories 456

Iteration Management

List All Iterations

shortcut-cli iteration list

View an Iteration

shortcut-cli iteration view 789

List Stories in an Iteration

shortcut-cli iteration stories 789

Delete an Iteration

shortcut-cli iteration delete 789

Project Management

List All Projects

shortcut-cli project list

View a Project

shortcut-cli project view 123

List Stories in a Project

shortcut-cli project stories 123

Delete a Project

shortcut-cli project delete 123

Label Management

List All Labels

shortcut-cli label list

View a Label

shortcut-cli label view 999

List Stories with a Label

shortcut-cli label stories 999

List Epics with a Label

shortcut-cli label epics 999

Member Management

List All Members

shortcut-cli member list

View a Member

shortcut-cli member view "uuid-here"

Get Current Authenticated Member

shortcut-cli member me

Workflow Management

List All Workflows

shortcut-cli workflow list

View a Workflow

shortcut-cli workflow view 111

Milestone Management

List All Milestones

shortcut-cli milestone list

View a Milestone

shortcut-cli milestone view 222

List Epics in a Milestone

shortcut-cli milestone epics 222

Development

Running Tests

bb test

Linting

bb lint

### Code Formatting

# Check formatting
bb fmt-check

# Auto-format code
bb fmt

Running in Development

# Start an nREPL server
bb nrepl

# Run the CLI directly
bb main --help
bb main story list

Building

# Clean build artifacts
bb clean

# Build uberjar
bb build-jar

# Full CI pipeline (clean, lint, test)
bb ci

Project Structure

shortcut-cli/
├── src/
│   └── shortcut_cli/
│       └── main.clj          # Main CLI implementation
├── resources/
│   ├── cli.yml              # CLI configuration
│   └── shortcut.openapi.json # Shortcut OpenAPI spec
├── test/                    # Test files
├── deps.edn                # Dependencies
├── bb.edn                  # Babashka tasks
└── readme.org              # This file

Architecture

The CLI is built using:

• cli-matic: Declarative CLI framework
• http-kit: Async HTTP client
• jsonista: Fast JSON parsing
• clj-yaml: YAML parsing for OpenAPI spec
• puget: Pretty printing
• bling: Terminal colors and formatting

The entire CLI is dynamically generated from Shortcut’s OpenAPI specification, ensuring it stays up-to-date with the API.

Error Handling

The CLI provides helpful error messages:

• 401 Unauthorized: Check your SHORTCUT_TOKEN
• 404 Not Found: Resource doesn’t exist
• 422 Unprocessable Entity: Invalid parameters
• 429 Rate Limit Exceeded: Too many requests

All errors include the full API response for debugging.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting: bb ci
5. Submit a pull request

Resources

• Shortcut Homepage
• Shortcut API Documentation
• Shortcut OpenAPI Specification

License

[Your chosen license here]

Changelog

v0.0.1 (2024-11-11)

• Initial release
• OpenAPI-driven command generation
• Full CRUD support for Stories, Epics, Iterations, Projects
• Generic API invocation
• Built-in API documentation explorer
• Pretty formatted output