Feature Request: Add --port flag to mintlify dev

[brandensilva]

Feature Request

Add a --port (or -p) flag to the mintlify dev command to allow specifying a custom port for the local preview server.

Current behavior

mintlify dev always starts on port 3000. If port 3000 is occupied, it falls back to 3001, 3002, etc. There is no way to explicitly set the port.

Proposed behavior

mintlify dev --port 3456
# or
mintlify dev -p 3456

Additionally, it would be great if mintlify dev respected the PORT environment variable as a fallback when --port is not provided:

PORT=3456 mintlify dev

Why this matters

Port 3000 is one of the most commonly used ports in local development. It's the default for Next.js, Create React App, Remix, and many other frameworks. Teams running a documentation site alongside their application almost always hit a port collision during local development.

The current fallback behavior (silently incrementing to 3001, 3002, etc.) makes the port unpredictable, which creates friction with:

• Local reverse proxies (e.g., Portless, nginx, Caddy) that need a stable port to route to
• docker-compose or monorepo setups where services are configured to communicate on known ports
• Developer scripts and aliases that hardcode a URL for quick access
• Browser bookmarks and saved dev environments that rely on a consistent address

Many documentation tools already support this — Docusaurus (--port), Starlight/Astro (--port), VitePress (--port), MkDocs (--dev-addr). Adding --port to Mintlify would bring it in line with the ecosystem and make it much easier to run docs alongside other services in local development.

Environment

• mintlify CLI: 4.2.434
• OS: macOS

[brandensilva]

Update: I noticed that the @mintlify/cli npm package references --port support, but it doesn't appear to be functional in the current release (4.2.434). Running mintlify dev --help or mint dev --help does not list --port as an available option. It's possible this is in development but not yet shipped — wanted to flag this in case it's close to landing.

[vincent067]

Hi @brandensilva 👋

Thanks for this well-written feature request! This is definitely a pain point I've run into as well — port 3000 is almost always taken when working with Next.js apps alongside Mintlify docs.

A few thoughts on implementation:

Proposed CLI Interface

# Flag approach (most common)
mintlify dev --port 3456
mintlify dev -p 3456

# Environment variable fallback
PORT=3456 mintlify dev

# Config file support (docs.json)
{
  "dev": {
    "port": 3456
  }
}

Priority Order

If the team decides to implement this, I'd suggest this priority:

1. --port flag (explicit user intent)
2. PORT env var (CI/docker friendly)
3. Config file (project-wide default)
4. Default 3000 (current behavior)

Temporary Workaround

Until this lands, here's a workaround using environment variables with the current fallback behavior:

# In your package.json scripts
{
  "scripts": {
    "docs:dev": "mintlify dev",
    "docs:dev:alt": "lsof -ti:3000 | xargs kill -9 2>/dev/null; mintlify dev"
  }
}

Or using a port-check script:

#!/bin/bash
# docs-dev.sh
for port in 3000 3456 4000 5000; do
  if ! lsof -Pi :$port -sTCP:LISTEN -t >/dev/null ; then
    echo "Starting Mintlify on port $port"
    # Note: This still doesn't guarantee the port, but helps avoid collision
    mintlify dev
    break
  fi
done

Ecosystem Comparison

Tool	Flag	Env Var	Config
Docusaurus	✅ --port	❌	✅ docusaurus.config.js
VitePress	✅ --port	❌	❌
Starlight	✅ --port	❌	✅ astro.config.mjs
MkDocs	✅ --dev-addr	❌	✅ mkdocs.yml
Mintlify	❌	❌	❌

Would love to see this feature! Happy to help test or contribute if needed. 😊

cc @mintlify team