@teamwork/get-bearer-token/README.md

CLI tool to obtain bearer tokens for Teamwork API using OAuth flow

# Teamwork Bearer Token Generator

## Overview

CLI tool that generates OAuth bearer tokens for the Teamwork API. Opens your system browser for Teamwork Launchpad authentication (including Google SSO), then provides a web UI to manage developer apps and generate tokens.

**Key features:**
- Secure OAuth authentication via Teamwork Launchpad (Google SSO supported)
- Automatic account and region detection
- Create and manage developer apps
- Generate bearer tokens with one click
- No configuration required

## Usage

```bash
npx --yes @teamwork/get-bearer-token@latest
```

Or install globally:

```bash
npm install -g @teamwork/get-bearer-token
get-bearer-token
```

The CLI starts a local server on port 8123, opens your browser for authentication, and serves a web UI for managing apps and tokens. Press Ctrl+C to stop.

## Configuration for Staging / Custom Instances

By default the tool authenticates against production Teamwork using the built-in Timer app OAuth credentials. To target a staging or custom Teamwork instance, set these environment variables (or add them to a `.env` file):

| Variable | Description | Default |
|---|---|---|
| `TEAMWORK_URL` | Base URL of the Teamwork instance | `https://www.teamwork.com` |
| `TEAMWORK_CLIENT_ID` | OAuth app client ID | Timer app production ID |
| `TEAMWORK_CLIENT_SECRET` | OAuth app client secret | Timer app production secret |

> **Note:** The OAuth app on your target instance must have `http://127.0.0.1:8123` listed as an allowed redirect URI.

Example:

```bash
TEAMWORK_URL=https://staging.teamwork.com \
TEAMWORK_CLIENT_ID=your-client-id \
TEAMWORK_CLIENT_SECRET=your-client-secret \
npx --yes @teamwork/get-bearer-token@latest
```

## Development

### Prerequisites

- Node.js 22+

### Setup

```bash
git clone <repository-url>
cd get-bearer-token
npm install
```

### Running

```bash
npm start
```

## Deployment

Push a version tag to trigger npm publish via GitHub Actions:

```bash
git tag 1.0.0
git push origin 1.0.0
```

Use `-rc` suffix for beta releases (e.g. `1.0.0-rc0`).