Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
name: CI

on:
push:
branches: [main]
pull_request:

permissions:
contents: read

jobs:
test:
name: Node ${{ matrix.node }} on ${{ matrix.os }}
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest]
node: [18, 20, 22, 24]
include:
# Paths, PATH lookup, and the clipboard differ on these systems.
- os: macos-latest
node: 22
- os: windows-latest
node: 22
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: ${{ matrix.node }}
package-manager-cache: false
- run: npm test
42 changes: 42 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# Publish to npm when a GitHub release is published.
# It uses npm trusted publishing (OIDC), so the repository holds no npm token.
# npm creates the provenance statement for the package.
# Before the first run: publish 0.2.0 once by hand and add this workflow as the
# trusted publisher of @taskade/cli on npmjs.com. See "For maintainers" in README.md.

name: Release

on:
release:
types: [published]

permissions:
contents: read

jobs:
publish:
runs-on: ubuntu-latest
permissions:
contents: read
id-token: write
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
# Trusted publishing needs npm 11.5.1 or later. Node 24 includes it.
node-version: 24
registry-url: https://registry.npmjs.org
package-manager-cache: false
- name: Check that the tag equals the package version
env:
TAG: ${{ github.event.release.tag_name }}
run: |
VERSION="$(node -p "require('./package.json').version")"
if [ "$TAG" != "v$VERSION" ]; then
echo "::error::The release tag is $TAG, but package.json has version $VERSION. The tag must be v$VERSION."
exit 1
fi
- run: npm test
- run: npm publish --provenance --access public
34 changes: 34 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Changelog

## 0.2.0

### Added

- `plug <client>` connects Claude Code, Codex, Cursor, VS Code, or Claude Desktop to `https://www.taskade.com/mcp`. The default is the browser sign-in (OAuth), with no token.
- For Claude Code, Codex, and VS Code, `plug` shows the command of the client and runs it after a "y".
- For Cursor and for `vscode --project`, `plug` merges one `taskade` entry into the JSON config file. It shows a diff, writes a backup, writes atomically, keeps the file mode and the format of the rest of the file, and refuses a file that is not valid JSON.
- For Claude Desktop, `plug` prints the 3 steps for the Connectors screen and copies the URL to the clipboard.
- `plug` with no client lists the clients on the machine and changes nothing.
- `--yes`, `--print`, `--project`, and `--token`. `--token` reads a personal access token from `TASKADE_TOKEN` only, and never prints the full token.
- `doctor` checks the Node.js version, the server and its sign-in metadata, the token with an MCP `initialize` and `tools/list` request, and the client config files. `--json` prints the result as JSON. `--verbose` prints the tool names.
- `connect` is an alias of `plug`. `claude` is an alias of `claude-code`.
- `--version`.
- CI on Node.js 18, 20, 22, and 24 on Linux, and Node.js 22 on macOS and Windows.
- A release workflow that publishes to npm with provenance through npm trusted publishing.
- `SECURITY.md`.

### Changed

- `whoami` is now an alias of `doctor`. The old `whoami` called an API path that does not exist and always failed with 404.
- `plug` no longer asks for a token, and the default config holds no token.
- `npm test` lists the test files, so it works on every supported Node.js version.
- The copyright holder in `LICENSE` is TASKCADE INC.

### Removed

- `TASKADE_API_URL`. `TASKADE_MCP_URL` sets another server URL for tests.

## 0.1.0

- `plug [cursor|claude]` printed a config block with a personal access token.
- `whoami` called an API path that does not exist.
2 changes: 1 addition & 1 deletion LICENSE
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
MIT License

Copyright (c) 2026 Taskade
Copyright (c) 2026 TASKCADE INC.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
Expand Down
177 changes: 118 additions & 59 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,99 +1,158 @@
# @taskade/cli

Thin CLI for Taskade MCP plug-and-play. It prints the config block that connects Cursor or Claude Code to your Taskade workspace with a personal access token.
Connect your AI client to Taskade with one command:

> **Not on npm yet.** The package `@taskade/cli` is not published, so `npx @taskade/cli` fails. Run the CLI from GitHub with `npx github:taskade/cli`.
```bash
npx github:taskade/cli plug
```

Most clients do not need this CLI or a token. They connect to `https://www.taskade.com/mcp` and sign in with OAuth. See [taskade/mcp](https://github.com/taskade/mcp) for the steps for each client. Use this CLI when a client cannot sign in with OAuth.
The command lists the MCP clients on your machine and the command to run for each. It changes nothing.

## Quick Start
> **Not on npm yet.** Until the first npm release, run the CLI from GitHub with `npx github:taskade/cli`. After that release, `npx @taskade/cli` works too.

```bash
# 1. Create a personal access token at https://www.taskade.com/settings/api (it starts with tskdp_)
## Most people need no CLI

# 2. Connect Cursor
npx github:taskade/cli plug cursor
Paste this line into your agent. The agent reads the steps and connects itself:

```text
Set up Taskade for me. Read and follow https://www.taskade.com/SKILL.md
```

- The Taskade skills: [taskade/skills](https://github.com/taskade/skills)
- The Taskade MCP server and plugin: [taskade/mcp](https://github.com/taskade/mcp)
- The hosted server guide: [Hosted Taskade MCP](https://www.taskade.com/docs/mcp/hosted-mcp)

# 3. Connect Claude Code
npx github:taskade/cli plug claude
The hosted server is `https://www.taskade.com/mcp`. It is part of every paid Taskade plan. Clients sign in with your Taskade account in the browser (OAuth), so you need no token.

## Connect a client: `plug`

```bash
npx github:taskade/cli plug claude-code
npx github:taskade/cli plug codex
npx github:taskade/cli plug cursor
npx github:taskade/cli plug vscode
npx github:taskade/cli plug claude-desktop
```

## What This Does
Each command shows the change first. In a terminal, it asks for a "y" before it changes anything. On a pipe or in CI, it only prints. `connect` is an alias of `plug`, and `claude` is an alias of `claude-code`.

| Client | What the CLI does | What changes on your machine |
| --- | --- | --- |
| `claude-code` | Runs `claude mcp add --transport http --scope user taskade https://www.taskade.com/mcp`. | Claude Code adds the server to `~/.claude.json`. With `--project`, it writes `.mcp.json` in the current folder. |
| `codex` | Runs `codex mcp add taskade --url https://www.taskade.com/mcp`, then `codex mcp login taskade` if the add step did not sign you in. | Codex adds the server to `~/.codex/config.toml` and keeps the sign-in. |
| `cursor` | Merges one `taskade` entry into the Cursor config file. | `~/.cursor/mcp.json`, or `.cursor/mcp.json` in the current folder with `--project`. |
| `vscode` | Runs `code --add-mcp` with the `taskade` entry. With `--project`, merges one entry into the file. | Your VS Code user profile, or `.vscode/mcp.json` in the current folder with `--project`. |
| `claude-desktop` | Prints the 3 steps for the Connectors screen and copies the URL to the clipboard. | Only the clipboard. Claude keeps connectors in your Claude account, not in a file, so the CLI cannot add one for you. |

When a client command (`claude`, `codex`, `code`) is not on your PATH, the CLI prints the command and the install step, and exits 0.

When the CLI changes a JSON file, it:

This CLI prints the MCP server config block you need to paste into your AI agent client (Cursor or Claude Code). The block holds your token. Do not commit a file that holds your token.
- Shows the file and the exact change as a diff.
- Keeps every other key and every other server, and the format of the rest of the file.
- Writes a backup copy beside the file first (`<file>.bak-<timestamp>`).
- Writes a temp file, then renames it over the file. The file keeps its mode.
- Refuses a file that is not valid JSON and leaves it unchanged. (JSON with comments counts as not valid.)
- Says "Already connected" and changes nothing when an equal `taskade` entry exists. When a different entry exists, it shows both and asks.

**The token is the product.** You do not need this CLI to use Taskade MCP - you can copy the config block manually from [https://www.taskade.com/settings/api](https://www.taskade.com/settings/api). This CLI just makes it one command instead of five clicks.
Run `plug` with no client name to see which clients are on your machine.

## Commands
### Options for `plug`

### `taskade plug [cursor|claude]`
| Option | Effect |
| --- | --- |
| `--yes`, `-y` | Apply the change with no question. |
| `--print` | Show the command or the config block. Change nothing. This is the default on a pipe or in CI. |
| `--project` | Write the project file of the current folder, not the user file (Claude Code, Cursor, VS Code). |
| `--token` | Use a personal access token in place of the browser sign-in. See below. |

Prints the MCP server config block.
### A machine with no browser: `--token`

A headless machine cannot sign in with a browser. Create a personal access token at [https://www.taskade.com/settings/api](https://www.taskade.com/settings/api), put it in the environment variable `TASKADE_TOKEN`, and add `--token`:

```bash
npx github:taskade/cli plug cursor # Cursor format with instructions
npx github:taskade/cli plug claude # Claude Code format with instructions
npx github:taskade/cli plug # Raw JSON, no client wrapper
export TASKADE_TOKEN=... # your token
npx github:taskade/cli plug cursor --token
```

Output (raw JSON):

```json
{
"mcpServers": {
"taskade": {
"url": "https://www.taskade.com/mcp",
"headers": {
"Authorization": "Bearer tskdp_..."
}
}
}
}
- The CLI reads the token only from `TASKADE_TOKEN`. It refuses a token on the command line, because your shell history keeps it.
- The CLI never prints the full token. It shows the first 6 characters and "…".
- The config file then holds your token, and anyone who can read the file can use your Taskade account. A new file gets mode 600. Do not commit a project file that holds a token.
- Codex keeps only the name `TASKADE_TOKEN` in its config and reads the token from the environment each time it starts.
- Claude Desktop takes no token from the CLI.

## Check a connection: `doctor`

```bash
npx github:taskade/cli doctor
```

`plug claude` adds `"type": "http"` to the block. Claude Code needs this field for a remote server.
`doctor` answers "why does my connection fail?" in plain lines. Each line starts with `ok`, `fail`, or `--` (skipped), and a failed line gives the next step. It changes nothing on your machine. `whoami` is an alias of `doctor`.

For Claude Desktop, add `https://www.taskade.com/mcp` in **Settings > Connectors** and sign in. Claude Desktop does not need a token.
It checks:

### `taskade whoami`
1. The Node.js version.
2. The server: a request with no sign-in must return 401 with a `www-authenticate` header that names the sign-in metadata. It then reads that metadata and the metadata of the authorization server.
3. With `TASKADE_TOKEN` set: an MCP `initialize` request and a `tools/list` request with your token. It reports that the token works and the server lists its tools, or the exact refusal of the server.
4. The clients on your machine, and whether each one has a `taskade` server entry. It only reads the files.

> **This command does not work today.** It calls `GET /api/v2/user`, and the Taskade public API has no such path. The command prints `API returned 404 Not Found` for every token.
Example, with a token that the server does not accept:

```bash
npx github:taskade/cli whoami
```text
ok The server answers. Without sign-in it returns 401 and names its sign-in metadata.
ok Sign-in metadata: https://www.taskade.com/mcp/.well-known/oauth-protected-resource
ok Authorization server: https://www.taskade.com/.well-known/oauth-authorization-server

fail The server refused the token (401: Invalid or expired token).
Next: Create a new token at https://www.taskade.com/settings/api and set TASKADE_TOKEN to it.
```

## Environment Variables
| Option | Effect |
| --- | --- |
| `--json` | Print the result as JSON, for scripts. |
| `--verbose` | Print the names of the tools that the server lists. |

The exit code is 0 when every check passes and 1 when a check fails. `doctor` sends your token only to the server URL, and it does not follow a redirect with the token.

| Variable | Default | Description |
|----------|---------|-------------|
| `TASKADE_TOKEN` | (prompt) | Your personal access token (`tskdp_...`). Create one at [https://www.taskade.com/settings/api](https://www.taskade.com/settings/api) |
| `TASKADE_API_URL` | `https://www.taskade.com` | API base URL for `whoami` |
## Environment

| Variable | Use |
| --- | --- |
| `TASKADE_TOKEN` | A personal access token. `plug` reads it only with `--token`. `doctor` uses it for the token check. |
| `TASKADE_MCP_URL` | Another server URL, for tests. It must use `https://`, except for `localhost` and `127.0.0.1`. |

## Other commands

| Command | Effect |
| --- | --- |
| `help`, `--help`, `-h` | Show the help. |
| `--version`, `-v` | Show the version. |

An unknown command prints a short message and exits 1.

## Requirements

- Node.js 18+ (uses built-in `fetch`)
Node.js 18 or later. The CLI has no dependencies.

## For maintainers

Run the tests with `npm test`. The tests use a temporary HOME and PATH, fake client commands, and a fake MCP server on `127.0.0.1`. They never touch the config of your machine.

## Hosted MCP and the local package
To release a version:

| | Hosted MCP | Local package (stdio) |
|---|-----------|-------------|
| Run | `https://www.taskade.com/mcp` | `npx @taskade/mcp-server` |
| Auth | OAuth sign-in, or a personal access token (`tskdp_...`) | Personal access token (`tskdp_...`) |
| Plan | Every paid plan | See [taskade/mcp](https://github.com/taskade/mcp) |
| Best for | Clients that support remote servers | Clients that support only stdio servers |
1. Set the version in `package.json` and add a section to `CHANGELOG.md`.
2. Change the examples in this README and the `RUN` constant in `src/clients.mjs` from `npx github:taskade/cli` to `npx @taskade/cli` (once, with the first npm release).
3. Publish a GitHub release with the tag `v<version>`. The `Release` workflow checks that the tag equals the version, runs the tests, and publishes to npm with provenance.

Both need network access to taskade.com. The local package calls the Taskade public API. [taskade/mcp](https://github.com/taskade/mcp) lists the tools of each.
The `Release` workflow uses npm trusted publishing (OIDC), so the repository holds no npm token. It cannot work before these two steps, which an owner of the npm scope must do once:

**Use hosted MCP** when your client supports remote servers.
1. Publish the first version by hand from a clean checkout: `npm publish --access public`.
2. On npmjs.com, open the settings of `@taskade/cli` and add a trusted publisher: GitHub Actions, organization `taskade`, repository `cli`, workflow `release.yml`.

## Related
## Security

- [Hosted MCP](https://www.taskade.com/mcp) - the server this CLI configures
- [API v2 docs](https://www.taskade.com/api/documentation/v2) - the REST API the MCP wraps
- [taskade/mcp](https://github.com/taskade/mcp) - the MCP server repo
- [taskade/docs](https://github.com/taskade/docs) - developer documentation
Report a vulnerability to security@taskade.com. See [SECURITY.md](SECURITY.md).

## License

MIT
MIT. See [LICENSE](LICENSE).
24 changes: 24 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Security policy

## Report a vulnerability

Send an email to security@taskade.com. Do not open a public issue for a vulnerability.

Include:

- The version of `@taskade/cli` and of Node.js.
- The steps to reproduce the problem.
- The effect that you saw.

We answer each report, and we tell you when a release includes the fix.

## Supported versions

We fix security problems in the newest release only.

## How the CLI handles a token

- The CLI reads a personal access token only from the environment variable `TASKADE_TOKEN`. It refuses a token on the command line.
- It never prints the full token.
- It sends the token only to the server URL, only over `https://` (or to `localhost` for tests), and it does not follow a redirect with the token.
- `plug --token` writes the token into the config file of the client. Treat that file as a secret.
Loading
Loading