Introduction 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.

• socket report create – creates a Project Health Report on Socket.dev for your project. Uploads your package.json, package-lock.json etc and creates a report out of them.
• socket ci – like socket report create but waits for the report to complete 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 info [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

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.

Our current two commands, report and info, will likely get accompanied by more in the future. On top of that, report in itself is also multi-command and will for sure get more sub-commands going forward.

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

Strictness flags

• --all - by default only high and critical issues are included, by setting this flag all issues will be included
• --strict - when set, exits with an error code if report result is deemed unhealthy

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
• --debug - outputs additional debug output. Great for debugging, geeks and us who develop. Hopefully you will never need it, but it can still be fun, right?
• --help - prints the help for the current command. All CLI tools should have this flag
• --version - prints the version of the tool. All CLI tools should have this flag

How can I get my hands on this?

Install it like this:

npm install -g @socketsecurity/cli

Then run it using commands like:

socket --help
socket info [email protected]
socket report create .
socket report create package.json

And if you don't like to be asked for an API key all of the time (lets say you're in a CI environment), then put it in a SOCKET_SECURITY_API_KEY environment variable.

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 only way to use the CLI without going through installation using an npm compatible package manager is to build it from source from the GitHub repository where you can download source code for a given release. The ability to install software from the npm registry is a normal and generally accepted practice as of time of writing.