For the users that prefer command line, Bytesafe offers the Bytesafe CLI for MacOS, Linux and Windows. The CLI supports actions for managing your private registries and packages. Giving you complete control over what package versions are available in each registry!
Most Bytesafe actions can be performed either from the CLI or the web console.
For this post I will cover
bytesafe push and
bytesafe pull of package versions in more detail.
If you instead want to know how to configure and use the npm client with Bytesafe, please read Bytesafe basics.
Get started using Bytesafe CLI
Distributions of the Bytesafe CLI are available for download from the Bytesafe web console by clicking CLI in the menu.
The authentication token required for login to Bytesafe (using the CLI) as well as other usage instructions can be found on the CLI page in the Bytesafe web console.
To start using the Bytesafe CLI, visit the CLI page by signing in to the web console for your Bytesafe account
Don’t have a Bytesafe account yet? Sign up with just a few clicks.
bytesafe pull pulls package versions from an upstream into a registry and is used for managing registries and moving packages between registries.
When using pull, you always express which registry you want to pull the package into (using the -r or –registry followed by registry name).
You can either:
- Specify a specific upstream to pull package from
- Exclude upstream information and Bytesafe will attempt to pull the package version from all configured upstreams in priority order
Unlike when using
npm install to install a package into a project workspace, package dependencies is not included by default when using
bytesafe pull to pull package versions into a registry.
For the sake of example lets assume the following:
- <REGISTRY> : prod-registry (the registry to pull into, set with -r)
- <UPSTREAM> : partner-reg (one of the configured upstreams for registry: prod-registry)
- <PACKAGE> : node-pkg (availalable in the partner-reg upstream)
- <VERSION> : 1.5.0 (tag “latest” points to this version)
First, we check what packages are stored in the registry before our action, using
$ # Using bytesafe list -r <REGISTRY> lists all packages stored in that registry
$ bytesafe list -r prod-registry
| NAME | LATEST |
No packages are listed. Our example registry is empty.
Pull, without specifying upstream source
In scenarios where you only have one upstream source or you have no direct preference regarding upstream source, you can exclude information regarding which upstream to fetch the package from.
$ # Usage pattern: bytesafe pull -r <REGISTRY> <PACKAGE>[@VERSION]
$ bytesafe pull -r prod-registry firstname.lastname@example.org
$ # pull latest package version (@VERSION is omitted)
$ bytesafe pull -r prod-registry node-pkg
What package version to pull is either specifically expressed or you can omit what version to pull. If package version is omitted, the package version that is tagged as latest will be pulled into the specified registry.
Pull, with specified upstream
If you want to be in control of what upstream source is used when pulling package versions, you can specify the upstream source as part of the command. This is for instance beneficial when an upstream registry contains a patched version of a package.
$ # Usage pattern: bytesafe pull -r <REGISTRY> [UPSTREAM:]<PACKAGE@VERSION>
$ bytesafe pull -r prod-registry partner-reg:email@example.com
Note: Package version needs to be explicitly specified when pulling from a specified upstream
bytesafe push pushes between registries and upstreams and like its counterpart, pull, is used for managing registries and moving package versions between registries
npm publish publishes a package from a project workspace to a registry)
When using push, you always express the source registry that contains the package versions you want to push as well as the upstream target registry.
Source registry is specified using -r or –registry followed by registry name and target registry by using the upstream name.
Specifying package version is optional and as such if a specific version is excluded the version tagged latest will be pushed.
Let’s assume we want to push the same example package version to the public npm registry (which is configured as upstream with name: npmjs). Below example assumes upstream is configured with a maintainer access token (see potential errors below).
$ # Usage pattern: bytesafe push -r <REGISTRY> <PACKAGE>[@VERSION] <UPSTREAM>
$ # Version can be omitted to push latest version
$ bytesafe push -r prod-registry firstname.lastname@example.org npmjs
Pushed package: node-pkg version: 1.5.0 from: prod-registry to: npmjs
Bytesafe has now pushed the package version to the specified upstream!
Use a Bytesafe private npm registry as the target for your
npm publish from a project workspace and use
bytesafe push to push a package to public npm registry as an upstream.
Troubleshooting and potential errors
The flexibilty with how you can configure upstreams for your Bytesafe registries enable a powerful way of securely managing your packages and versions. And the results of pushing and pulling are dependent on your configuration.
If no upstreams are configured for a registry or your action would fail for any other reason, an error message will be available in your terminal. Error messages are recursive, so for configurations with multiple upstreams (direct or indirect) you will receive appropriate guidance.
Potential error causes:
- No upstream configured - Configure an upstream for your registry in the Bytesafe web console
- Upstream does not contain specified package version - Either specify another upstream to fetch package version from or add the package to the upstream (either directly or by adding another upstream to that registry)
- Missing upstream authentication token - Certain upstreams require an authentication token to be provided (like a maintainer access token for pushes to public npm). If required, the token can be added in the Bytesafe web console
- Unable to reach upstream - Double check URL (and token) for the configured upstream
For more information and details on upstream configurations when using push and pull commands, see the post Using Bytesafe - Upstreams.