TAPD CLI

tapd is a command line client for TAPD, built on top of the typed github.com/go-tapd/tapd SDK.

It provides commands for common TAPD resources such as stories, bugs, tasks, iterations, workspaces, wiki pages, test cases, releases, comments, attachments, webhooks, TAPD Lite comments, and raw TAPD API calls.

📦 Install

Homebrew

brew install go-tapd/tap/tapd

npm

Use this when you want to install tapd through Node.js tooling:

npm install -g @go-tapd/tapd

GitHub Releases

Download a prebuilt archive for your platform from GitHub Releases.

Go

go install github.com/go-tapd/cli/cmd/tapd@latest

Requires Go 1.25 or later. This installs a binary named tapd.

🚀 Quick Start

tapd login --auth-method pat
tapd auth status
tapd story list --workspace-id 123456 --limit 20

Use tapd --help and tapd <command> --help to inspect available commands and flags.

🔐 Authentication

The recommended interactive setup is tapd login.

Personal access token:

tapd login --auth-method pat

Validate credentials during login:

tapd login --auth-method pat --workspace-id 123456

Basic authentication:

tapd login --auth-method basic

You can also pass credentials directly:

tapd login --token "$TAPD_ACCESS_TOKEN"
tapd login --client-id "$TAPD_CLIENT_ID" --client-secret "$TAPD_CLIENT_SECRET"

The login command stores credentials in:

~/.tapd/config.json

For CI or temporary shell sessions, you can skip local config and use environment variables:

export TAPD_ACCESS_TOKEN=...

or:

export TAPD_CLIENT_ID=...
export TAPD_CLIENT_SECRET=...

✨ Common Examples

tapd workspace view --workspace-id 123456
tapd workspace users --workspace-id 123456

tapd story list --workspace-id 123456 --limit 20
tapd story view 1111112222001000001 --workspace-id 123456
tapd story create --workspace-id 123456 --name "New story" --owner alice

tapd bug list --workspace-id 123456 --owner alice
tapd bug create --workspace-id 123456 --title "Login fails" --owner alice

tapd task list --workspace-id 123456 --creator bob --format json
tapd api tasks/get_fields_info --field workspace_id=123456
tapd webhook inspect --file payload.json
tapd webhook serve --addr 127.0.0.1:8080 --path /webhook

🧭 Command Areas

• Authentication: tapd login, tapd auth status, tapd auth logout
• Raw API: tapd api ...
• Workspaces: tapd workspace ...
• Stories: tapd story ...
• Bugs: tapd bug ...
• Tasks: tapd task ...
• Iterations: tapd iteration ...
• Tests: tapd test-case ..., tapd test-plan ...
• Releases: tapd release ..., tapd launch-form ...
• Wiki: tapd wiki ...
• Reports and metrics: tapd report ..., tapd measure ...
• Timesheets: tapd timesheet ...
• Comments: tapd comment ...
• Attachments: tapd attachment ...
• Boards: tapd board ...
• Workflow and settings: tapd workflow ..., tapd setting ...
• Labels and users: tapd label ..., tapd user ...
• Source integrations: tapd source ...
• Webhooks: tapd webhook ...
• TAPD Lite: tapd lite comment ...

📚 Documentation

• Raw API command
• Shell completion
• Workspace commands
• Story commands
• Bug commands
• Task commands
• Iteration commands
• Test commands
• Release commands
• Wiki commands
• Report commands
• Attachment commands
• Measure commands
• Timesheet commands
• Comment commands
• Board commands
• Workflow commands
• Setting commands
• Label commands
• User commands
• Source commands
• Webhook commands
• Lite commands
• Feature coverage

🛠️ Development

make lint
make test
go build ./...

Test coverage is currently minimal, so command and documentation changes should also be checked with the relevant tapd <command> --help output.

When adding a command, prefer the typed services, requests, and responses from github.com/go-tapd/tapd rather than writing ad hoc HTTP calls.

📄 License

This project is licensed under the MIT License.