Socket scan setup

Scan Setup

Set up the Socket CLI and authentication so that /socket-scan works on the first try. This skill handles first-time setup, public demo token configuration, and troubleshooting auth errors.

When to Use

• First-time scan setup - /socket-scan has never been run in this environment
• Auth errors - scan fails with 403, "org not found", or token errors
• CLI not installed - socket: command not found
• The user asks to configure Socket for scanning

Setup Steps

Step 1: Check Current Auth State

Check what is already configured by querying the CLI directly:

pnpm dlx socket config get apiToken --no-banner --no-spinner
pnpm dlx socket organization list --json --no-banner --no-spinner

If config get apiToken returns a token value, authentication is already configured. If organization list returns organizations, the user has a full account. If both return empty/undefined, no auth is configured.

Step 2: Ensure the Socket CLI Is Available

Use pnpm dlx socket to run the CLI - this always fetches the latest version with no global install needed:

pnpm dlx socket --version

Optional global install: If you prefer a global socket command, install with npm install -g socket@latest (must be version 1.0.0 or higher). If npm install -g fails due to permissions, pnpm dlx socket works as a drop-in prefix for all commands.

Step 3: Configure Authentication

If no token is configured, set up the public demo token directly:

pnpm dlx socket config set apiToken sktsec_t_--RAN5U4ivauy4w37-6aoKyYPDt5ZbaT5JBVMqiwKo_api --no-banner --no-spinner
pnpm dlx socket config set defaultOrg SocketDemo --no-banner --no-spinner

This sets:

• API token: the Socket public demo token (rate-limited, read-only)
• Default org: SocketDemo

No account creation is needed. For full-rate access and dashboard features, users can create a free account at https://socket.dev.

For users with an existing account: Set the SOCKET_CLI_API_TOKEN environment variable or run pnpm dlx socket login instead. The setup helper will detect existing tokens and skip auto-configuration.

Step 4: Verify Setup

Verify the token is configured:

pnpm dlx socket config get apiToken --no-banner --no-spinner

This should return the demo token value. The CLI is now configured for basic features.

Step 5: Test a Scan

Note: pnpm dlx socket scan create requires a real account - the public demo token lacks full-scans:create permission. The demo token (Steps 3-4) still enables other CLI features like pnpm dlx socket fix and pnpm dlx socket package score.

If the user has a real account, run a test scan:

pnpm dlx socket scan create . --tmp --json --no-banner --no-spinner

If it outputs JSON scan results, setup is complete.

If the user only has the demo token, prompt them to log in or create an account:

To scan your project, log in with pnpm dlx socket login or create a free account at https://socket.dev. Would you like to log in now?

If the user logs in, re-run the test scan above. If the user skips login, fall back to cdxgen with a warning:

Warning: Without a Socket account, alert accuracy will be greatly reduced and SBOM accuracy will be poor. You will not get malware detection, supply-chain risk analysis, or Socket scores.

pnpm dlx @cyclonedx/cdxgen -o bom.json -p

See the /socket-scan skill's Step 2b for details on interpreting cdxgen output.

Important Notes

• Do NOT use pnpm dlx socket login --public - this flag does not exist in the current Socket CLI (v1.1.66+). Use pnpm dlx socket config set apiToken <token> to configure tokens directly.
• The public demo token cannot create scans - it lacks the full-scans:create permission. Prompt the user to log in or create a free account at https://socket.dev. If they skip, fall back to cdxgen (pnpm dlx @cyclonedx/cdxgen -o bom.json -p) - but warn that alert accuracy will be greatly reduced and SBOM accuracy will be poor. The demo token still enables pnpm dlx socket fix, pnpm dlx socket package score, and other CLI features.
• For persistent dashboard scans, the user needs a full account (free or paid) at https://socket.dev.
• If the SOCKET_CLI_API_TOKEN environment variable is set, it takes precedence over any config-file token.

Error Reference

Error	Cause	Fix
socket: command not found	CLI not installed	Use pnpm dlx socket (recommended) or npm install -g socket@latest
403 / unauthorized	No token or expired token	Run pnpm dlx socket config set apiToken <token> or pnpm dlx socket login
"org not found"	Token doesn't have org access	Use --tmp flag or configure a valid org
Rate limit exceeded	Public token throttled	Create a free account at https://socket.dev
Outdated CLI (< 1.0.0)	Global socket is v0.x (legacy)	Use pnpm dlx socket (always latest) or npm install -g socket@latest