@shortcut/client

A library for interacting with the Shortcut REST API.

Getting Started

Installation

npm install @shortcut/client

Important

Our legacy npm organization namespace is @useshortcut.

While it will still contain copies of all future released package versions, we strongly recommend switching to our primary @shortcut organization namespace.

How to Get an API Token

The Shortcut API uses token-based authentication, you will need one to use this library.

To generate an API token, go to https://app.shortcut.com/settings/account/api-tokens.

To make it easier to explore our API, we recommend saving this token as an environment variable in your local dev environment:

export SHORTCUT_API_TOKEN="YOUR API TOKEN HERE"

This will allow you to copy and paste many examples in the documentation to try them out.

Note

Requests made with a missing or invalid token will get a 401 Unauthorized response.

Note

All requests must be made over HTTPS.

Caution

Tokens provide complete access to your Shortcut account, so keep them secure.

Don’t paste them into your source code, use an environment variable instead.

For security reasons, we will immediately invalidate any tokens we find have been made public.

Usage

To see all available exports, take a look at the API documentation or check out the .d.ts files in this repository.

import { ShortcutClient } from '@shortcut/client';
// const { ShortcutClient } = require('@shortcut/client');

const shortcut = new ShortcutClient('YOUR_API_TOKEN'); // See https://github.com/useshortcut/shortcut-client-js#how-to-get-an-api-token

shortcut.getCurrentMemberInfo().then((response) => console.log(response?.data));

shortcut.listProjects().then((response) => console.log(response?.data));

Play with It

You can play with it in your web browser with this live playground:

CodeSandbox

Documentation

Documentation for this client.

Documentation for the REST API.

Publishing & Deployment

This library uses GitHub Actions for CI/CD. npm releases are staged automatically, then approved manually in npm.

Release Process

To publish a new version:

Update the version in package.json
Commit and push to main
Create a GitHub Release with a version tag (e.g., v2.4.0)
The publish workflow will automatically build and stage the package versions on npm
Review and approve both staged packages in npm to publish them live

Staged Publishing to npm

Staging is triggered automatically when a GitHub Release is created:

Create a GitHub Release: Go to the repository's Releases page and create a new release with a version tag (e.g., v2.4.0)
The publish.yml workflow will stage @shortcut/client, then stage the same built package under the legacy @useshortcut/client namespace
Review the staged packages in npm using npm stage list, npm stage view <stage-id>, or the npmjs.com Staged Packages tab
Approve both staged packages with 2FA using npm stage approve <stage-id> or the npmjs.com approval flow

The npm trusted publisher for this repository must allow npm stage publish for .github/workflows/publish.yml. Trusted publishing from GitHub Actions automatically generates provenance for public packages from public repositories. Staged publishing requires npm CLI 11.15.0 or later and Node.js 22.14.0 or later.

Documentation Deployment

API documentation is automatically deployed to GitHub Pages on every push to main:

The gh-pages.yml workflow builds the documentation using TypeDoc
Documentation is published to https://useshortcut.github.io/shortcut-client-js/