Pharos CLI

A Go CLI tool for the PHAROS MCP server package registry.

Install

Linux / macOS / WSL / Git Bash:

curl -fsSL getpharos.dev/install | sh

Windows PowerShell (not cmd — curl | sh is not a cmd command):

irm https://getpharos.dev/install.ps1 | iex

Until /install.ps1 is live on the site, download the .exe from the latest release (pharos_1.0.0_windows_amd64.exe) and put it on your PATH.

From source:

go install github.com/Wpnx330/pharos-cli@latest
# or
go build -o pharos .

Full command reference: https://discoverpharos.dev/cli/docs

Homebrew & Scoop

macOS (Homebrew):

brew tap Wpnx330/pharos && brew install pharos

Windows (Scoop; two lines — PowerShell 5.1 has no &&):

scoop bucket add pharos https://github.com/Wpnx330/Scoop-Bucket
scoop install pharos

Commands

# Discovery
pharos search <query>          # Search the registry
pharos search <query> --transport http-sse --registry pharos -p 2
pharos info "<package-id>"     # Quote IDs with spaces or (

# Package lifecycle
pharos init                    # Scaffold a new pharos.json (interactive, includes dependency + tag prompts)
pharos init --yes              # Non-interactive (use defaults)
pharos package [dir]           # Package a directory into a tarball (like npm pack)
pharos publish [dir]           # Package + upload + publish to the registry
pharos unpublish <name>        # Hide a package version from search and lookup
pharos republish <name>        # Re-activate a previously unpublished version
pharos purge <name>            # Permanently remove a package version from the registry

# Local management
pharos install <name>          # Download and install a package (with recursive dependency resolution)
pharos install <name> --no-dep-config  # Install without writing MCP client configs for dependencies
pharos install <name> --idle-timeout 30  # Auto-unload after 30min idle (default: 60)
pharos install <name> --idle-timeout 0   # Never unload — always on
pharos install <name> --profile work     # Write only the profile's mapped clients + attach it
pharos list                    # List locally installed packages
pharos list --running          # Show only running servers (daemon-managed)
pharos start <name>            # Start a locally installed MCP server
pharos stop <name>             # Stop a running MCP server
pharos update [name]           # Check for and apply updates to installed servers — installs the new version and rewrites affected client configs
pharos lock                    # Resolve dependencies and write ./pharos.lock
pharos import                  # Import existing MCP client configs into a pharos.lock
pharos import --adopt          # One-command onboarding: adopt every detected client config as the managed baseline (conflicts resolved interactively)
pharos remove <name>           # Remove a locally installed package
pharos remove <name> --force   # Remove even if other packages depend on it (not a confirm skip)
pharos try <name>              # Probe a server's live capabilities without wiring it (see "Try before you wire")
pharos try <name> --inspect    # Launch MCP Inspector against the server (needs npx)

# Profiles (contexts — see "Profiles (contexts)" below)
pharos profile create work --client cursor   # Map a named context to clients
pharos profile add work <server...>          # Attach already-installed servers
pharos profile ls --json                     # The context map (agent-readable)
pharos profile use work                      # Reconcile mapped clients to exactly this context (plan + confirm)
pharos profile rm work                       # Delete the profile (servers stay installed)

# Daemon (MCP server process supervisor)
pharos daemon start            # Start the daemon (backgrounds by default)
pharos daemon start --foreground  # Run in foreground (for debugging)
pharos daemon stop             # Stop daemon + unload all managed servers
pharos daemon restart          # Stop + start (convenience)
pharos daemon status           # Show daemon health + managed server table
pharos daemon log              # Show recent daemon log output (default 50 lines)
pharos daemon log -n 100       # Show last 100 lines of daemon log
pharos daemon autostart --on   # Enable autostart on boot
pharos daemon autostart --off  # Disable autostart on boot
pharos daemon autostart        # Show current autostart status

# Auth
pharos login                   # GitHub OAuth login (opens browser)
pharos whoami                  # Show current authenticated user

# OAuth configuration
pharos oauth configure <name>  # Configure OAuth for a published MCP server
pharos oauth configure <name> \ # With all options
  --auth-url <url> --client-id <id> --scopes <scopes> --pkce

# System
pharos doctor                  # Diagnose CLI health — registry, servers, client configs
pharos audit                   # Scan installed servers for known vulnerabilities
pharos config <key> [value]    # Get or set configuration
pharos config add-client <id> --path <path>   # Register a custom MCP client
pharos config remove-client <id>
pharos config list-clients
pharos health                  # Check registry health
pharos version                 # Print CLI version

One-line list only. Full flags and examples: https://discoverpharos.dev/cli/docs. Command names come from cmd/*.go (Use:). If this README and the site disagree, the Go source wins.

Flags

• --json — Output as JSON (search, info, health). Search includes transport, source_registry, nextCursor, total.
• --limit / -n — Number of search results (default: 10)
• --page / -p — Search page (1-based). Mapped to API cursor (page-1)*limit.
• --registry — Search filter: mcp.io, mcp.so, pharos, smithery
• --transport — Search filter: stdio, http-sse, streamable-http, sse, http
• --version / -v — Install a specific version
• --global / -g — Install system-wide
• --token / -t — Auth token for publishing
• --dry-run — Validate manifest without publishing
• --yes — Skip interactive prompts (init)
• --no-dep-config — Don't write MCP client configs for dependencies (install)
• --force — Remove a package even if other packages depend on it (remove)
• --frozen — Install strictly from lockfile; refuse if missing or mismatched (install)
• --idle-timeout — Per-server minutes of inactivity before auto-unloading that server's HTTP/SSE process (default: 60, 0 = never unload). Set at install time; stored per-server in ~/.pharos/mcp.json (install)
• --running — Show only running daemon-managed servers (list)
• --diff — Compare pharos-managed server entries in client configs against the pharos.lock baseline; read-only drift report (doctor)
• --timeout — Total probe budget for pharos try (Go duration, default 10s; each JSON-RPC request is also capped at 10s)
• --inspect — Print and launch the npx MCP Inspector command for the server instead of probing (try)

Try before you wire

Installing a server shouldn't be a leap of faith. pharos try <name> spawns the server exactly as it is configured in ~/.pharos/mcp.json, speaks real MCP to it (initialize handshake over stdio JSON-RPC), and prints its live capabilities in about five seconds — no client config is touched:

$ pharos try echo-server
Probing echo-server…
✓ echo-server v1.2.3 — MCP 2025-06-18

  TOOLS (2)
    echo                     Echo back the provided message
    status                   Return server status
  RESOURCES (2): notes, file:///config.json
  PROMPTS (1): greeting

• Honest failures: if the server won't start, fails the handshake, or hangs, try exits 1 and shows the server's actual stderr (last 10 lines) — not just "exit status 1". Unknown server: exit 2 with an install hint (pharos install <name> --sandbox probe-only installs are planned).
• --json (PHAROS_JSON=1): a single stdout JSON document {server, caps: {protocolVersion, serverInfo, tools[], resources[], prompts[]}} — probe failures emit {server, errors, stderr_tail}; pre-flight failures (config unreadable, unknown server, non-stdio) emit the minimal {server, errors} document. Never prompts; progress lines go to stderr. Built for the agent-automation contract.
• --timeout 30s: raise the total probe budget (default 10s).
• --inspect: prints the exact npx -y @modelcontextprotocol/inspector … command for this server, then launches it in the foreground (honest error if npx isn't on PATH). --inspect --json only reports the command without spawning.

try probes stdio servers only. Env vars from the canonical config are passed through as-is (${secret:…} templates are not resolved in this wave).

Search Results

The search table shows the trust signals the registry already provides: OWNER (publisher namespace), CATEGORY (registry catalog category), and DOWNLOADS (30-day downloads, humanized — 1234 renders as 1.2k). A non-active version_status is flagged inline on the version, e.g. 1.2.3 (stale); active versions stay bare. Missing values render as —. --json carries the same fields (publisher, category, tools_count, version_status) per result.

Configuration

Config is stored at ~/.pharos/config.json:

pharos config registry https://getpharos.dev
pharos config token <your-token>

Credentials are stored at ~/.pharos/credentials.json after pharos login.

Manifest (pharos.json)

{
  "name": "my-mcp-server",
  "version": "1.0.0",
  "description": "An MCP server for X",
  "license": "MIT",
  "transport": "stdio",
  "runtime": "python",
  "command": "python server.py",
  "capabilities": ["tools"],
  "homepage": "https://github.com/user/repo",
  "repository": "https://github.com/user/repo",
  "files": ["server.py", "lib/"],
  "tags": ["weather", "doppler", "humidity"]
}

Manifest fields

| Field | Required | Description | |-------|----------|-------------| | name | yes | Package name (unscoped or @scope/name) | | version | yes | Semantic version | | description | no | Short description shown in search results | | license | no | SPDX license identifier | | transport | yes | stdio, http-sse, streamable-http, or http | | runtime | no | Runtime hint: npx, uvx, docker, binary, python (auto-detected from command if omitted) | | command | no | Explicit launch command (e.g. python -m src.server). Overrides runtime-based construction. Falls back to bin field for backwards compat | | entrypoint | no | Alternative to command (Docker entrypoint) | | capabilities | yes | MCP capability types: tools, resources, prompts, logging | | files | no | Explicit file list to package (auto-detected if omitted). Directory entries (e.g. "src/") are packed recursively | | homepage | no | Homepage URL | | repository | no | Repository URL | | dependencies | no | Array of {name, version} — semver constraints for recursive install | | tags | no | Array of up to 3 text hashtags for discoverability (lowercase, alphanumeric + hyphens, max 20 chars each) |

Publishing

The pharos publish command runs a 4-phase flow automatically:

1. Get user — GET /v1/auth/me to determine your namesp