@shortcut-cli/shortcut-cli 3.8.1 → 5.0.0

package/README.md

@@ -4,7 +4,7 @@
 [![GitHub License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/shortcut-cli/shortcut-cli/blob/main/LICENSE)
 [![PRs welcome!](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)]()
 
-This is a community-driven command line interface for [Shortcut](https://shortcut.com), focused on the display and manipulation of stories. With this, you can run custom searches, save them as local workspaces, and recall those workspaces. You can also view full stories, update most attributes on a story, and create brand new stories quickly.
+This is a community-driven command line interface for [Shortcut](https://shortcut.com). It covers story search and updates, saved workspaces, and newer workspace resources such as teams, labels, epics, objectives, iterations, docs, projects, and raw API access.
 
 ## Table of Contents
 
@@ -15,7 +15,12 @@ This is a community-driven command line interface for [Shortcut](https://shortcu
     - [Story Creation](#story-creation)
     - [Workspace](#workspace)
     - [Members](#members)
+    - [Teams](#teams)
+    - [Labels](#labels)
+    - [Custom Fields](#custom-fields)
     - [Epics](#epics)
+    - [Objectives](#objectives)
+    - [Iterations](#iterations)
     - [Docs](#docs)
     - [Workflows](#workflows)
     - [Projects](#projects)
@@ -30,7 +35,7 @@ This is a community-driven command line interface for [Shortcut](https://shortcu
 Install via npm:
 
 ```sh
-npm install @shortcut-cli/shortcut-cli -g
+npm install -g @shortcut-cli/shortcut-cli
 short install
 ```
 
@@ -83,14 +88,25 @@ short story 3300
 
     install         install and configure API access
     search          search stories with optional query
+    find            [DEPRECATED] search stories with optional query
     members         list members
-    story           view or manipulate a story or stories
+    teams           list teams
+    team            view a team or list its stories
+    labels          list labels
+    label           view stories for a label
+    custom-fields   list custom fields
+    custom-field    view a custom field
+    story           view or manipulate stories
     create          create a story
     workflows       list workflows and their states
     epics           list epics and their states
+    iterations      list iterations
+    iteration       view, create, update, or delete an iteration
+    objectives      list objectives and their states
+    objective       view, create, or update objectives
     docs            list and search docs
     doc             view, create, update, or delete a doc
-    projects        list or search projects
+    projects        list projects and their states
     workspace       list stories matching saved workspace query
     api             make a request to the Shortcut API
     help [cmd]      display help for [cmd]
@@ -99,7 +115,7 @@ short story 3300
 ### Search
 
 ```
-  Usage: short find [options] [SEARCH OPERATORS]
+  Usage: short search [options] [SEARCH OPERATORS]
 
   Search through Shortcut stories. Arguments (non-flag/options) will
   be passed to Shortcut story search API as search operators. Passing '%self%' as
@@ -194,6 +210,7 @@ The default sorting for stories found is `state.position:asc,position:asc`, whic
 
   Options:
 
+    -a, --archived           Update story as archived
     -I, --idonly              Print only ID of story results
     -s, --state [id|name]     Update workflow state of story
     -e, --estimate [number]   Update estimate of story
@@ -213,12 +230,17 @@ The default sorting for stories found is `state.position:asc,position:asc`, whic
     --move-down [n]           Move story position downward by n stories
     --move-up [n]             Move story position upward by n stories
     -c, --comment [text]      Add comment to story
+    --deadline [date]         Update due date of story (YYYY-MM-DD)
+    --external-link [url]     Add external link to story, comma-separated
+    --follower [id|name]      Update followers of story, comma-separated
     -o, --owners [id|name]    Update owners of story, comma-separated
     -O, --open                Open story in browser
     --oe, --open-epic         Open story's epic in browser
     --oi, --open-iteration    Open story's iteration in browser
     --op, --open-project      Open story's project in browser
     -q, --quiet               Print only story output, no loading dialog
+    --requester [id|name]     Update requester of story
+    -T, --team [id|name]      Update team/group of story
     -t, --title [text]        Update title of story
     --task [text]             Create new task on story
     --task-complete [text]    Toggle completion of story task matching text
@@ -226,6 +248,44 @@ The default sorting for stories found is `state.position:asc,position:asc`, whic
     -h, --help                output usage information
 ```
 
+History:
+
+```sh
+npx short story history 17
+```
+
+Comments:
+
+```sh
+npx short story comments 17
+```
+
+Tasks:
+
+```sh
+npx short story tasks 17
+```
+
+Sub-tasks:
+
+```sh
+npx short story sub-tasks 17
+```
+
+Relations:
+
+```sh
+npx short story relation add 17 44 --type relates-to
+```
+
+Update examples:
+
+```sh
+npx short story 17 --deadline 2026-03-31
+npx short story 17 --requester test3969 --follower test3969
+npx short story 17 --external-link "https://example.com/spec"
+```
+
 Example output:
 
 ```
@@ -264,7 +324,7 @@ Comment: This is a comment
     -T, --team [id|name]      Set team of story
     -t, --title [text]        Set title of story, required
     -s, --state [id|name]     Set workflow state of story, required if --project is not set
-    -y, --type [name]         Set type of story, default: feature
+    -y, --type <name>         Set type of story (feature, bug, chore; default: feature)
     -h, --help                output usage information
     --git-branch              Checkout git branch from story slug <mention-name>/ch<id>/<type>-<title>
                               as required by the Git integration: https://bit.ly/2RKO1FF
@@ -303,6 +363,158 @@ Comment: This is a comment
     -h, --help            output usage information
 ```
 
+### Teams
+
+```
+  Usage: short teams [options]
+
+  Display teams available for stories and epics
+
+
+  Options:
+
+    -a, --archived        List teams including archived
+    -s, --search [query]  List teams with name containing query
+    -h, --help            output usage information
+```
+
+```
+  Usage: short team [command] [options]
+
+  view a team or list its stories
+
+
+  Commands:
+
+    view <idOrName>     view a team by id or name
+    stories <idOrName>  list stories for a team by id or name
+```
+
+View a team:
+
+```sh
+npx short team test-team
+```
+
+List team stories:
+
+```sh
+npx short team stories test-team
+```
+
+### Labels
+
+```
+  Usage: short labels [options]
+
+  Display labels available for stories and epics
+
+
+  Options:
+
+    -a, --archived        List labels including archived
+    -s, --search [query]  List labels with name containing query
+    -h, --help            output usage information
+```
+
+```
+  Usage: short label [command] [options]
+
+  create labels or view stories for a label
+
+
+  Commands:
+
+    create             create a new label
+    update <idOrName>  update an existing label
+    epics <idOrName>   list epics for a label by id or name
+    stories <idOrName>  list stories for a label by id or name
+```
+
+Create a label:
+
+```
+  Usage: short label create [options]
+
+  Options:
+
+    -n, --name [text]         Set name of label, required
+    -d, --description [text]  Set description of label
+    -c, --color [hex]         Set label color in hex format like #3366cc
+    -I, --idonly              Print only ID of label result
+    -h, --help                output usage information
+```
+
+Update a label:
+
+```
+  Usage: short label update <idOrName> [options]
+
+  Options:
+
+    -n, --name [text]         Set name of label
+    -d, --description [text]  Set description of label
+    -c, --color [hex]         Set label color in hex format like #3366cc
+    -a, --archived            Archive label
+    -h, --help                output usage information
+```
+
+List stories for a label:
+
+```
+  Usage: short label stories <idOrName> [options]
+
+  Options:
+
+    -d, --detailed           Show more details for each story
+    -f, --format [template]  Format each story output by template
+    -h, --help               output usage information
+```
+
+List epics for a label:
+
+```
+  Usage: short label epics <idOrName>
+```
+
+Example:
+
+```sh
+npx short labels --search client
+npx short label create --name "triage-needed" --color "#3366cc"
+npx short label update triage-needed --description "Queue for manual review"
+npx short label epics client_web
+npx short label stories client_web
+```
+
+### Custom Fields
+
+```
+  Usage: short custom-fields [options]
+
+  Display custom fields available for stories
+
+
+  Options:
+
+    -d, --disabled        List custom fields including disabled
+    -s, --search [query]  List custom fields with name containing query
+    -h, --help            output usage information
+```
+
+```
+  Usage: short custom-field <id> [options]
+
+  view a custom field by id
+```
+
+Example:
+
+```sh
+npx short custom-fields --search priority
+npx short custom-field 123e4567-e89b-12d3-a456-426614174000
+```
+
 ### Epics
 
 ```
@@ -318,12 +530,49 @@ Comment: This is a comment
     -d, --detailed            List more details for each epic
     -f, --format [template]   Format epic output by template
     -M, --milestone [ID]      List only epics with the given milestone ID
+    --objectives [id|name]    List epics linked to objective id/name, comma-separated
     -t, --title [query]       List epics with name/title containing query
     -s, --started             List epics that have been started
     -h, --help                output usage information
 ```
 
-#### Epic Creation
+Example:
+
+```sh
+npx short epics --objectives "Our first Tactical Objective"
+```
+
+#### Epic Commands
+
+```
+  Usage: short epic [command] [options]
+
+  create, view, or update epics
+
+
+  Commands:
+
+    create        create a new epic
+    view <id>     view an epic by id
+    update <id>   update an existing epic
+    stories <id>  list stories in an epic
+    comments <id> list comments on an epic
+```
+
+You can use `short epic` to create, view, or update a single epic.
+
+View an epic:
+
+```
+  Usage: short epic view <id> [options]
+
+  Options:
+
+    -O, --open   Open epic in browser
+    -h, --help   output usage information
+```
+
+Create an epic:
 
 ```
   Usage: short epic create [options]
@@ -341,11 +590,70 @@ Comment: This is a comment
     -o, --owners [id|name]     Set owners of epic, comma-separated
     -T, --team [id|name]       Set team of epic
     -l, --label [id|name]      Set labels of epic, comma-separated
+    -M, --milestone [id]       Set milestone of epic (deprecated, use objectives)
+    --objectives [id|name]     Set objectives of epic, comma-separated
     -I, --idonly               Print only ID of epic result
     -O, --open                 Open epic in browser
     -h, --help                 output usage information
 ```
 
+Update an epic:
+
+```
+  Usage: short epic update <id> [options]
+
+  Options:
+
+    -n, --name [text]          Set name of epic
+    -d, --description [text]   Set description of epic
+    -s, --state [name]         Set state of epic (to do, in progress, done)
+    --deadline [date]          Set deadline for epic (YYYY-MM-DD)
+    --planned-start [date]     Set planned start date (YYYY-MM-DD)
+    -o, --owners [id|name]     Set owners of epic, comma-separated
+    -T, --team [id|name]       Set team of epic
+    -l, --label [id|name]      Set labels of epic, comma-separated
+    -M, --milestone [id]       Set milestone of epic (deprecated, use objectives)
+    --objectives [id|name]     Set objectives of epic, comma-separated
+    -a, --archived             Archive epic
+    -O, --open                 Open epic in browser
+    -h, --help                 output usage information
+```
+
+List stories in an epic:
+
+```
+  Usage: short epic stories <id> [options]
+
+  Options:
+
+    -d, --detailed           Show more details for each story
+    -f, --format [template]  Format each story output by template
+    -h, --help               output usage information
+```
+
+Example:
+
+```sh
+npx short epic stories 36
+```
+
+List comments on an epic:
+
+```
+  Usage: short epic comments <id> [options]
+
+  Options:
+
+    -d, --detailed  Show nested replies for each comment
+    -h, --help      output usage information
+```
+
+Example:
+
+```sh
+npx short epic comments 16
+```
+
 #### Epic Output Formatting
 
 Templating variables:
@@ -354,6 +662,7 @@ Templating variables:
 %id      Print ID of epic
 %t       Print title/name of epic
 %m       Print milestone of epic
+%obj     Print linked objectives of epic
 %s       Print epic state
 %dl      Print epic deadline
 %d       Print epic description
@@ -361,11 +670,220 @@ Templating variables:
 %ps      Print epic total points started
 %pd      Print epic total points done
 %c       Print epic total completion percentage
-%a       Print archived status of epic
+%ar      Print archived status of epic
 %st      Print started status of epic
 %co      Print completed status of epic
 ```
 
+### Objectives
+
+```
+  Usage: short objectives [options] [SEARCH OPERATORS]
+
+  List and search Shortcut objectives. By default, lists all objectives.
+  Passing search operators will use the Shortcut objective search API and
+  page through all results.
+
+
+  Options:
+
+    -a, --archived          List only objectives including archived
+    -c, --completed         List only objectives that have been completed
+    -d, --detailed          List more details for each objective
+    -f, --format [template] Format each objective output by template
+    -s, --started           List objectives that have been started
+    -S, --state [state]     Filter objectives by state
+    -t, --title [query]     Filter objectives with name/title containing query
+    -h, --help              output usage information
+```
+
+#### Objective Commands
+
+```
+  Usage: short objective [command] [options]
+
+  view, create, or update objectives
+
+
+  Commands:
+
+    view <id>     view an objective by id
+    create        create a new objective
+    update <id>   update an existing objective
+    epics <id>    list epics in an objective
+```
+
+You can use `short objective` to view, create, or update a single objective.
+
+View an objective:
+
+```
+  Usage: short objective view <id> [options]
+
+  Options:
+
+    -O, --open   Open objective in browser
+    -h, --help   output usage information
+```
+
+You can also view an objective directly by ID: `short objective <id>`
+
+Create an objective:
+
+```
+  Usage: short objective create [options]
+
+  Options:
+
+    -n, --name [text]          Set name of objective, required
+    -d, --description [text]   Set description of objective
+    -s, --state [name]         Set state of objective (to do, in progress, done)
+    --started-at [date]        Set started override (ISO date or YYYY-MM-DD)
+    --completed-at [date]      Set completed override (ISO date or YYYY-MM-DD)
+    -I, --idonly               Print only ID of objective result
+    -O, --open                 Open objective in browser
+    -h, --help                 output usage information
+```
+
+Update an objective:
+
+```
+  Usage: short objective update <id> [options]
+
+  Options:
+
+    -n, --name [text]          Set name of objective
+    -d, --description [text]   Set description of objective
+    -s, --state [name]         Set state of objective (to do, in progress, done)
+    --started-at [date]        Set started override (ISO date or YYYY-MM-DD)
+    --completed-at [date]      Set completed override (ISO date or YYYY-MM-DD)
+    -a, --archived             Archive objective
+    -O, --open                 Open objective in browser
+    -h, --help                 output usage information
+```
+
+List epics in an objective:
+
+```
+  Usage: short objective epics <id>
+```
+
+### Iterations
+
+```
+  Usage: short iterations [options]
+
+  Display iterations available for stories
+
+
+  Options:
+
+    -S, --status [status]     Filter by status (unstarted, started, done)
+    -T, --team [id|name]      Filter by team/group id or name
+    -C, --current             Show only current/active iterations
+    -t, --title [query]       Filter iterations with name containing query
+    -d, --detailed            Show more details for each iteration
+    -f, --format [template]   Format each iteration output by template
+    -h, --help                output usage information
+```
+
+#### Iteration View, Create, Update, Delete
+
+```
+  Usage: short iteration [command] [options]
+
+  view, create, update, or delete iterations
+
+
+  Commands:
+
+    view <id>     view an iteration by id
+    create        create a new iteration
+    update <id>   update an existing iteration
+    delete <id>   delete an iteration
+    stories <id>  list stories in an iteration
+```
+
+View an iteration:
+
+```
+  Usage: short iteration view <id> [options]
+
+  Options:
+
+    -O, --open   Open iteration in browser
+    -h, --help   output usage information
+```
+
+Create an iteration:
+
+```
+  Usage: short iteration create [options]
+
+  Options:
+
+    -n, --name [text]         Set name of iteration (required)
+    -d, --description [text]  Set description of iteration
+    --start-date [date]       Set start date (YYYY-MM-DD, required)
+    --end-date [date]         Set end date (YYYY-MM-DD, required)
+    -T, --team [id|name]      Set team/group of iteration
+    -I, --idonly              Print only ID of iteration result
+    -O, --open                Open iteration in browser
+    -h, --help                output usage information
+```
+
+Update an iteration:
+
+```
+  Usage: short iteration update <id> [options]
+
+  Options:
+
+    -n, --name [text]         Set name of iteration
+    -d, --description [text]  Set description of iteration
+    --start-date [date]       Set start date (YYYY-MM-DD)
+    --end-date [date]         Set end date (YYYY-MM-DD)
+    -T, --team [id|name]      Set team/group of iteration
+    -O, --open                Open iteration in browser
+    -h, --help                output usage information
+```
+
+Delete an iteration:
+
+```
+  Usage: short iteration delete <id>
+```
+
+List stories in an iteration:
+
+```
+  Usage: short iteration stories <id> [options]
+
+  Options:
+
+    -f, --format [template]   Format each story output by template
+    -h, --help                output usage information
+```
+
+#### Iteration Output Formatting
+
+Templating variables:
+
+```
+%id          Print ID of iteration
+%t           Print title/name of iteration
+%s           Print iteration status
+%start       Print iteration start date
+%end         Print iteration end date
+%teams       Print teams assigned to iteration
+%stories     Print total number of stories
+%done        Print number of completed stories
+%points      Print total points
+%pdone       Print completed points
+%completion  Print completion percentage
+%url         Print URL of iteration
+```
+
 ### Docs
 
 ```
@@ -512,16 +1030,37 @@ Delete a doc:
 
 ## Development
 
+Install dependencies first:
+
+```sh
+pnpm install
+```
+
+Build the CLI:
+
+```sh
+pnpm run build
+```
+
 You can use TypeScript watcher which will recompile your code automatically:
 
 ```sh
-npm run build:watch
+pnpm run build:watch
 ```
 
 You can run shortcut-cli with TypeScript map enabled:
 
 ```sh
-npm start -- story 1234
+pnpm start -- story 1234
+```
+
+Run the main checks:
+
+```sh
+pnpm test
+pnpm run test:format
+pnpm run type-check
+pnpm run lint
 ```
 
 ## Acknowledgments