taskporter

README

Taskporter

Cross-Editor CLI Task Bridge • Inspired by Death Stranding

A Golang-powered CLI tool that acts as a "porter" for project automation, bridging and running tasks from various code editors directly from the terminal.

🎮 What is Taskporter?

Taskporter is a cross-editor task bridge that unifies task execution across different IDEs and editors. Just like Sam Porter Bridges connects isolated cities in Death Stranding, Taskporter connects your development tools, allowing you to run VSCode tasks, launch configurations, and JetBrains run configurations from a single, unified CLI.

🎬 See it in Action

Watch Taskporter discover, convert, and execute tasks across VSCode and JetBrains IDEs seamlessly

✨ Features

🎯 Multi-Editor Support

• VSCode Tasks - Parse and execute .vscode/tasks.json
• VSCode Launch Configs - Run .vscode/launch.json configurations with preLaunchTask support
• JetBrains IDEs - Execute .idea/runConfigurations/*.xml (IntelliJ, WebStorm, GoLand, etc.)
• Auto-Discovery - Automatically detects all configuration files in your project

🚀 Smart Execution

• Environment Variables - Full support with workspace path resolution
• Working Directory - Respects each task's configured working directory
• PreLaunchTasks - Automatically runs dependent tasks before launch configs
• Variable Resolution - Handles ${workspaceFolder}, $PROJECT_DIR$, and more

🎨 Developer Experience

• Smart Matching - Find tasks by exact name, case-insensitive, or partial match
• Verbose Mode - See all environment variables and execution details
• JSON Output - Perfect for CI/CD integration
• Death Stranding Theme - Enjoy "strand established" success messages

📋 Task Discovery

# List all available tasks and launch configs
taskporter list

# Get detailed scanning information
taskporter list --verbose

# JSON output for scripts and CI/CD
taskporter list --json

🛠 Installation

📦 Binary Downloads

Download the latest release for your platform from GitHub Releases.

Quick install for common platforms:

# Linux (x86_64)
curl -L https://github.com/syndbg/taskporter/releases/latest/download/taskporter_Linux_x86_64.tar.gz | tar xz
sudo mv taskporter /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/syndbg/taskporter/releases/latest/download/taskporter_Darwin_x86_64.tar.gz | tar xz
sudo mv taskporter /usr/local/bin/

# macOS (Apple Silicon)
curl -L https://github.com/syndbg/taskporter/releases/latest/download/taskporter_Darwin_arm64.tar.gz | tar xz
sudo mv taskporter /usr/local/bin/

# Windows (PowerShell)
curl -L -o taskporter.zip https://github.com/syndbg/taskporter/releases/latest/download/taskporter_Windows_x86_64.zip
Expand-Archive taskporter.zip

🐳 Docker

# Pull and run
docker run -ti --rm -v $(pwd):/workspace -w /workspace ghcr.io/syndbg/taskporter list

# Create an alias for easy use
alias taskporter='docker run -ti --rm -v $(pwd):/workspace -w /workspace ghcr.io/syndbg/taskporter'
taskporter list

📋 Linux Package Managers

Debian/Ubuntu:

# Download and install .deb package
curl -L -O https://github.com/syndbg/taskporter/releases/latest/download/taskporter_amd64.deb
sudo dpkg -i taskporter_amd64.deb

Red Hat/CentOS/Fedora:

# Download and install .rpm package
curl -L -O https://github.com/syndbg/taskporter/releases/latest/download/taskporter_x86_64.rpm
sudo rpm -i taskporter_x86_64.rpm

Alpine Linux:

# Download and install .apk package
curl -L -O https://github.com/syndbg/taskporter/releases/latest/download/taskporter_x86_64.apk
sudo apk add --allow-untrusted taskporter_x86_64.apk

🔧 Go Install

go install github.com/syndbg/taskporter@latest

🛠️ Build from Source

git clone https://github.com/syndbg/taskporter.git
cd taskporter
make build

Note: Taskporter uses semantic versioning with automatic releases based on conventional commits. New versions are automatically published when changes are merged to the main branch.

🚀 Quick Start

1. Navigate to your project with VSCode .vscode/ or JetBrains .idea/ directories
2. List available tasks:

   taskporter list
   

3. Run a task:

   taskporter run build
   taskporter run "Debug Application"
   taskporter run test --verbose
   # Or disable interactive mode for scripting:
   taskporter run --no-interactive
   

🔧 Shell Completion

Taskporter supports intelligent shell completion for commands, flags, and dynamic task names from your project configurations!

Quick Setup

Bash:

# Add to ~/.bashrc or ~/.bash_profile
source <(taskporter completion bash)

# Or install globally
taskporter completion bash > /etc/bash_completion.d/taskporter

Zsh:

# Add to ~/.zshrc
source <(taskporter completion zsh)

# Or add to your completion directory
taskporter completion zsh > "${fpath[1]}/_taskporter"

Fish:

# Add to ~/.config/fish/config.fish
taskporter completion fish | source

# Or install globally
taskporter completion fish > ~/.config/fish/completions/taskporter.fish

PowerShell:

# Add to your PowerShell profile
taskporter completion powershell | Out-String | Invoke-Expression

🎯 What Gets Completed

• Commands: list, run, completion
• Flags: --verbose, --output, --config, --no-interactive
• Flag Values: --output <TAB> shows text and json
• 🔥 Task Names: taskporter run <TAB> shows all available tasks from your project!

✨ Example Usage

taskporter run <TAB><TAB>
# Shows all your project tasks:
# build  test  clean  "Launch Server"  "Debug App"  "Run Main"

taskporter run b<TAB>
# Completes to "build"

taskporter list --output <TAB><TAB>
# Shows: text  json

The completion is context-aware - it reads your actual VSCode and JetBrains configurations to provide accurate task name suggestions!

📖 Usage Examples

VSCode Tasks Example

// .vscode/tasks.json
{
  "tasks": [
    {
      "label": "build",
      "type": "shell",
      "command": "go",
      "args": ["build", "-o", "bin/app"],
      "group": "build",
      "env": {
        "CGO_ENABLED": "0"
      }
    }
  ]
}

taskporter run build
# ✅ Strand established! Task 'build' completed successfully

VSCode Launch Configuration Example

// .vscode/launch.json
{
  "configurations": [
    {
      "name": "Launch Server",
      "type": "go",
      "request": "launch",
      "program": "${workspaceFolder}/cmd/server",
      "env": {
        "PORT": "8080"
      },
      "preLaunchTask": "build"
    }
  ]
}

taskporter run "Launch Server"
# Runs 'build' task first, then launches the server

JetBrains Run Configuration Example

<!-- .idea/runConfigurations/Application.xml -->
<component name="ProjectRunConfigurationManager">
  <configuration name="Run Main" type="Application">
    <option name="MAIN_CLASS_NAME" value="com.example.Main" />
    <option name="PROGRAM_PARAMETERS" value="--debug" />
    <envs>
      <env name="ENV" value="development" />
    </envs>
  </configuration>
</component>

taskporter run "Run Main"
# Executes the JetBrains Application configuration

🎛 CLI Reference

Commands

taskporter list

Lists all discovered tasks and launch configurations.

Flags:

• --verbose - Show detailed scanning information
• --json - Output in JSON format for CI/CD integration

Example Output:

📋 Discovered Tasks & Launch Configurations

VSCode Tasks (.vscode/tasks.json):
  • build [build] - go build -o bin/app
  • test [test] - go test ./...
  • lint [none] - golangci-lint run

VSCode Launch (.vscode/launch.json):
  • Launch Server [launch] - Launch: /path/to/cmd/server
  • Debug Tests [launch] - Launch: ${workspaceFolder}/cmd/test

JetBrains (.idea/runConfigurations/):
  • Run Main [run] - Application: com.example.Main
  • Gradle Build [run] - Gradle: build

✅ Found 7 configurations across 3 sources

taskporter run <task-name>

Executes the specified task or launch configuration.

Arguments:

• <task-name> - Name of task (supports exact, case-insensitive, and partial matching)

Flags:

• --verbose - Show environment variables and detailed execution info
• --no-interactive - Disable interactive mode (useful for CI/CD)

Examples:

# Exact match
taskporter run build

# Case-insensitive
taskporter run BUILD

# Partial match
taskporter run "launch"  # matches "Launch Server"

# With verbose output
taskporter run test --verbose

# Disable interactive mode (for CI/CD)
taskporter run --no-interactive

Global Flags

• --help - Show help information
• --version - Show version information

🏗 Supported Configurations

VSCode Tasks (tasks.json)

• ✅ All task types (shell, process, custom)
• ✅ Groups (build, test, etc.)
• ✅ Environment variables
• ✅ Working directory (cwd)
• ✅ Workspace variables (${workspaceFolder})
• ✅ Complex argument arrays

VSCode Launch Configurations (launch.json)

• ✅ Go launch configurations
• ✅ Node.js launch configurations
• ✅ Python launch configurations
• ✅ Environment variables
• ✅ PreLaunchTask execution
• ✅ Workspace variable resolution
• ✅ Program arguments

JetBrains Run Configurations (.idea/runConfigurations/*.xml)

• ✅ Application configurations
• ✅ Gradle configurations
• ✅ Environment variables
• ✅ Program parameters
• ✅ JetBrains variables ($PROJECT_DIR$, $MODULE_DIR$)
• ✅ Working directory

🤝 Contributing

We welcome contributions! Whether you're fixing bugs, adding features, improving documentation, or adding support for new IDEs, your help makes Taskporter better for everyone.

Get Started: See our comprehensive Contributing Guidelines for:

• Development setup and prerequisites
• Build commands and project structure
• Code style and testing guidelines
• How to add new IDE support
• Pull request process and review
• Architecture guidelines and design principles

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🎮 Death Stranding Inspiration

"A strand is a rope, a cord, a chain of connection. In Death Stranding, strands connect isolated cities. In Taskporter, strands connect isolated development tools."

Taskporter draws inspiration from Death Stranding's theme of connection and bridging isolated communities. Just as Sam Porter Bridges reconnects America, Taskporter reconnects your development workflow.

---

🌉 Bridge your development workflow. Connect your tools. Deliver your code.

Made with ❤️