### Setup Project with .env File Generation

Source: https://github.com/bendechrai/devports/blob/main/QUICKSTART.md

Automate project setup by creating a .env.devports template file and running the `devports setup` command. This command allocates necessary ports and generates a .env file with the allocated port values embedded.

```bash
# Create a template file first
cat > .env.devports <<EOF
DEVPORTS_PROJECT_NAME=myproject
DATABASE_URL=postgresql://user:pass@localhost:{devports:postgres:db}/myapp
API_PORT={devports:api:server}
API_URL=https://{devports:project}.example.com
EOF

# Run setup to allocate ports and generate .env
devports setup
# → ✅ Setting up myproject...
# → 📍 Detected services: db, server
# → 🔌 Allocated ports: db: 5432, server: 3000
# → 📝 Generated .env from .env.devports

# Check your new .env file
cat .env
# → DATABASE_URL=postgresql://user:pass@localhost:5432/myapp
# → API_PORT=3000
```

--------------------------------

### Development Setup and Verification (Bash)

Source: https://github.com/bendechrai/devports/blob/main/CONTRIBUTING.md

This snippet guides through cloning the repository, installing dependencies, building the project, linking it locally for testing, and verifying the installation by checking the version.

```bash
git clone https://github.com/bendechrai/devports.git
cd devports
npm install

npm run build
npm link

devports --version

npm test
```

--------------------------------

### Pattern 1: New Project Setup with .env

Source: https://github.com/bendechrai/devports/blob/main/QUICKSTART.md

A common pattern for setting up a new project where ports are allocated for specific services (e.g., postgres, api) and their values are saved into a .env file.

```bash
PROJECT=$(basename $(pwd))

# Allocate needed ports
POSTGRES_PORT=$(devports allocate "$PROJECT" postgres --type postgres --quiet)
API_PORT=$(devports allocate "$PROJECT" api --type api --quiet)

# Save to .env
cat > .env <<EOF
DATABASE_PORT=$POSTGRES_PORT
API_PORT=$API_PORT
EOF
```

--------------------------------

### Install Devports Globally or Locally

Source: https://github.com/bendechrai/devports/blob/main/QUICKSTART.md

Install the devports CLI globally for system-wide access or locally as a development dependency for a specific project. The global installation is recommended for ease of use.

```bash
npm install -g devports
devports --version
```

```bash
npm install --save-dev devports
npx devports --version
```

--------------------------------

### Setup Git Worktree with Unique Ports

Source: https://github.com/bendechrai/devports/blob/main/AI-ASSISTANT-GUIDE.md

This example shows how to set up a Git worktree for a new feature branch. It then navigates into the new worktree and allocates a unique port for PostgreSQL, writing it to a `.env` file within that worktree.

```bash
# Create worktree with unique ports
WORKTREE="feature-auth"
git worktree add "../$WORKTREE" -b "$WORKTREE"

cd "../$WORKTREE"
PORT=$(devports allocate "$WORKTREE" postgres --type postgres --quiet)
echo "DATABASE_PORT=$PORT" > .env
```

--------------------------------

### Devports Command Reference

Source: https://github.com/bendechrai/devports/blob/main/QUICKSTART.md

A comprehensive list of available devports commands, including their syntax, parameters, and optional flags for managing ports.

```bash
# Allocate
devports allocate <project> <service> [--type <type>] [--quiet] [--json]

# Release
devports release <project> [service] [--all] [--quiet] [--json]
devports release <port> --port  # Release by port number

# List
devports list [--project <n>] [--type <type>] [--quiet] [--json]

# Status
devports status [--quiet] [--json]

# Check
devports check <port> [--quiet] [--json]

# Info
devports info [--json]

# Reserve
devports reserve <port> [reason]
devports unreserve <port>
```

--------------------------------

### Run Programmatic Node.js Devports Example

Source: https://github.com/bendechrai/devports/blob/main/examples/README.md

Shows how to utilize the devports Node.js API programmatically. This example requires Node.js version 18 or higher and assumes devports has been installed.

```bash
# After installing devports
node examples/programmatic.mjs

```

--------------------------------

### Import Existing Port Allocations

Source: https://github.com/bendechrai/devports/blob/main/QUICKSTART.md

Import manually assigned port allocations into devports by copying and editing the provided example script (`import-example.mjs`). This allows devports to manage previously unrecorded ports.

```bash
# Copy and edit the example script
cp node_modules/devports/scripts/import-example.mjs ./import-ports.mjs

# Edit import-ports.mjs - add your allocations like:
# { port: 5432, project: 'myapp', service: 'postgres', type: 'postgres' }

# Run the import
node import-ports.mjs

# Verify
devports list
```

--------------------------------

### Troubleshooting Common Devports Issues

Source: https://github.com/bendechrai/devports/blob/main/QUICKSTART.md

Solutions for common problems encountered when using devports, including 'command not found', ports already being allocated, and scenarios where no ports are available.

```bash
**Command not found:**
```bash
npm install -g devports
```

**Port already allocated:**
```bash
devports list
devports release <project> <service>
```

**No ports available:**
```bash
devports status
devports list --type postgres
```
```

--------------------------------

### Make Example Scripts Executable

Source: https://github.com/bendechrai/devports/blob/main/examples/README.md

A bash command to grant execute permissions to all example scripts in the 'examples' directory, including both .sh and .mjs files. This is a prerequisite for running the examples.

```bash
chmod +x examples/*.sh examples/*.mjs

```

--------------------------------

### Run JSON Parsing Devports Example

Source: https://github.com/bendechrai/devports/blob/main/examples/README.md

Illustrates how to parse devports output using the `--json` flag with the `jq` command-line JSON processor. Requires bash and jq.

```bash
./examples/json-parsing.sh

```

--------------------------------

### Main Clone Setup with Devports

Source: https://github.com/bendechrai/devports/blob/main/README.md

Demonstrates how to use the `devports setup` command to initialize a main repository clone, optionally using a custom template or forcing an overwrite.

```bash
# Basic setup using default configurations
devports setup

# Setup using a custom template file (e.g., .env.devports)
devports setup --template .env.devports

# Force setup, overwriting existing files (creates .env.backup)
devports setup --force
```

--------------------------------

### Run Basic Devports CLI Example

Source: https://github.com/bendechrai/devports/blob/main/examples/README.md

Executes a bash script demonstrating basic devports operations such as allocation, listing, and releasing ports. This script is self-contained and cleans up after itself.

```bash
./examples/basic.sh

```

--------------------------------

### Copy and Modify Devports Example Script

Source: https://github.com/bendechrai/devports/blob/main/examples/README.md

Provides a bash snippet for copying an existing example script (e.g., 'basic.sh') to a new file ('my-script.sh') and then running the modified script. This facilitates customization for personal use cases.

```bash
cp examples/basic.sh my-script.sh
# Edit my-script.sh
./my-script.sh

```

--------------------------------

### Auto-render docker-compose.yml.devports

Source: https://github.com/bendechrai/devports/blob/main/README.md

This YAML example shows a `docker-compose.yml.devports` template. `devports setup` will render this file into `docker-compose.yml`, substituting placeholders with actual allocated ports and project names.

```yaml
# docker-compose.yml.devports
services:
  db:
    image: postgres:15
    ports:
      - "{devports:postgres:db}:5432"
    container_name: {devports:project}-db

  app:
    build: .
    ports:
      - "{devports:api:server}:3000"
    container_name: {devports:project}-app
```

--------------------------------

### Basic Devports Operations: Allocate, Status, List, Release

Source: https://github.com/bendechrai/devports/blob/main/QUICKSTART.md

Perform core port management tasks: allocate a new port for a project and service, check the overall status, list current allocations, and release ports when they are no longer needed.

```bash
# Allocate your first port
devports allocate myproject postgres --type postgres
# → ✅ Allocated port 5432 for myproject/postgres

# Check status
devports status

# List allocations
devports list

# Release when done
devports release myproject postgres
```

--------------------------------

### Devports Template File Format Example

Source: https://context7.com/bendechrai/devports/llms.txt

Illustrates the format of devports template files, showing how to use placeholders for port allocation and project names in common configuration file types.

```bash
# .env.devports template example
DEVPORTS_PROJECT_NAME=myproject
DATABASE_URL=postgresql://user:pass@localhost:{devports:postgres:db}/myapp
API_PORT={devports:api:server}
REDIS_URL=redis://localhost:{devports:redis:cache}
APP_URL=https://{devports:project}-api.example.com

# docker-compose.yml.devports template example
# services:
#   db:
#     image: postgres:15
#     ports:
#       - "{devports:postgres:db}:5432"
#     container_name: {devports:project}-db
#   app:
#     build: .
#     ports:
#       - "{devports:api:server}:3000"
#     container_name: {devports:project}-app
```

--------------------------------

### Run Git Worktree Devports Example

Source: https://github.com/bendechrai/devports/blob/main/examples/README.md

Demonstrates integrating devports with Git worktrees. This bash script automatically allocates ports when creating a new Git worktree for a specified feature branch. Requires bash and git.

```bash
./examples/worktree.sh feature/my-feature

```

--------------------------------

### Install Shell Completion for Devports CLI

Source: https://github.com/bendechrai/devports/blob/main/README.md

Automatically installs shell completion for devports, detecting and updating the appropriate shell configuration file (.zshrc or .bashrc). This simplifies the setup process for users.

```bash
# Automatic setup for your shell (detects zsh/bash)
devports completion --install

# Then start a new terminal or reload your shell config
```

--------------------------------

### Install and Verify Devports CLI

Source: https://github.com/bendechrai/devports/blob/main/README.md

Installs the devports command-line interface globally using npm and then verifies the installation by checking the version.

```bash
# Install devports globally
npm install -g devports

# Verify installation
devports --version
```

--------------------------------

### Example devports Configuration JSON

Source: https://github.com/bendechrai/devports/blob/main/AI-ASSISTANT-GUIDE.md

This JSON object shows an example configuration for `devports`. It defines port ranges for various service types (postgres, mysql, redis, api, app, custom) and specifies the path to the registry file.

```json
{
  "ranges": {
    "postgres": { "start": 5434, "end": 5499 },
    "mysql": { "start": 3308, "end": 3399 },
    "redis": { "start": 6381, "end": 6399 },
    "api": { "start": 3002, "end": 3099 },
    "app": { "start": 5002, "end": 5999 },
    "custom": { "start": 8002, "end": 8999 }
  },
  "registryPath": "~/.config/devports/ports.json"
}
```

--------------------------------

### Devports Flags Reference

Source: https://github.com/bendechrai/devports/blob/main/QUICKSTART.md

Explanation of common flags used with devports commands to modify their behavior, such as controlling output verbosity, enabling JSON output, specifying port types, and applying actions to all services.

```bash
- `--quiet` / `-q`: Minimal output (for scripting)
- `--json`: JSON output (for parsing)
- `--type` / `-t`: Specify port type
- `--all` / `-a`: Apply to all services
```

--------------------------------

### Environment Variable Naming Convention Example

Source: https://github.com/bendechrai/devports/blob/main/DOCKER.md

Illustrates a recommended naming convention for environment variables in a development context, distinguishing between internal (service-to-service) and external (host-accessible) configurations, and including convenience variables.

```bash
# Internal (unchanged)
DATABASE_URL=postgresql://user:pass@db:5432/mydb

# External (port-mapped)
MCP_DATABASE_URL=postgresql://readonly:pass@localhost:{devports:postgres:database}/mydb

# Convenience
DB_PORT=5433  # Added automatically
```

--------------------------------

### Troubleshoot Devports CLI Installation

Source: https://github.com/bendechrai/devports/blob/main/README.md

Provides solutions for common devports CLI installation issues, such as the command not being found. It suggests checking the global npm installation.

```bash
npm install -g devports
# Or check: npm list -g devports
```

--------------------------------

### Pattern 4: CI/CD Ephemeral Port Allocation

Source: https://github.com/bendechrai/devports/blob/main/QUICKSTART.md

Allocate ephemeral ports for CI/CD pipelines. This pattern demonstrates allocating ports for testing environments, setting them as environment variables, running tests, and then cleaning up the allocated ports.

```bash
# Allocate ephemeral ports for testing
TEST_ID="ci-$BUILD_NUMBER"

DB_PORT=$(devports allocate "$TEST_ID" db --quiet)
export DATABASE_URL="postgresql://user:pass@localhost:$DB_PORT/test"

# Run tests...

# Cleanup
devports release "$TEST_ID" --all --quiet
```

--------------------------------

### Shell Script Example: Allocating Ports and Creating .env

Source: https://github.com/bendechrai/devports/blob/main/README.md

A bash script that automatically allocates PostgreSQL and API ports using devports, then creates a .env file with these ports and a database connection URL.

```bash
#!/bin/bash
PROJECT=$(basename $(pwd))

# Allocate ports using devports
POSTGRES_PORT=$(devports allocate "$PROJECT" postgres --type postgres --quiet)
API_PORT=$(devports allocate "$PROJECT" api --type api --quiet)

# Write port information to a .env file
cat > .env <<EOF
DATABASE_PORT=$POSTGRES_PORT
API_PORT=$API_PORT
DATABASE_URL=postgresql://user:pass@localhost:$POSTGRES_PORT/db
EOF

echo "✅ Ports allocated: PG=$POSTGRES_PORT, API=$API_PORT"
```

--------------------------------

### Pattern 2: Git Worktree Port Management

Source: https://github.com/bendechrai/devports/blob/main/QUICKSTART.md

Manage unique ports for different git worktrees. This pattern shows how to create a worktree, allocate ports specific to that worktree's project name, and then clean up by releasing ports and removing the worktree.

```bash
# Create worktree with unique ports
WORKTREE="feature-auth"
git worktree add "../$WORKTREE" -b "$WORKTREE"

cd "../$WORKTREE"
POSTGRES_PORT=$(devports allocate "$WORKTREE" postgres --type postgres --quiet)
echo "DATABASE_PORT=$POSTGRES_PORT" > .env

# Cleanup later
devports release "$WORKTREE" --all
git worktree remove "../$WORKTREE"
```

--------------------------------

### Create .env.devports Template

Source: https://github.com/bendechrai/devports/blob/main/README.md

This bash script demonstrates creating a `.env.devports` template file. It uses placeholders like `{devports:type:service-name}` which are replaced by `devports setup` with allocated ports.

```bash
# .env.devports
DEVPORTS_PROJECT_NAME=myproject
DATABASE_URL=postgresql://user:pass@localhost:{devports:postgres:db}/myapp
API_PORT={devports:api:server}
REDIS_URL=redis://localhost:{devports:redis:cache}
API_URL=https://{devports:project}-api.example.com
```

--------------------------------

### Troubleshoot 'devports command not found'

Source: https://github.com/bendechrai/devports/blob/main/AI-ASSISTANT-GUIDE.md

This snippet provides commands to check if `devports` is installed globally, install it if necessary, or use `npx` to run it without a global installation.

```bash
# Check if installed globally
npm list -g devports

# If not, install
npm install -g devports

# Or use npx
npx devports --version
```

--------------------------------

### Install and Check devports CLI

Source: https://github.com/bendechrai/devports/blob/main/AI-ASSISTANT-GUIDE.md

Commands to check if devports is installed, display its version and help information, and install shell completion for Zsh and Bash. These are essential for verifying the tool's presence and setting up user-friendly command-line interactions.

```bash
# Check if devports is installed
which devports

# Show version and help
devports --version
devports --help

# Install shell completion for better UX
devports completion zsh --install  # macOS default
devports completion bash --install # Linux default

```

--------------------------------

### devports Docker Post-Hook Setup

Source: https://github.com/bendechrai/devports/blob/main/DOCKER.md

Commands to create and make executable the `docker-post-hook.sh` script within the `.devports/hooks` directory. This hook is automatically run by devports to update container names.

```bash
mkdir -p .devports/hooks
cp examples/docker-post-hook.sh .devports/hooks/post-worktree
chmod +x .devports/hooks/post-worktree
```

--------------------------------

### Import Existing Allocations using MJS Script

Source: https://github.com/bendechrai/devports/blob/main/README.md

This snippet demonstrates how to copy an example MJS script, define existing port allocations in a JavaScript array, and then run the script to import these allocations. It's useful for migrating manual port assignments into devports.

```bash
cp node_modules/devports/scripts/import-example.mjs ./import-ports.mjs
```

```javascript
const EXISTING_ALLOCATIONS = [
  { port: 5432, project: 'myapp', service: 'postgres', type: 'postgres' },
  { port: 3001, project: 'myapp', service: 'api', type: 'api' },
];
```

```bash
node import-ports.mjs
```

--------------------------------

### Devports CLI Usage: Basic Commands

Source: https://github.com/bendechrai/devports/blob/main/README.md

Provides an overview of essential devports commands for project setup, port allocation, release, listing, status checking, and template rendering.

```bash
# Set up the current directory
devports setup [--template <file>] [--force] [--skip-render]

# Allocate a port for a project and service
devports allocate <project> <service> --type <type>

# Release port(s) for a project
devports release <project> [service] [--all]

# List port allocations, optionally filtered by project or type
devports list [--project <name>] [--type <type>]

# Check port availability
devports status
devports check <port>

# Render a template file
devports render <file> [--output <file>]

# Manage .gitignore entries
devports gitignore [--preview]

# Display configuration information
devports info
```

--------------------------------

### Testing Port Allocation Logic (TypeScript)

Source: https://github.com/bendechrai/devports/blob/main/CONTRIBUTING.md

This example demonstrates a unit test written in TypeScript using Vitest to verify the functionality of the `allocatePort` function. It checks if different port types are allocated within their specified ranges.

```typescript
it('should allocate different port types in correct ranges', async () => {
  const pgPort = await allocatePort('test', 'postgres', 'postgres');
  const apiPort = await allocatePort('test', 'api', 'api');

  expect(pgPort).toBeGreaterThanOrEqual(5432);
  expect(pgPort).toBeLessThanOrEqual(5499);
  expect(apiPort).toBeGreaterThanOrEqual(3000);
  expect(apiPort).toBeLessThanOrEqual(3099);
});
```

--------------------------------

### Check Allocated Ports for a Project

Source: https://github.com/bendechrai/devports/blob/main/AI-ASSISTANT-GUIDE.md

This script checks if any ports are currently allocated for the 'myapp' project. If ports are allocated, it lists them; otherwise, it suggests running a setup script.

```bash
# Check what ports are in use for a project
if devports list --project myapp --json | jq -e 'length > 0' > /dev/null; then
  echo "Project has allocated ports:"
  devports list --project myapp
else
  echo "No ports allocated. Run setup script."
fi
```

--------------------------------

### Check devports Installation

Source: https://github.com/bendechrai/devports/blob/main/AI-ASSISTANT-GUIDE.md

Verify if devports is installed and accessible by checking its version. This is a fundamental step before attempting to use any devports commands.

```bash
devports --version
```

--------------------------------

### Generate and Install Shell Completion (devports completion)

Source: https://github.com/bendechrai/devports/blob/main/README.md

Generates and installs shell completion scripts for bash and zsh. Supports automatic installation, uninstallation, checking status, and testing. JSON output is available.

```bash
devports completion [shell] [options]

Arguments:
  shell                  Shell type (bash, zsh) - defaults to zsh

Options:
  -i, --install         Install completion script and setup shell config automatically
  -u, --uninstall       Remove completion script and clean shell config
  --check               Check if completion is already installed
  --test                Test if completion works in a fresh shell
  --json                Output as JSON
```

--------------------------------

### Test Worktree Creation and Verification with Devports

Source: https://github.com/bendechrai/devports/blob/main/DOCKER.md

This snippet demonstrates how to create a new worktree using devports, add a branch, and then verify the setup by checking the .env file and Docker Compose configuration within the new worktree. It's a crucial step for testing new configurations.

```bash
# Test the setup
devports worktree add ../test-worktree -b test/devports-setup

# Verify results
cd ../test-worktree
cat .env
docker-compose config  # Check resolved configuration
```

--------------------------------

### Skip Auto-rendering with devports

Source: https://github.com/bendechrai/devports/blob/main/README.md

This command skips the automatic rendering of *.devports files during the setup process. It's useful when you want to manually control configuration generation.

```bash
devports setup --skip-render
```

--------------------------------

### Basic Docker Compose Setup (Problematic)

Source: https://github.com/bendechrai/devports/blob/main/DOCKER.md

A standard docker-compose.yml file that leads to port and container naming conflicts when used across multiple Git worktrees. It directly maps host ports and uses fixed container names.

```yaml
version: '3.8'
services:
  db:
    image: postgres:15
    container_name: myproject-db
    ports:
      - '5432:5432'
    environment:
      POSTGRES_DB: mydb
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password

  api:
    build: .
    container_name: myproject-api
    ports:
      - '3000:3000'
    depends_on:
      - db
    environment:
      DATABASE_URL: postgresql://user:password@db:5432/mydb
```

--------------------------------

### Project Naming for Conflict Avoidance

Source: https://github.com/bendechrai/devports/blob/main/README.md

These examples show how to name projects to avoid conflicts, especially when multiple projects share similar branch names. Using project-specific identifiers or including the project name in the identifier are recommended strategies.

```bash
# Use project-specific identifiers
devports allocate "myproject-feature-auth" postgres --type postgres
devports allocate "otherproject-feature-auth" postgres --type postgres
```

```bash
# Include project name in identifier
PROJECT=$(basename $(pwd))
devports allocate "$PROJECT-$BRANCH" postgres --type postgres
```

--------------------------------

### Tailscale Funnel Dynamic Subdomain Generation

Source: https://github.com/bendechrai/devports/blob/main/DOCKER.md

This example illustrates how to generate dynamic subdomains for Tailscale Funnel by incorporating the `${DEVPORTS_PROJECT_NAME}` variable. This allows for unique and consistent subdomain generation across different worktrees.

```bash
FUNNEL_DOMAIN={DEVPORTS_PROJECT_NAME}.tail1234.ts.net
```

--------------------------------

### JSON Error Format Example

Source: https://github.com/bendechrai/devports/blob/main/AI-ASSISTANT-GUIDE.md

This is an example of the JSON format used for error reporting by `devports`. It clearly indicates the error message, which is useful for programmatic error handling.

```json
{
  "error": "Port 5432 already allocated to myapp/postgres"
}
```

--------------------------------

### MCP Database URL Configuration

Source: https://github.com/bendechrai/devports/blob/main/DOCKER.md

This example shows how to configure a PostgreSQL database URL for MCP servers using devports to dynamically inject the host port for the main database service. This ensures correct port mapping for database access.

```bash
MCP_DATABASE_URL=postgresql://readonly:pass@localhost:{devports:postgres:main-db}/mydb
```

--------------------------------

### Get devports Info using CLI

Source: https://github.com/bendechrai/devports/blob/main/AI-ASSISTANT-GUIDE.md

Retrieves general information about the devports configuration and statistics. The `--json` flag provides this information in a machine-readable format.

```bash
# Show configuration and stats
devports info

# JSON output
devports info --json

```

--------------------------------

### Handle Errors in devports Scripts

Source: https://github.com/bendechrai/devports/blob/main/AI-ASSISTANT-GUIDE.md

These bash examples show how to handle errors when using the `devports allocate` command. The first checks the exit code directly, while the second captures the output and checks if the allocation was successful.

```bash
# Check exit code
if devports allocate myapp postgres --type postgres --quiet; then
  echo "Success"
else
  echo "Failed to allocate port" >&2
  exit 1
fi

# Or capture output
if PORT=$(devports allocate myapp postgres --type postgres --quiet 2>/dev/null); then
  echo "Allocated port: $PORT"
else
  echo "Allocation failed"
fi
```

--------------------------------

### Debug Worktree Creation and Template Parsing with Devports

Source: https://github.com/bendechrai/devports/blob/main/DOCKER.md

These commands are used for debugging devports setups. The first command helps in checking which services would be detected and outputs the information in JSON format. The second command verifies the syntax of the .env.devports template, and the third command tests the docker-compose configuration with resolved variables.

```bash
# Check what services would be detected
devports worktree add ../debug-test -b debug --json

# Verify template parsing
cat .env.devports  # Check template syntax

# Test docker-compose with resolved variables
cd worktree && docker-compose config
```

--------------------------------

### Devports Quick Decision Tree

Source: https://github.com/bendechrai/devports/blob/main/AI-ASSISTANT-GUIDE.md

This flowchart outlines the decision-making process for using `devports`. It guides users on whether to check a specific port, allocate the next available port, or release ports based on their needs.

```text
Need a port?
├─ Know which port? → devports check <port> --quiet
│  ├─ Available? → devports reserve <port> "reason"
│  └─ In use? → devports allocate <project> <service> --quiet
│
├─ Need next available? → devports allocate <project> <service> --quiet
│
└─ Cleaning up?
   ├─ One service? → devports release <project> <service> --quiet
   └─ All ports? → devports release <project> --all --quiet
```

--------------------------------

### devports Environment Variable Template

Source: https://github.com/bendechrai/devports/blob/main/DOCKER.md

An example `.env.devports` file demonstrating how to use devports templating for dynamic port allocation and project naming. It defines internal Docker network variables and external access variables using devports placeholders.

```bash
# .env.devports
DEVPORTS_PROJECT_NAME=myproject

# Internal Docker networking (stays the same)
DATABASE_URL=postgresql://user:password@db:5432/mydb
API_URL=http://api:3000

# Port variables for docker-compose.yml
DATABASE_PORT={devports:postgres:database}
API_PORT={devports:api:api-server}

# External tool access (gets port-mapped)
MCP_DATABASE_URL=postgresql://readonly:password@localhost:${DATABASE_PORT}/mydb
EXTERNAL_API_URL=http://localhost:${API_PORT}
```

--------------------------------

### Allocate Ports for a New Project

Source: https://github.com/bendechrai/devports/blob/main/AI-ASSISTANT-GUIDE.md

This script demonstrates allocating ports for a new project named 'new-app'. It allocates ports for PostgreSQL, Redis, and an API, appending each allocated port to the `.env` file.

```bash
# When creating a new project, allocate all needed ports
PROJECT_NAME="new-app"
devports allocate "$PROJECT_NAME" postgres --type postgres --quiet >> .env
devports allocate "$PROJECT_NAME" redis --type redis --quiet >> .env
devports allocate "$PROJECT_NAME" api --type api --quiet >> .env
```

--------------------------------

### Pattern 3: Check Port Availability Before Allocation

Source: https://github.com/bendechrai/devports/blob/main/QUICKSTART.md

Check if a specific port is currently available using `devports check`. If the port is in use, the script proceeds to allocate the next available port for the specified project and service.

```bash
# Check if port 5432 is free
if devports check 5432 --quiet; then
  echo "Port 5432 is available"
else
  echo "Port 5432 is in use, getting next available..."
  PORT=$(devports allocate myapp postgres --quiet)
fi
```

--------------------------------

### Generate .env File with Allocated Ports

Source: https://github.com/bendechrai/devports/blob/main/AI-ASSISTANT-GUIDE.md

This script allocates ports for a database and an API for the 'myapp' project. It then generates a `.env` file that includes the project name, allocated ports, and a constructed database URL.

```bash
# Allocate ports and create .env file
DB_PORT=$(devports allocate myapp db --quiet)
API_PORT=$(devports allocate myapp api --type api --quiet)

# Generate .env file for your application
cat > .env <<EOF
DEVPORTS_PROJECT_NAME=myapp
DATABASE_PORT=$DB_PORT
API_PORT=$API_PORT
DATABASE_URL=postgresql://user:password@localhost:$DB_PORT/mydb
EOF
```

--------------------------------

### Install and Manage Shell Completions with Devports CLI

Source: https://context7.com/bendechrai/devports/llms.txt

The `devports completion` command generates and installs shell completion scripts for bash and zsh. It supports installation, checking status, testing, manual script generation, and uninstallation.

```bash
# Install zsh completion (macOS default)
devports completion zsh --install
# → ✅ Completion script installed
# → ✅ Shell config updated (~/.zshrc)
# → Restart your terminal or run: source ~/.zshrc

# Install bash completion (Linux default)
devports completion bash --install

# Check if completion is installed
devports completion zsh --check
# → ✅ Completion is installed and configured

# Test completion in fresh shell
devports completion zsh --test
# → ✅ Completion working correctly

# Generate script to stdout (manual installation)
devports completion zsh > ~/.devports-completion.zsh

# Uninstall completion
devports completion zsh --uninstall
# → ✅ Completion uninstalled
```

--------------------------------

### Show Devports Configuration and Statistics (devports info)

Source: https://github.com/bendechrai/devports/blob/main/README.md

Displays the location of the configuration and registry files, along with port statistics. Supports JSON output.

```bash
devports info [--json]
```

--------------------------------

### Allocate Multiple Services and Create .env File

Source: https://github.com/bendechrai/devports/blob/main/AI-ASSISTANT-GUIDE.md

This bash script allocates ports for multiple services (PostgreSQL, API, App) for a given project using `devports allocate`. It then creates a `.env` file containing these allocated ports, making them available for application configuration.

```bash
#!/bin/bash
PROJECT="myapp"

# Allocate multiple services
PG_PORT=$(devports allocate "$PROJECT" postgres --type postgres --quiet)
API_PORT=$(devports allocate "$PROJECT" api --type api --quiet)
APP_PORT=$(devports allocate "$PROJECT" app --type app --quiet)

# Write to .env
cat > .env <<EOF
DATABASE_PORT=$PG_PORT
API_PORT=$API_PORT
APP_PORT=$APP_PORT
EOF
```

--------------------------------

### Allocate and Manage Ports with Devports CLI

Source: https://github.com/bendechrai/devports/blob/main/README.md

Demonstrates basic devports commands for allocating ports for different services (PostgreSQL, API), listing all allocations, checking port status, and releasing allocated ports.

```bash
# Allocate a PostgreSQL port for 'myproject'
devports allocate myproject postgres --type postgres

# Allocate an API port for 'myproject'
devports allocate myproject api --type api

# List all current port allocations
devports list

# Check the status of available ports
devports status

# Release the allocated PostgreSQL port for 'myproject'
devports release myproject postgres
```

--------------------------------

### Package Testing Commands Bash

Source: https://github.com/bendechrai/devports/blob/main/CONTRIBUTING.md

Bash commands to test the packaged version of devports. This involves creating a tarball of the package, installing it globally in a temporary directory, and then verifying the installed version.

```bash
# Create and test package
npm pack
cd /tmp
npm install -g /path/to/devports-0.1.0.tgz
devports --version
```

--------------------------------

### Adding a New Port Type to Configuration (TypeScript)

Source: https://github.com/bendechrai/devports/blob/main/CONTRIBUTING.md

This snippet shows how to add a new port type, 'newtype', to the default configuration in `src/config.ts`, specifying its start and end port numbers.

```typescript
const DEFAULT_CONFIG: Config = {
  ranges: {
    // ... existing
    newtype: { start: 7000, end: 7099 },
  },
};

```

--------------------------------

### Programmatic Port Allocation with Node.js

Source: https://github.com/bendechrai/devports/blob/main/README.md

This JavaScript code demonstrates programmatic usage of the `devports` library in Node.js. It shows how to allocate ephemeral ports for CI/CD, check port availability, and list project port allocations.

```javascript
import { allocatePort, listAllocations, checkPortInUse } from 'devports';

// CI/CD: Allocate ephemeral port for testing
const testRunId = `ci-${process.env.GITHUB_RUN_ID}`;
const dbPort = await allocatePort(testRunId, 'test-db', 'postgres');

// Tool integration: Check if port is actually available
const isInUse = await checkPortInUse(5432);
if (!isInUse) {
  console.log('Port 5432 is available for use');
}

// Development tools: List project ports
const projectPorts = listAllocations({ project: 'myapp' });
console.log('Current allocations:', projectPorts);
```

--------------------------------

### Troubleshoot 'Port already allocated'

Source: https://github.com/bendechrai/devports/blob/main/AI-ASSISTANT-GUIDE.md

When a port is already allocated, these commands help identify which project and service is using it. It also shows how to release the port if appropriate.

```bash
# Find what's using it
devports list --json | jq '.[] | select(.port == 5432)'

# Release if appropriate
devports release <project> <service>
```

--------------------------------

### Development Workflow Commands (Bash)

Source: https://github.com/bendechrai/devports/blob/main/CONTRIBUTING.md

This snippet covers essential commands for the development workflow, including running the project in watch mode, executing tests (with a watch mode option), performing type checking, and building the project for distribution.

```bash
# Watch mode for development
npm run dev

# Run tests (watch mode available with npm run test:watch)
npm test

# Type checking
npm run lint

# Build for distribution
npm run build
```

--------------------------------

### Manage Devports CLI Shell Completion

Source: https://github.com/bendechrai/devports/blob/main/README.md

Provides commands to manage devports shell completion, including checking installation status, testing functionality, generating the script, and uninstalling.

```bash
# Check if completion is already installed
devports completion --check

# Test that completion works (validates in fresh shell)
devports completion --test

# Generate completion script to stdout
devports completion zsh

# Uninstall completion (removes files and shell config)
devports completion --uninstall
```

--------------------------------

### Devports CLI Usage: Scripting and Automation

Source: https://github.com/bendechrai/devports/blob/main/README.md

Illustrates how to use devports commands in scripts for automation, focusing on quiet output for port numbers and JSON output for structured data.

```bash
# Get only the allocated port number
PORT=$(devports allocate myapp postgres --type postgres --quiet)
echo "Using port: $PORT"

# Get allocation details in JSON format
devports allocate myapp api --type api --json
# Expected output: {"port":3001,"project":"myapp","service":"api","type":"api"}

# Check if a specific port is available (exit code 0 for available, 1 for unavailable)
if devports check 5432 --quiet; then
  echo "Port 5432 is available"
fi
```

--------------------------------

### Advanced Multi-Database Docker Compose (Problematic)

Source: https://github.com/bendechrai/devports/blob/main/DOCKER.md

A complex docker-compose.yml setup with multiple databases and services that suffers from port and container naming conflicts across different worktrees. It uses fixed ports and container names.

```yaml
# docker-compose.yml (problematic)
version: '3.8'
services:
  users-db:
    image: postgres:15
    container_name: users-database
    ports:
      - '5432:5432'

  orders-db:
    image: postgres:15
    container_name: orders-database
    ports:
      - '5433:5432'

  redis:
    image: redis:7
    container_name: cache-redis
    ports:
      - '6379:6379'

  api:
    build: ./api
    container_name: main-api
    ports:
      - '3000:3000'
    environment:
      USERS_DB_URL: postgresql://user:pass@users-db:5432/users
      ORDERS_DB_URL: postgresql://user:pass@orders-db:5432/orders
      REDIS_URL: redis://redis:6379
```

--------------------------------

### Troubleshoot 'No available ports'

Source: https://github.com/bendechrai/devports/blob/main/AI-ASSISTANT-GUIDE.md

If no ports are available, these commands help diagnose the issue by checking the status of `devports` and listing all ports allocated for a specific type.

```bash
# Check status
devports status --json

# List all to see what's in use
devports list --type postgres --json
```

--------------------------------

### Bash Script for Advanced Docker Environment Setup Hook

Source: https://github.com/bendechrai/devports/blob/main/DOCKER.md

An advanced post-worktree hook script that configures the Docker environment. It updates container names in both `docker-compose.yml` and `docker-compose.override.yml`, and creates custom `docker-up.sh` and `docker-down.sh` scripts for managing containers.

```bash
#!/bin/bash
set -e
cd "$DEVPORTS_WORKTREE_PATH"

echo "🐳 Setting up Docker environment for: $DEVPORTS_PROJECT_NAME"

# Update docker-compose.yml
if [ -f docker-compose.yml ]; then
    cp docker-compose.yml docker-compose.yml.bak
    sed -i "s/container_name: \([^$]*\)/container_name: ${DEVPORTS_PROJECT_NAME}-\1/g" docker-compose.yml
fi

# Update docker-compose.override.yml
if [ -f docker-compose.override.yml ]; then
    cp docker-compose.override.yml docker-compose.override.yml.bak
    sed -i "s/container_name: \([^$]*\)/container_name: ${DEVPORTS_PROJECT_NAME}-\1/g" docker-compose.override.yml
fi

# Create a docker-compose alias script
cat > docker-up.sh << EOF
#!/bin/bash
# Custom docker-compose script for worktree: $DEVPORTS_PROJECT_NAME
docker-compose --project-name $DEVPORTS_PROJECT_NAME up -d "$@"
EOF
chmod +x docker-up.sh

# Create cleanup script
cat > docker-down.sh << EOF
#!/bin/bash
# Cleanup script for worktree: $DEVPORTS_PROJECT_NAME
docker-compose --project-name $DEVPORTS_PROJECT_NAME down "$@"
EOF
chmod +x docker-down.sh

echo "✅ Docker environment configured"
echo "💡 Use ./docker-up.sh to start containers"
echo "💡 Use ./docker-down.sh to stop containers"
```

--------------------------------

### Allocate a Port using devports CLI

Source: https://github.com/bendechrai/devports/blob/main/AI-ASSISTANT-GUIDE.md

Demonstrates how to allocate a port for a given project and service using the devports CLI. Supports specifying port type, quiet mode for script output, and JSON output for programmatic parsing. Exit codes indicate success (0) or failure (1).

```bash
# Basic allocation (defaults to postgres type)
devports allocate <project> <service>

# With specific type
devports allocate <project> <service> --type <type>

# Quiet mode (returns only port number)
devports allocate <project> <service> --quiet

# JSON output
devports allocate <project> <service> --json

```

```bash
# Normal mode
$ devports allocate myapp postgres --type postgres
✅ Allocated port 5432 for myapp/postgres

# Quiet mode
$ devports allocate myapp postgres --type postgres --quiet
5432

# JSON mode
$ devports allocate myapp postgres --type postgres --json
{"port":5432,"project":"myapp","service":"postgres","type":"postgres"}

```