Guide to Socket CLI

In the current preview release of the Socket CLI we have shipped a first set of the commands. More are to come as we are developing towards a 1.0 release.

Main features

• socket scan create – creates a Scan on Socket.dev for your project. Uploads your package.json, package-lock.json etc, and creates a Project Health Report.
• socket ci – like creating a Scan but waits for it to complete, compiles a report, and exits with an error code if report is showing that the project is unhealthy. Useful to automate Socket checks in eg. your Continuous Integration runs
• socket package score npm [email protected] – enables looking up supply chain risks and other package "issues" that Socket has detected for given version of a package. Gives you a short summary, but also eg. supports outputting the raw JSON response from our API, for your jq pleasures or similar.
• socket npm – A wrapper that automatically warns you against installing dangerous packages.
• socket analytics – A terminal based GUI showing metrics on your organization health.
• socket threat-feed – Easy access to our real-time threat feed.
• Various commands to leverage the API and update Socket.dev account details, repository management, etc.
• Most commands support --json easy automated consumption and --markdown for sharing.
• See sidebar for overview of commands. Or run socket to see the available commands.

What's in a Project Health Report?

A Socket Project Health Report contains a full listing of all package issues present in the project, as well as individual health scores for each package and average scores for the whole project.

There's a lot of incredible information about your packages in here:

How does the CLI work?

socket is a multi-command CLI tool.

The basic socket command does nothing more than giving you some help information, the rest of the magic is in the individual commands.

All commands describe themselves if you ask them using --help and the commands support mostly the same flags:

Output flags

• --json - outputs result as json which you can then pipe into jq and other tools
• --markdown - outputs result as markdown which you can then copy into an issue, PR or even chat

Other flags

• --dry-run - like all CLI tools that perform an action should have, we have a dry run flag. Eg. socket report create supports running the command without actually uploading anything. (This flag is not shown in --help but it exists for all commands.)
• --help - prints the help for the current command. All CLI tools should have this flag.
• --version - prints the version of the tool. The version information is also printed as part of the banner at the top of every command.

How can I get my hands on this?

Install it like this:

npm install -g socket

Then run it using commands like:

socket --help
socket package score npm [email protected] --markdown
socket report create .
socket report create package.json

And if you don't like to be asked for an API token all of the time you can do socket login to store the token locally or you can supply it in the command as an environmental variable, like SOCKET_SECURITY_API_TOKEN=xyz socket scan list for example.

If you want to add the environment variable for a local project but not globally, then use a tool like direnv.

Is the CLI distributed without using the npm registry?

Not as a fully built artifact. The ability to install software from the npm registry is a normal and generally accepted practice at the time of writing.

The code is open source, though. You can find the repository in its GitHub repository and you can build it manually.