Socket CLI

CLI for Socket.dev — scan dependencies, audit packages, apply security patches, and gate installs from your terminal or CI. This is the 1.x line of the published socket package on npm.

Install

npm install -g socket
socket --help

Usage

Commands

• socket npm [args...] and socket npx [args...] - Wraps npm/npx with Socket security scanning

• socket fix - Fix CVEs in dependencies

• socket optimize - Optimize dependencies with @socketregistry overrides

• socket cdxgen [command] - Run cdxgen for SBOM generation

• socket patch <command> - Apply, manage, and rollback Socket security patches for vulnerable dependencies

Patch subcommands

Command	Description
socket patch scan	Scan installed packages for available security patches
socket patch get <uuid> --org <slug>	Download a patch by UUID and store it locally
socket patch apply	Apply downloaded patches to node_modules
socket patch rollback [purl|uuid]	Rollback patches and restore original files
socket patch list [--json]	List all patches in the local manifest
socket patch remove <purl|uuid>	Remove a patch from the manifest (rolls back by default)
socket patch setup [--yes]	Add socket patch apply to postinstall scripts
socket patch repair	Download missing blobs and clean up unused blobs

Quick start:

# Scan for available patches, download, and apply.
socket patch scan
socket patch apply

# Or download a specific patch by UUID.
socket patch get <uuid> --org <org-slug>
socket patch apply

# Add to postinstall so patches reapply on npm install.
socket patch setup --yes

Free patches work without authentication. For paid patches, set SOCKET_CLI_API_TOKEN and SOCKET_CLI_ORG_SLUG.

Aliases

All aliases support the flags and arguments of the commands they alias.

• socket ci - Alias for socket scan create --report (creates report and exits with error if unhealthy)

Scanning uv workspace members

Use --uv-members to scan selected directories of a uv workspace with the versions pinned in the workspace's shared uv.lock:

socket scan create --uv-members ./packages/api ./packages/worker

Each TARGET is a directory with its own pyproject.toml. uv finds the uv.lock in that directory or in its workspace root, so one scan can cover members of several workspaces. The scan includes each target's transitive and local workspace dependencies, all extras, and all dependency groups. Dependencies used only by dependency groups are marked as development dependencies. Unrelated members and the shared lockfile are not added to the scan.

This mode requires uv on PATH with support for uv export --format cyclonedx1.5, which uv currently treats as a preview feature. The export runs offline with --frozen, so it uses the existing lockfile without resolving newer versions, installing packages, or changing the project.

The CLI writes a socket-uv-cdx.json SBOM into each target directory, uploads only those SBOMs in place of regular manifest discovery, and removes them after the scan, including on failure, Ctrl-C, or SIGTERM. It stops if that file already exists. --read-only prepares the SBOMs without uploading them, and --dry-run validates the options without running uv.

With --reach, pass a single target. Reachability analysis then runs on that member's directory. --uv-members cannot be combined with --auto-manifest or --dynamic-sbom-inference.

Reachability analysis

Socket reachability analysis comes in three forms:

• Full application reachability (formerly Tier 1): Analyzes your application together with its dependencies to determine whether vulnerable code is actually invoked from your code through the full dependency graph — the highest-precision reachability analysis. Run it with socket scan create --reach.
• Precomputed reachability (formerly Tier 2): Determines whether vulnerable code in transitive dependencies is reachable through your direct dependencies, using precomputed static analysis of dependency chains (no access to your application code required). In the CLI this is the fallback used when full application reachability cannot complete (see the --reach-continue-on-* flags).
• Dependency reachability (formerly Tier 3): Package-level filtering that detects which dependencies are actually used, so CVEs in unused/dead dependencies can be filtered out.

Network access

Full application reachability (socket scan reach, socket scan create --reach) downloads its analysis engine, the Coana CLI, on first use and installs your project's dependencies to analyze them. On a restricted network, allow:

Host	Used for	If blocked
api.socket.dev	Socket API calls, and a signed URL for the engine download	The command fails
storage.googleapis.com	Downloading the engine and its analyzers (about 120 MB)	The command fails with Failed to get the Coana CLI <version>: getaddrinfo ENOTFOUND storage.googleapis.com
The package registry of each scanned ecosystem, for example registry.npmjs.org	Installing your project's dependencies for analysis	The analysis still completes, but the affected vulnerabilities are reported as INSTALL ERROR with no reachability result

The engine comes from Socket, not npm, so an npm mirror or registry proxy does not cover the engine download. The registry row does not apply when your dependencies are already installed in the scanned directory, for example a node_modules directory from an earlier npm ci.

The engine is cached in $XDG_CACHE_HOME/socket/coana (~/.cache/socket/coana by default). Persist that directory between CI runs to skip the download; with a warm cache, storage.googleapis.com is not contacted.

Behind an HTTP(S) proxy, set NODE_USE_ENV_PROXY=1 along with HTTPS_PROXY. The CLI does not currently route its own requests through HTTPS_PROXY or SOCKET_CLI_API_PROXY, and fails with getaddrinfo EAI_AGAIN api.socket.dev. NODE_USE_ENV_PROXY=1 (Node.js 22.21 or later) makes Node.js send them through the proxy:

HTTPS_PROXY=http://proxy.example.com:3128 NODE_USE_ENV_PROXY=1 socket scan reach .

Flags

Output flags

• --json - Output as JSON
• --markdown - Output as Markdown

Other flags

• --dry-run - Run without uploading
• --debug - Show debug output
• --help - Show help
• --max-old-space-size - Set Node.js memory limit
• --max-semi-space-size - Set Node.js heap size
• --version - Show version

Configuration files

Socket CLI reads socket.yml configuration files. Supports version 2 format with projectIgnorePaths for excluding files from reports.

Environment variables

• SOCKET_CLI_API_TOKEN - Socket API token
• SOCKET_CLI_CONFIG - JSON configuration object
• SOCKET_CLI_GITHUB_API_URL - GitHub API base URL
• SOCKET_CLI_GIT_USER_EMAIL - Git user email (default: github-actions[bot]@users.noreply.github.com)
• SOCKET_CLI_GIT_USER_NAME - Git user name (default: github-actions[bot])
• SOCKET_CLI_GITHUB_TOKEN - GitHub token with repo access (alias: GITHUB_TOKEN)
• SOCKET_CLI_NO_API_TOKEN - Disable default API token
• SOCKET_CLI_NPM_PATH - Path to npm directory
• SOCKET_CLI_ORG_SLUG - Socket organization slug
• SOCKET_CLI_ACCEPT_RISKS - Accept npm/npx risks
• SOCKET_CLI_VIEW_ALL_RISKS - Show all npm/npx risks

See also

• Socket API Reference
• Socket GitHub App
• @socketsecurity/sdk

Development

Run locally:

npm install
npm run build
npm exec socket

Development environment variables

• SOCKET_CLI_API_BASE_URL - API base URL (default: https://api.socket.dev/v0/)
• SOCKET_CLI_API_PROXY - Proxy for API requests (aliases: HTTPS_PROXY, https_proxy, HTTP_PROXY, http_proxy). Currently not applied to API requests; see Network access for the NODE_USE_ENV_PROXY=1 workaround
• SOCKET_CLI_API_TIMEOUT - API request timeout in milliseconds
• SOCKET_CLI_DEBUG - Enable debug logging
• DEBUG - Enable debug package logging

License

MIT