@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. The deployment process is fully automated.

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 publish to npm

Publishing to npm

Publishing 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:
- Build the package (yarn build via prepublishOnly)
- Publish to npm under @shortcut/client
- Also publish under the legacy @useshortcut/client namespace for backwards compatibility

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/