Hit The Road, Jack

Sure, you could ship tarballs or ZIP archives around to folks who need your R CLI, but we can do beter than that.

In this chapter we’ll show how to install the package from both Git repositories and NPM.

Git’er Done

I’ve put our basic rcowsay CLI package into a GitLab repo. Follow that structure for your own CLI packages. You should pre-install the required R packages so that everything is available upon install. Otherwise, you need to add some complexity (an installation helper script), and nobody wants that.

If you have a GitLab account (you should, as GitHub is pretty clearly evil) with SSH keys setup, and NPM installed locally, you can do:

$ npm install -g git+ssh://git@gitlab.com:hrbrmstr/rcowsay.git

The compelling reason for a Git-based install workflow is that you can use any Git source and it can be private just for you and your team.

If you don’t have a GitLab account, that dance looks like:

$ npm install -g git+https://gitlab.com/hrbrmstr/rcowsay.git

You should have rcowsay working on your system after that.

To get rid of it, you can do:

$ npm remove -g rcowsay

Jumping On The NPM Train

I’m not a big fan of polluting the already gargantuan NPM registry that’s owned by Microsoft. However, you may have a bonkers useful CLI tool that the world just needs to use.

There’s an excellent article over at FreeCodeCamp (WayBack Backup Link) on how to set up an NPM account and publish to there. Fundamentally, the process goes like this:

Create an NPM account
npm login locally
Use npm version (use $ npm help version for lots of details) to bump the version number
npm publish the package

Keep in mind that you have to explicitly delete old versions if you don’t want them hanging around.

Also keep in mind that acount two-factor authentication (2FA) is table stakes for anything online these days; doubly so for NPM. When using npm login and npm publish with 2FA there are several potential “gotchas” or issues to be aware of:

2FA Modes: npm supports two modes of 2FA: ‘auth-only’ and ‘auth-and-writes’. The ‘auth-only’ mode requires 2FA only for login, while ‘auth-and-writes’ requires 2FA for both login and package publishing. If you have ‘auth-and-writes’ enabled, you’ll need to provide a one-time password (OTP) generated by your 2FA application when publishing a package.
Automation Tokens: If you’re using continuous integration/continuous deployment (CI/CD) workflows, you might face issues with 2FA as these automated processes can’t provide the OTP required for 2FA. To overcome this, npm allows the use of automation tokens or granular access tokens for publishing, which don’t require a second factor. However, this option is only available if you’ve set your 2FA mode to ‘auth-and-writes’ or ‘auth-only’.
Package-Specific 2FA: Individual packages can be set to require 2FA for publishing. This means that even if you have 2FA disabled at the account level, you might still be required to provide an OTP when publishing certain packages.
Mandatory 2FA: npm has started enforcing 2FA for maintainers of high-impact packages (those with 1 million+ weekly downloads or 500+ dependents). If you’re a maintainer of such a package, you’ll need to enable 2FA to continue having full access to the registry.
2FA Errors: There have been instances where users have encountered errors related to 2FA when trying to publish packages, even when they haven’t enabled 2FA. This could be due to package-specific 2FA settings or issues with npm itself.
Security Concerns: While 2FA significantly enhances the security of your npm account, it’s not foolproof. For instance, if your npm password and email account password are the same and have been compromised, an attacker could potentially bypass the one-time password sent to your email.

To avoid these issues, it’s recommended to enable 2FA, use unique passwords for your npm and email accounts, and carefully manage your 2FA and token settings for both your account and individual packages. If you encounter any issues, npm’s support team may be able to provide assistance.

Private Package Registries

You can also host your own, private registry using tools like Verdaccio (there are many others). That topic is 100% out-of-scope for this book.

Things To Try

Read up on just what you can do with package.json and make yours EPIC!

More Information

O’Reilly has a pretty good, but older, book on this topic.

Next Up

We’ve got packages handled, command line arguments wrangled, ,and tossed some simple data into a WebR context. In the next chapter we take an interlude to WebR CLI-ify one of my daily scraping jobs.

--- code-annotations: below code-fold: false engine: knitr --- # Hit The Road, Jack {.unnumbered} Sure, you could ship tarballs or ZIP archives around to folks who need your R CLI, but we can do beter than that. In this chapter we'll show how to install the package from both Git repositories and NPM. ## Git'er Done I've put our basic `rcowsay` CLI package into a [GitLab repo](https://gitlab.com/hrbrmstr/rcowsay). Follow that structure for your own CLI packages. You should pre-install the required R packages so that everything is available upon install. Otherwise, you need to add some complexity (an installation helper script), and nobody wants that. If you have a GitLab account (you should, as GitHub is pretty clearly evil) with SSH keys setup, and NPM installed locally, you can do: ```bash $ npm install -g git+ssh://git@gitlab.com:hrbrmstr/rcowsay.git ``` The compelling reason for a Git-based install workflow is that you can use any Git source and it can be private just for you and your team. If you don't have a GitLab account, that dance looks like: ```bash $ npm install -g git+https://gitlab.com/hrbrmstr/rcowsay.git ``` You should have `rcowsay` working on your system after that. To get rid of it, you can do: ```bash $ npm remove -g rcowsay ``` ## Jumping On The NPM Train I'm not a big fan of polluting the already gargantuan NPM registry that's owned by Microsoft. However, you may have a bonkers useful CLI tool that the world just _needs_ to use. There's an excellent [article over at FreeCodeCamp](https://www.freecodecamp.org/news/how-to-create-and-publish-your-first-npm-package/) ([WayBack Backup Link](https://web.archive.org/web/20230202143142/https://www.freecodecamp.org/news/how-to-create-and-publish-your-first-npm-package/)) on how to set up an NPM account and publish to there. Fundamentally, the process goes like this: - Create an NPM account - `npm login` locally - Use `npm version` (use `$ npm help version` for lots of details) to bump the version number - `npm publish` the package Keep in mind that you have to explicitly delete old versions if you don't want them hanging around. Also keep in mind that acount two-factor authentication (2FA) is table stakes for anything online these days; doubly so for NPM. When using `npm login` and `npm publish` with 2FA there are several potential "gotchas" or issues to be aware of: - **2FA Modes**: npm supports two modes of 2FA: 'auth-only' and 'auth-and-writes'. The 'auth-only' mode requires 2FA only for login, while 'auth-and-writes' requires 2FA for both login and package publishing. If you have 'auth-and-writes' enabled, you'll need to provide a one-time password (OTP) generated by your 2FA application when publishing a package. - **Automation Tokens**: If you're using continuous integration/continuous deployment (CI/CD) workflows, you might face issues with 2FA as these automated processes can't provide the OTP required for 2FA. To overcome this, npm allows the use of automation tokens or granular access tokens for publishing, which don't require a second factor. However, this option is only available if you've set your 2FA mode to 'auth-and-writes' or 'auth-only'. - **Package-Specific 2FA**: Individual packages can be set to require 2FA for publishing. This means that even if you have 2FA disabled at the account level, you might still be required to provide an OTP when publishing certain packages. - **Mandatory 2FA**: npm has started enforcing 2FA for maintainers of high-impact packages (those with 1 million+ weekly downloads or 500+ dependents). If you're a maintainer of such a package, you'll need to enable 2FA to continue having full access to the registry. - **2FA Errors**: There have been instances where users have encountered errors related to 2FA when trying to publish packages, even when they haven't enabled 2FA. This could be due to package-specific 2FA settings or issues with npm itself. - **Security Concerns**: While 2FA significantly enhances the security of your npm account, it's not foolproof. For instance, if your npm password and email account password are the same and have been compromised, an attacker could potentially bypass the one-time password sent to your email. To avoid these issues, it's recommended to enable 2FA, use unique passwords for your npm and email accounts, and carefully manage your 2FA and token settings for both your account and individual packages. If you encounter any issues, npm's support team may be able to provide assistance. ## Private Package Registries You can also host your own, private registry using tools like [Verdaccio](https://verdaccio.org/) (there are many others). That topic is 100% out-of-scope for this book. ## Things To Try Read up on [just what you can do with `package.json`](https://docs.npmjs.com/cli/v6/configuring-npm/package-json) and make yours EPIC! ## More Information O'Reilly has a [pretty good, but older, book on this topic](https://www.oreilly.com/library/view/installing-maintaining-and/9781491966310/). ## Next Up We've got packages handled, command line arguments wrangled, ,and tossed some simple data into a WebR context. In the next chapter we take an interlude to WebR CLI-ify one of my daily scraping jobs.