CLI Reference

# Install via pip
pip install pharos-cli

# Or install via npm
npm install -g @pharos/cli

# Verify installation
pharos --version

# Print the CLI version explicitly
pharos version

# Search the registry for a keyword
pharos search "flight tracker"

# Filter by transport, capability, or publisher
pharos search "memory" --transport stdio --capability tools

# Limit and sort results
pharos search "database" --limit 20 --sort stars

# Show full package details from the registry
pharos info my-test-mcp-server
pharos info [email protected]

# List packages installed in the local client
pharos list

# Check registry connectivity and health
pharos health

# Install an MCP server into your client
pharos install my-test-mcp-server --client claude

# Install a pinned version with variables
pharos install [email protected] --var API_KEY=secret

# Dry-run an install without writing configs
pharos install my-test-mcp-server --dry-run

# Update one or more installed servers
pharos update my-test-mcp-server

# Update everything installed
pharos update --all

# Remove a server from client configs and the local store
pharos remove my-test-mcp-server

# Import existing MCP servers from a client config
pharos import --client claude

# Scaffold a new pharos.json manifest
pharos init --name my-server --namespace acme --runtime python

# Publish a package to the registry
pharos publish ./my-server

# Publish with a tag and SBOM + signing
pharos publish ./my-server --tag beta --sign --sbom

# Dry-run a publish to validate without uploading
pharos publish ./my-server --dry-run

# Hide a version from search and lookup
pharos unpublish my-test-mcp-server --version 1.4.0

# Re-activate a previously unpublished version
pharos republish my-test-mcp-server --version 1.4.0

# Permanently remove a version from the registry
pharos purge my-test-mcp-server --version 1.4.0 --yes

# Start a locally installed MCP server in the background
pharos start my-test-mcp-server

# Start in the foreground with an explicit port
pharos start my-test-mcp-server --foreground --port 3100

# Stop a running server (graceful by default)
pharos stop my-test-mcp-server

# Force-stop all running servers after a timeout
pharos stop --all --force --timeout 5

# Scan installed servers for known vulnerabilities
pharos audit

# Output audit results in a specific format
pharos audit --format json

# Ignore a specific advisory during audit
pharos audit --ignore PHAROS-2026-001

# Run a health check on the local installation
pharos doctor

# Attempt automatic fixes for detected issues
pharos doctor --fix

# Regenerate the lockfile from current installs
pharos lock regenerate

# Verify the lockfile is consistent
pharos lock verify

# Show changes between lockfile and installed state
pharos lock diff

# Authenticate with the registry
pharos login

# Authenticate via GitHub OAuth
pharos login --github

# Use a pre-issued token
pharos login --token phs_live_xxx

# Show the currently authenticated user
pharos whoami

# Read a config value
pharos config get registry

# Set a config value
pharos config set registry pharos

# List all config keys
pharos config list

# Store a secret securely
pharos config secret API_KEY

# Override the install prefix
pharos --prefix ~/.local install my-test-mcp-server

# Target a different registry
pharos --registry staging search "memory"

# Force JSON output for scripting
pharos --json list

# Increase or decrease log verbosity
pharos --verbose install my-test-mcp-server
pharos --quiet search "database"

# Disable colored output (CI / logs)
pharos --no-color search "database"

# Point at a custom config file
pharos --config ./custom-pharos.json list

# 0  — success
# 1  — user error (invalid arguments, missing spec)
# 2  — lockfile violation (pharos.lock out of sync)
# 3  — network error (registry unreachable, timeout)
# 4  — security failure (audit found advisories, signature mismatch)

# Example: check the exit code in a shell script
pharos audit && echo "clean" || echo "exit code: $?"