Introduction

Welcome to the documentation for portctl!

portctl is a modern, high-performance CLI tool designed to help developers manage network ports and processes with ease. It eliminates the need to remember complex lsof or netstat commands and provides a safe, user-friendly interface for identifying and killing processes.

Key Features

• 🔍 Smart Process Discovery: Instantly find what's running on any port.
• ⚡ Fast & Safe Killing: Terminate processes by port or PID with safety checks.
• 🖥️ Interactive TUI: A beautiful terminal UI for browsing and managing processes.
• 👀 Real-time Monitoring: Watch ports for changes and get desktop notifications.
• 🛡️ Developer Focused: "Quick" commands to kill dev servers, find free ports, and clean up zombies.
• 📊 System Stats: Insight into system resource usage and port distribution.
• 🤖 AI Integration: MCP server support with .well-known metadata (mcp-manifest.jsonld, llms.txt, skills.txt).
• 🔒 Secure: SLSA attestations, dual SBOM generation (SPDX + CycloneDX), and comprehensive dependency tracking.

Installation

Homebrew (macOS/Linux)

brew install ckodex-labs/tap/portctl

Go Install

go install github.com/ckodex-labs/portctl@latest

Manual Download

Download the latest binary from the Releases Page.

Getting Started

Check out the Usage Guide to learn how to use the CLI commands.

For architectural details and design decisions, see the Architecture (arc42) section.

Usage Guide

portctl provides a suite of commands to manage network ports and processes.

Core Commands

list - List Processes

List processes that are currently listening on ports.

# List all processes with open ports
portctl list

# List processes on a specific port
portctl list 8080

# List all processes (explicit)
portctl list --all

Options:

• --json, -j: Output in JSON format for scripting.
• --all, -a: List all processes.
• --sort [field]: Sort by pid, port, cpu, memory, command, service, or user.
• --service [name]: Filter by service name (e.g., node, postgres).
• --user [name]: Filter by user name.

kill - Kill Processes

Kill processes by port or PID.

# Kill processes on port 8080
portctl kill 8080

# Kill process by PID
portctl kill --pid 12345

# Kill multiple ports
portctl kill 3000 8080 9000

Options:

• --pid, -p: Kill by PID instead of port.
• --force, -f: Force kill (SIGKILL on Unix, /F on Windows).
• --yes, -y: Skip confirmation prompt.
• --service [name]: Kill all processes matching a service name.
• --user [name]: Kill all processes owned by a user.
• --older [duration]: Kill processes older than a duration (e.g., 1h).

interactive - TUI Mode

Launch an interactive terminal user interface.

portctl interactive
# or alias
portctl tui

This mode allows you to:

• Browse processes with arrow keys.
• Filter list by typing /.
• View details by pressing Enter.
• Kill processes by pressing k.
• View system stats by pressing s.

watch - Real-time Monitoring

Watch ports for changes in real-time.

# Watch all ports
portctl watch

# Watch a specific port
portctl watch 8080

Options:

• --interval, -i: Refresh interval (default 3s).
• --notify, -n: Send desktop notifications on changes.
• --changes-only, -c: Only display output when changes occur.

scan - Port Scanning

Scan local or remote hosts for open ports.

# Scan localhost for common ports
portctl scan localhost --common

# Scan a specific range
portctl scan 192.168.1.1 1-1000

Options:

• --common: Scan top 20 common ports.
• --range, -r: Specify port range (e.g., 80,443,3000-4000).
• --timeout, -t: Connection timeout (default 3s).
• --concurrent, -c: Number of concurrent scans (default 50).

quick - Developer Shortcuts

Quick actions for common developer tasks.

# Kill all development servers (ports 3000-9999)
portctl quick kill-dev

# Kill all Node.js processes
portctl quick kill-node

# Find next available port and export it
portctl quick next-port

available - Find Free Ports

Find available ports for binding.

# Find 10 free ports starting from 3000
portctl available

# Find in specific range
portctl available --start 8000 --end 9000

stats - System Statistics

View system resource usage and port statistics.

portctl stats

Global Flags

• --help, -h: Show help for any command.
• --version, -v: Show version information.

CI/CD Pipeline & Release Process

This document describes the automated CI/CD pipeline and release process for portctl.

Overview

The portctl project uses Dagger for all CI/CD automation, providing a modular, reproducible, and platform-agnostic pipeline. All build, test, and release steps are defined as Dagger functions in .dagger/main.go.

Pipeline Architecture

Dagger Functions

All pipeline steps are callable via dagger call <function>:

# Core development workflow
dagger call lint --src=.                    # Run golangci-lint
dagger call test --src=.                    # Run Go tests
dagger call build --src=.                   # Build binary

# Release workflow
dagger call generate-manifest --src=.       # Generate MCP manifest
dagger call release --src=. export --path=./artifacts  # Release with GoReleaser
dagger call publish-image --src=.           # Publish Docker images

# Quality & Security
dagger call security-scan --src=.           # Run gosec security scan
dagger call sbom --src=.                    # Generate SBOM
dagger call snapshot-test --src=.           # Run snapshot tests
dagger call well-known --src=.              # Validate .well-known metadata

# Documentation
dagger call docs --src=.                    # Build mdBook documentation
dagger call publish-docs --src=.            # Publish to GitHub Pages

GitHub Actions Workflows

CI Workflow (.github/workflows/ci.yml)

Runs on every push and pull request:

• Linting with golangci-lint
• Unit tests with coverage
• Security scanning with gosec
• SBOM generation
• Documentation build

Release Workflow (.github/workflows/release.yml)

Triggered on version tags (e.g., v1.0.1):

1. Validation: Runs lint and test steps
2. Build & Release:
   • Runs GoReleaser to build multi-platform binaries
   • Generates SBOM and SLSA attestations
   • Creates GitHub release with artifacts
   • Updates Homebrew tap
3. Artifact Export: Exports artifacts to host filesystem for upload
4. Docker Publishing: Builds and publishes multi-arch images to GHCR
5. Artifact Upload: Uploads artifacts to GitHub Actions

Release Process

Creating a Release

1. Ensure all changes are committed and pushed:

   git add .
   git commit -m "feat: your changes"
   git push origin main
   

2. Create and push a version tag:

   # For a patch release (bug fixes)
   git tag -a v1.0.1 -m "Release v1.0.1"
   
   # For a minor release (new features)
   git tag -a v1.1.0 -m "Release v1.1.0"
   
   # For a major release (breaking changes)
   git tag -a v2.0.0 -m "Release v2.0.0"
   
   git push origin <tag-name>
   

3. Monitor the release workflow:

   • Go to https://github.com/ckodex-labs/portctl/actions
   • Watch the "Release" workflow run
   • Verify all steps complete successfully

What Gets Released

Each release includes:

• Multi-platform binaries: Linux, macOS, Windows (amd64, arm64)
• Docker images: Published to ghcr.io/ckodex-labs/portctl with tags:
  • latest - Always points to the latest release
  • v1.0.x - Specific version tag
• Security & Compliance Artifacts:
  • *.sbom.spdx.json - Software Bill of Materials in SPDX format
  • *.sbom.cyclonedx.json - Software Bill of Materials in CycloneDX format
  • *.intoto.jsonl - SLSA provenance attestations (in-toto format)
• AI Integration Metadata (.well-known/ folder):
  • mcp-manifest.jsonld - Model Context Protocol server manifest
  • llms.txt - LLM guidance and context for AI agents
  • skills.txt - Capability descriptions for MCP tools
• Homebrew formula: Automatically updated in ckodex-labs/homebrew-tap

Artifact Publishing

The release workflow exports artifacts from Dagger containers to the GitHub Actions runner:

- name: Build and Release
  run: dagger call release --src=. --github-token=env:GITHUB_TOKEN --tap-github-token=env:TAP_GITHUB_TOKEN export --path=./artifacts

- name: Upload Artifacts
  uses: actions/upload-artifact@v4
  with:
    name: release-artifacts
    path: ./artifacts

The export --path=./artifacts command writes the Dagger directory to the host filesystem, making artifacts available for upload.

Local Testing

Test the release process locally before pushing tags:

# Set required environment variables
export GITHUB_TOKEN="your-github-token"
export TAP_GITHUB_TOKEN="your-tap-token"

# Test the release build (without publishing)
dagger call release --src=. --github-token=env:GITHUB_TOKEN --tap-github-token=env:TAP_GITHUB_TOKEN export --path=./artifacts

# Verify artifacts were created
ls -la ./artifacts

Security & Compliance

SLSA Provenance

All releases include SLSA (Supply chain Levels for Software Artifacts) provenance attestations:

• Build provenance is generated by GoReleaser
• Attestations are signed and published with releases
• Verifiable supply chain security

SBOM (Software Bill of Materials)

Each release includes a comprehensive SBOM:

• Generated using Syft
• Lists all dependencies and their versions
• Helps with vulnerability tracking and compliance

SLSA Level 3 Compliance

portctl achieves SLSA Level 3 through:

• Signed provenance: GoReleaser generates signed .intoto.jsonl attestations
• Cosign signatures: All artifacts are cryptographically signed with keyless signing
• SBOM generation: Comprehensive dependency tracking with Syft
• Hardened build: GitHub Actions with OIDC authentication

Verifying Signatures

Download and verify a release artifact:

# Download artifacts
wget https://github.com/ckodex-labs/portctl/releases/download/v1.0.2/portctl_linux_amd64.tar.gz
wget https://github.com/ckodex-labs/portctl/releases/download/v1.0.2/portctl_linux_amd64.tar.gz.sig
wget https://github.com/ckodex-labs/portctl/releases/download/v1.0.2/portctl_linux_amd64.tar.gz.cert

# Verify with Cosign
cosign verify-blob \
  --certificate portctl_linux_amd64.tar.gz.cert \
  --signature portctl_linux_amd64.tar.gz.sig \
  --certificate-identity-regexp="https://github.com/ckodex-labs/portctl" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  portctl_linux_amd64.tar.gz

Verifying SLSA Provenance

# Download provenance
wget https://github.com/ckodex-labs/portctl/releases/download/v1.0.2/portctl_checksums.txt.intoto.jsonl

# Inspect provenance
cat portctl_checksums.txt.intoto.jsonl | jq

Documentation Publishing

Documentation is built with mdBook and published to GitHub Pages:

# Build documentation locally
dagger call docs --src=.

# Publish to GitHub Pages (requires GITHUB_TOKEN)
dagger call publish-docs --src=.

The documentation is automatically published on every release.

Troubleshooting

Release Workflow Fails

1. Check the GitHub Actions logs for specific errors
2. Verify all required secrets are set:
   • GITHUB_TOKEN (automatically provided)
   • TAP_GITHUB_TOKEN (for Homebrew tap updates)
3. Ensure the tag follows semantic versioning (e.g., v1.0.1)

Artifacts Not Uploaded

The artifact export mechanism requires:

• Dagger Release function returns *dagger.Directory
• Workflow uses export --path=./artifacts
• Upload step references the correct path

Docker Publishing Fails

Verify:

• GitHub Container Registry permissions are configured
• GITHUB_TOKEN has packages: write permission
• Multi-arch build platforms are supported

Best Practices

1. Test locally first: Always test builds locally before creating tags
2. Follow semantic versioning: Use appropriate version numbers
3. Write clear release notes: Document changes in tag messages
4. Monitor workflows: Watch GitHub Actions to catch issues early
5. Verify artifacts: Download and test released artifacts

Architecture Documentation

This section provides architectural documentation for portctl following the arc42 template.

Introduction and Goals

Requirements Overview

portctl is a secure, cross-platform CLI tool designed to simplify port and process management for developers. It addresses the common pain point of identifying and terminating processes occupying specific ports during development.

Key Requirements:

• Cross-platform compatibility: Works on macOS, Linux, and Windows
• Security: Safe process termination with confirmation prompts
• Developer experience: Intuitive commands, interactive TUI, real-time monitoring
• AI integration: MCP server support for AI agent interaction
• Automation: JSON output for scripting and CI/CD integration

Quality Goals

Stakeholders

Architecture Constraints

Technical Constraints

Organizational Constraints

System Scope and Context

Business Context

┌─────────────┐
│  Developer  │
└──────┬──────┘
       │ CLI commands
       ▼
┌─────────────────┐
│    portctl      │
└──────┬──────────┘
       │
       ├─► OS Process Manager (kill signals)
       ├─► Network Stack (lsof/netstat)
       └─► Terminal (TUI rendering)

Technical Context

External Interfaces:

1. Operating System APIs

   • Process management (signals, PIDs)
   • Network information (lsof, netstat, /proc)
   • Terminal control (for TUI)

2. User Interfaces

   • CLI (Cobra framework)
   • TUI (Bubble Tea framework)
   • JSON output for scripting

3. AI Integration

   • MCP (Model Context Protocol) server
   • .well-known metadata files

Solution Strategy

Technology Decisions

Architectural Patterns

1. Command Pattern: Each CLI command is a separate handler with clear responsibilities
2. Adapter Pattern: Platform-specific process managers (macOS/Linux/Windows) implement common interface
3. Observer Pattern: Watch mode uses polling with notification callbacks
4. Repository Pattern: Process information is abstracted behind ProcessManager interface

Building Block View

Level 1: System Overview

┌────────────────────────────────────────────────┐
│                   portctl                      │
├────────────────────────────────────────────────┤
│  CLI Layer (Cobra)                             │
│  ├─ list, kill, watch, scan, stats, tui        │
├────────────────────────────────────────────────┤
│  Business Logic                                │
│  ├─ ProcessManager                             │
│  ├─ PortScanner                                │
│  ├─ Notifier                                   │
├────────────────────────────────────────────────┤
│  Platform Adapters                             │
│  ├─ macOS (lsof)                               │
│  ├─ Linux (lsof, /proc)                        │
│  ├─ Windows (netstat)                          │
└────────────────────────────────────────────────┘

Level 2: Component Details

ProcessManager

• Responsibility: Abstract process listing and termination
• Interface:

  type ProcessManager interface {
      GetAllProcesses() ([]Process, error)
      GetProcessesOnPort(port int) ([]Process, error)
      KillProcess(pid int, force bool) error
  }
  

CLI Commands

• list: Query and display processes
• kill: Terminate processes by port or PID
• watch: Real-time monitoring with notifications
• scan: Port scanning (local/remote)
• tui: Interactive terminal UI
• stats: System resource statistics

Runtime View

Scenario: Kill Process on Port

User                CLI              ProcessManager      OS
  │                  │                     │             │
  │─ portctl kill 8080 ──────────────────►│             │
  │                  │                     │             │
  │                  │──GetProcessesOnPort(8080)────────►│
  │                  │◄─────────────[Process{pid:1234}]──│
  │                  │                     │             │
  │◄─Confirm kill?───│                     │             │
  │─ yes ───────────►│                     │             │
  │                  │──KillProcess(1234)──────────────►│
  │                  │◄─────────────success──────────────│
  │◄─Success─────────│                     │             │

Deployment View

Distribution Channels

1. Homebrew (macOS/Linux)

   brew install ckodex-labs/tap/portctl
   

2. Direct Download (All platforms)

   • GitHub Releases with signed binaries
   • Multi-arch support (amd64, arm64)

3. Docker (Containerized environments)

   docker pull ghcr.io/ckodex-labs/portctl:latest
   

4. Go Install (Developers)

   go install github.com/ckodex-labs/portctl@latest
   

Infrastructure

┌─────────────────────────────────────────┐
│          GitHub Repository              │
├─────────────────────────────────────────┤
│  - Source Code                          │
│  - CI/CD (GitHub Actions + Dagger)      │
│  - Releases (GoReleaser)                │
│  - Container Registry (GHCR)            │
│  - Documentation (GitHub Pages)         │
└─────────────────────────────────────────┘

Cross-cutting Concepts

Security

• Process Isolation: Only kills processes owned by current user (unless sudo)
• Confirmation Prompts: Prevents accidental termination
• Input Validation: All user inputs are validated and sanitized
• SLSA Level 3 Compliance: Signed build provenance and attestations for supply chain security

SBOM (Software Bill of Materials)

Each release includes comprehensive SBOMs in both industry-standard formats:

• SPDX format: *.sbom.spdx.json - Linux Foundation standard
• CycloneDX format: *.sbom.cyclonedx.json - OWASP standard
• Generated using Syft (via GoReleaser)
• Lists all dependencies and their versions
• Helps with vulnerability tracking and compliance
• Compatible with different security scanning tools

Signed Releases

Release signing with Cosign:

• Cosign integration enabled in .goreleaser.yml
• Keyless signing using GitHub OIDC (COSIGN_EXPERIMENTAL=1)
• Generates .sig signature files and .cert certificates
• Provides cryptographic proof of artifact integrity
• Verifiable with cosign verify-blob command

Verification Example:

cosign verify-blob \
  --certificate portctl_linux_amd64.tar.gz.cert \
  --signature portctl_linux_amd64.tar.gz.sig \
  portctl_linux_amd64.tar.gz

AI Integration Metadata (.well-known/)

The project includes AI-native metadata for agent integration:

• mcp-manifest.jsonld: Model Context Protocol server manifest (JSON-LD format)
• llms.txt: LLM guidance and context for AI agents
• skills.txt: Capability descriptions for MCP tools
• Published to GitHub Pages at /.well-known/ path
• Included in release archives for offline access

Error Handling

• Graceful Degradation: Falls back to alternative methods if primary fails
• User-Friendly Messages: Clear error messages with suggested actions
• Logging: Structured logging for debugging (optional verbose mode)

Testing Strategy

• Unit Tests: Core business logic (80%+ coverage)
• Integration Tests: Platform-specific adapters
• BDD Tests: User scenarios with Godog
• Snapshot Tests: CLI output validation

Design Decisions

ADR-001: Use Go for Implementation

Status: Accepted

Context: Need cross-platform CLI tool with minimal dependencies

Decision: Use Go as primary language

Consequences:

• ✅ Single binary distribution
• ✅ Excellent cross-platform support
• ✅ Fast compilation and execution
• ❌ Larger binary size than scripting languages

ADR-002: Dagger for CI/CD

Status: Accepted

Context: Need reproducible builds across local and CI environments

Decision: Use Dagger for all CI/CD pipelines

Consequences:

• ✅ Local-remote parity
• ✅ Portable pipeline definitions
• ✅ Container-based isolation
• ❌ Learning curve for contributors

ADR-003: MCP Server Integration

Status: Accepted

Context: Enable AI agent interaction with port management

Decision: Implement MCP server alongside CLI

Consequences:

• ✅ AI-native tool design
• ✅ Future-proof for AI workflows
• ✅ Programmatic access
• ❌ Additional maintenance surface

Quality Requirements

Performance

• Process listing: <100ms for typical workloads
• TUI refresh rate: 60 FPS
• Memory footprint: <50MB

Security

• SLSA Level 4 compliance
• Signed releases with provenance
• No privilege escalation vulnerabilities

Maintainability

• 80%+ test coverage
• Clear module boundaries
• Comprehensive documentation

Risks and Technical Debt

Known Technical Debt

1. Windows Support: Less mature than macOS/Linux implementations
2. Test Coverage: Some edge cases not fully covered
3. Documentation: Some advanced features lack detailed examples

Glossary