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 app.
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 documentation. The documentation also covers usage instructions for the different actions of the Bytesafe CLI.
The authentication token required for login to Bytesafe (using the CLI) can be found on the CLI page in Bytesafe.
To start using the Bytesafe CLI, visit the CLI page of the Bytesafe documentation.
Don’t have a Bytesafe account yet? Sign up with just a few clicks.
Bytesafe pull
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.
Usage examples
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 bytesafe list
$ # 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 node-pkg@1.5.0
pulled node-pkg@1.5.0
...
$ # pull latest package version (@VERSION is omitted)
$ bytesafe pull -r prod-registry node-pkg
pulled node-pkg@1.5.0
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:node-pkg@1.5.0
pulled partner-reg:node-pkg@1.5.0
Note: Package version needs to be explicitly specified when pulling from a specified upstream
Bytesafe push
bytesafe push pushes between registries and upstreams and like its counterpart, pull, is used for managing registries and moving package versions between registries
For comparison: 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.
Usage example
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 node-pkg@1.5.0 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!
Tip: Enable your organization to manage Javascript packages more securely by setting up a Bytesafe registry as an npm proxy!
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 Bytesafe
- 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 upstreams settings from Bytesafe
- 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.
