gem-hunter

CLI for Socket.dev - bring Socket's supply-chain security analysis to your terminal and CI.

Socket CLI is the command-line interface to Socket.dev, letting you scan dependencies, audit packages, and gate installs from your terminal or CI. This branch develops the 2.x prerelease of socket. End-user documentation lives on socket.dev.

pnpm add --global socket@next

Then run:

socket --help

# Score a package and its transitive dependencies
socket package score npm express@4.18.0

# Scan your project's dependencies
socket scan create

# Audit an install before it runs (npm, pnpm, or yarn)
socket npm install
socket pnpm install
socket yarn add <package>

socket npm, socket pnpm, and socket yarn each run the underlying package manager through Socket Firewall, which blocks known-malicious packages before they are installed. Install-time protection is no longer npm-only.

Browse the command index for every command and alias, then open a focused guide from its tables.

See the organization dependency inventory guide for listing dependencies already known to your organization.

For a local stdio connection, run socket login once, then configure your MCP client to launch socket with arguments ["mcp"]. Reuse saved authentication until it expires or the server rejects it.

For the hosted service, use your client's native remote connector with https://mcp.socket.dev/. In Claude Desktop, add it through Customize > Connectors.

Clients that require a stdio bridge can use the verified mcp-remote@0.8.3 release. Install it with pnpm add --global mcp-remote@0.8.3, then configure:

{
  "mcpServers": {
    "socket": {
      "command": "mcp-remote",
      "args": ["https://mcp.socket.dev/"]
    }
  }
}

The bridge runs the OAuth callback listener on your computer. Version 0.1.49 can open authorization after connection without starting that listener. The upstream fix is included in 0.8.3. Update the bridge executable if authorization returns to an unavailable localhost callback. Reauthorization recovery was verified against the published bridge transport; a complete browser login remains a separate integration check.

CLI entrypoints live in src/command/. Shared implementations live in src/core/. See the architecture guide for the source and test layout.

git clone --depth=1 --single-branch https://github.com/SocketDev/socket-cli.git
cd socket-cli
pnpm install
pnpm run build
pnpm test

Requires Node.js (see .node-version) and pnpm (see the packageManager field in package.json).

Run the built CLI from source:

pnpm run s --help

Enable debug logging:

SOCKET_CLI_DEBUG=1 pnpm run s <command>

Key development environment variables:

The API base URL and the npm registry URL both receive an Authorization header, so the CLI refuses either one when it points at a loopback, private, or link-local host - a repo-supplied SOCKET_CLI_CONFIG or .npmrc cannot aim the token at 169.254.169.254 or an internal service. An enterprise Socket instance or npm registry reached by a literal private address names that host in SOCKET_CLI_ALLOWED_PRIVATE_HOSTS:

SOCKET_CLI_ALLOWED_PRIVATE_HOSTS=10.0.0.5,registry.10.0.0.6.nip.io

It is an allowlist rather than an off switch, so allowing your own host does not allow every other private host.

Further contributor reading:

• docs/build-guide.md - single-package build and verification
• docs/bundle-tools.md - how bundled tools (opengrep, trivy, etc.) are integrated
• docs/repo/architecture.md - source and command layout

MIT