CLI Commands

The smcp CLI is the primary interface for resolving, downloading, and executing MCP servers from the registry. This page documents every command, flag, and exit code.

Global Flags

These flags are available on all commands:

smcp run

Execute an MCP server from a package reference.

smcp run [flags] <package-ref>

The run command resolves a package from the registry, downloads the bundle if not cached, validates its SHA-256 integrity, evaluates security policies, and launches the MCP server in a sandboxed process.

Flags

Package Reference Formats

Examples

# Run the latest certified version
smcp run cr0hn/mcp-schrodinger@latest

# Run with environment variables from a file
smcp run acme/[email protected] --env-file .env

# Run an untrusted package with explicit trust and a timeout
smcp run untrusted/tool@latest --trust --timeout 10m

smcp pull

Pre-download a package without executing it.

smcp pull [flags] <package-ref>

Downloads the manifest and bundle to the local cache and validates SHA-256 integrity. This is useful for CI/CD pipelines, air-gapped environments, or pre-caching packages on slow connections.

Examples

smcp pull cr0hn/mcp-schrodinger@latest
smcp pull acme/[email protected]

smcp info

Display detailed package information.

smcp info [flags] <package-ref>

Shows comprehensive metadata about a package without downloading or executing it:

• Name, version, and author
• Runtime and entry point
• Declared permissions
• Security score and certification level
• Origin type
• Bundle size and SHA-256 digest

Examples

# Human-readable output
smcp info cr0hn/mcp-schrodinger@latest

# Machine-readable JSON output
smcp info acme/[email protected] --json

smcp login

Authenticate with the MCP registry.

smcp login [flags]

Flags

When run without --token, opens an interactive browser-based authentication flow. Credentials are stored in ~/.mcp/auth.json with 0600 permissions.

Examples

# Interactive login (opens browser)
smcp login

# Non-interactive login with a token (useful for CI/CD)
smcp login --token mcphub_tok_abc123...

smcp logout

Remove stored authentication credentials.

smcp logout

Deletes the token from ~/.mcp/auth.json. After logging out, operations that require authentication (such as publishing) will fail until you log in again.

smcp cache ls

List cached packages.

smcp cache ls

Displays all packages currently stored in the local cache, including:

• Package reference
• Version
• SHA-256 digest
• Size on disk
• Date cached

smcp cache rm

Remove cached packages.

smcp cache rm [flags] [package-ref]

Flags

Examples

# Remove a specific package from cache
smcp cache rm cr0hn/mcp-schrodinger

# Remove all cached packages
smcp cache rm --all

smcp cache gc

Garbage collect expired cache entries.

smcp cache gc

Removes entries that have exceeded the configured TTL (default: 168 hours / 7 days). Run this periodically to reclaim disk space, or let the client handle it automatically.

smcp doctor

Diagnose system sandbox capabilities.

smcp doctor

Runs a diagnostic check and reports on:

• Platform – Operating system and architecture
• Sandbox support – Network isolation, filesystem isolation, resource limits, subprocess control
• Registry connectivity – Whether the registry is reachable
• Configuration status – Config file location, auth status, cache directory

This command is useful for troubleshooting execution failures, especially on platforms with limited sandboxing support.

Example Output

Platform:       linux/amd64
Sandbox:
  Network isolation:    supported (iptables)
  Filesystem isolation: supported (chroot)
  Resource limits:      supported (cgroups v2)
  Subprocess control:   supported (PID namespace)
Registry:       https://registry.mcp-hub.info (reachable)
Config:         ~/.mcp/config.yaml (found)
Auth:           authenticated as cr0hn
Cache:          ~/.mcp/cache (1.2 GB used)

Exit Codes

The smcp CLI uses specific exit codes to indicate the nature of a failure:

These exit codes are stable and can be relied upon in scripts and CI/CD pipelines.