Introduction

In this preview release of the Socket CLI, we are shipping a subset of the commands that we aim for in our 1.0 release. Some would call it a beta, but the commands we support today already work well, so we call it a preview.

16201620
  • socket report create – this is the star of the show here. It enables you to create a Project Health Report on Socket for your project's dependencies. Running this command will upload just your package.json and package-lock.json files – we of course don't want your source code or other sensitive files. You can use this command to automate Socket in your CI, no matter if you use GitLab or something else. And you of course can use it manually as well.

  • socket info [email protected] – this is a glimpse into the next step for the CLI. The info command enables you to look up all the supply chain risks and other package "issues" that Socket has detected for given version of a package. It mainly gives you a short summary, but it already also supports outputting the raw JSON response from our API. For your jq pleasures or others. This truly enables you to build your own tooling. More on that later.

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:

24182418

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:

Action flags

  • --dry-run - the socket report create supports running the command without actually uploading anything. All CLI tools that perform an action should have a dry run flag
    Output flags
  • --json - outputs result as json which you can then pipe into jq and other tools
  • --markdown - outputs result as markdown. This can then be copied into GitHub, Linear etc to easily share the result with your colleagues. Useful when you eg. feel the need to create an issue or PR because you found a package with quite a few issues.

Other flags

  • --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?

To use this preview you need an API key.

We use our new API and SDK in this (announcement to follow) and currently you have to ask us for an API key to get one. Bummer, we know, we're working on a self-service tool at this very moment but didn't want to wait for it.

To get an API key, please book a meeting with the Socket team.

Anyone can install the CLI tool though and explore. It will ask you for the API key and fail if you don't give it one. Install it like this:

Then run it using commands like:

npm install -g @socketsecurity/cli
socket --help
socket info [email protected]
socket report create .
socket report create package.json

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

If you want to add it for a local project but don't want to add it globally, then direnv is your friend.

What's next?

We're committing early and often, iterating, rewriting, and listening to your feedback. We will ship updates to the CLI frequently in the coming weeks in response to your feedback. Give it a star and a watch on GitHub to ensure you're on top of it all.

Get started with the Socket CLI today by running npm install @socketsecurity/cli and let us know what you think!