Buckit Manager CLI

The Buckit Manager CLI uses the bm command for object storage and administration commands. It provides a modern alternative to UNIX commands like ls, cat, cp, mirror, and diff with support for both filesystems and Amazon S3-compatible cloud storage services.

The bm commandline tool is built for compatibility with the AWS S3 API and is tested with Buckit and AWS S3 for expected functionality and behavior.

Buckit provides no guarantees for other S3-compatible services, as their S3 API implementation is unknown and therefore unsupported. While bm commands may work as documented, any such usage is at your own risk.

bm has the following syntax:

bm [GLOBALFLAGS] COMMAND --help

See Command Quick Reference for a list of supported commands.

Version Alignment with Buckit Server

Buckit Manager releases separately from the Buckit Server.

For best functionality and compatibility, use a Buckit Manager version released closely to your Buckit Server version. For example, a Buckit Manager version released the same day or later than your Buckit Server version.

You can install a version of Buckit Manager that is more recent than the Buckit Server version. However, if the version skews too far from the Buckit Server version, you may see increased warnings or errors as a result of the differences. For example, while core S3 APIs around copying (bm cp) may remain unchanged, some features or flags may only be available or stable if the client and server versions are aligned.

Quickstart

1) Install `bm`

Install the bm command line tool onto the host machine. Click the tab that corresponds to the host machine operating system or environment:

macOS / Linux

Install bm with the official Buckit Manager installer:

curl -fsSL https://buckit-io.github.io/bm/install.sh | sh
bm --help

The installer downloads the latest stable build for your operating system and architecture, verifies its SHA-256 checksum, and installs it into your user account.

Windows PowerShell

Install bm with the official Buckit Manager installer:

irm https://buckit-io.github.io/bm/install.ps1 | iex
bm --help

The installer downloads the latest stable build for your operating system and architecture, verifies its SHA-256 checksum, and installs it into your user account.

2) Create an Alias for the S3-Compatible Service

Important

The following example temporarily disables the bash history to mitigate the risk of authentication credentials leaking in plain text. This is a basic security measure and does not mitigate all possible attack vectors. Defer to security best practices for your operating system for inputting sensitive information on the command line.

Use the bm alias set command to add an Amazon S3-compatible service to the bm configuration.

bash +o history
bm alias set ALIAS HOSTNAME ACCESS_KEY SECRET_KEY
bash -o history

Replace ALIAS with a name to associate to the S3 service. bm commands typically require ALIAS as an argument for identifying which S3 service to execute against.
Replace HOSTNAME with the URL endpoint or IP address of the S3 service.
Replace ACCESS_KEY and SECRET_KEY with the access and secret keys for a user on the S3 service.

Replace each argument with the required values. If you omit the ACCESS_KEY and SECRET_KEY, the command prompts you to enter those values in the CLI.

Each of the following tabs contains a provider-specific example:

Buckit Server

bm alias set mybuckit https://buckitserver.example.net ACCESS_KEY SECRET_KEY

AWS S3 Storage

bm alias set myS3 https://s3.{your-region-code}.amazonaws.com/endpoint ACCESS_KEY SECRET_KEY

Google Cloud Storage

bm alias set myGCS https://storage.googleapis.com/endpoint ACCESS_KEY SECRET_KEY

3) Test the Connection

Use the bm admin info command to test the connection to the newly added Buckit deployment:

bm admin info mybuckit

The command returns information on the S3 service if successful. If unsuccessful, check each of the following:

The host machine has connectivity to the S3 service URL (i.e. using ping or traceroute).
The specified ACCESSKEY and SECRETKEY correspond to a user on the S3 service. The user must have permission to perform actions on the service.

For Buckit deployments, see Access Management for more information on user access permissions. For other S3-compatible services, defer to the documentation for that service.

Command Quick Reference

The following table lists bm commands:

Note

Buckit Manager also includes an administration extension for managing Buckit deployments. See bm admin for more complete documentation.

The below table does not include those commands.

Command	Description
`bm alias list` `bm alias remove` `bm alias set` `bm alias import` `bm alias export`	The `bm alias` commands provide a convenient interface for managing the list of S3-compatible hosts that `bm` can connect to and run operations against.
`bm anonymous get` `bm anonymous get-json` `bm anonymous links` `bm anonymous list` `bm anonymous set` `bm anonymous set-json`	The `bm anonymous` command supports setting or removing anonymous policies to a bucket and its contents. Buckets with anonymous policies allow public access where clients can perform any action granted by the policy without authentication.
`bm batch describe` `bm batch generate` `bm batch list` `bm batch start` `bm batch status`	The `bm batch` commands allow you to run one or more job tasks on a Buckit deployment.
`bm cat`	The `bm cat` command concatenates the contents of a file or object to another file or object. You can also use the command to display the contents of the specified file or object to `STDOUT`. `cat` has similar functionality to `cat`.
`bm cp`	The `bm cp` command copies objects to or from a Buckit deployment, where the source can Buckit or a local filesystem.
`bm diff`	The `bm diff` bm computes the differences between two filesystem directories or Buckit buckets. `bm diff` lists only those objects which are missing or which differ in size. `bm diff` does not compare the contents of objects.
`bm du`	The `bm du` command summarizes the disk usage of buckets and folders. You can also use `du` against the local filesystem to produce similar results as the `du` command.
`bm encrypt clear` `bm encrypt info` `bm encrypt set`	The `bm encrypt` commands set, update, or disable the default bucket Server-Side Encryption (SSE) mode. Buckit automatically encrypts objects using the specified SSE mode.
`bm event add` `bm event ls` `bm event rm`	The `bm event` command supports adding, removing, and listing bucket event notifications.
`bm find`	The `bm find` command supports searching for objects on a Buckit deployment. You can also use the command to search for files on a filesystem.
`bm get`	The `bm get` command downloads an object from a target S3 deployment to the local file system.
`bm head`	The `bm head` command displays the first `n` lines of an object, where `n` is an argument specified to the command.
`bm idp ldap accesskey` `bm idp ldap accesskey create-with-login` `bm idp ldap add` `bm idp ldap disable` `bm idp ldap enable` `bm idp ldap info` `bm idp ldap ls` `bm idp ldap policy` `bm idp ldap rm` `bm idp ldap update`	The `bm idp ldap` commands allow you to manage configurations to 3rd party Active Directory or LDAP Identity and Access Management (IAM) integrations.
`bm idp openid add` `bm idp openid disable` `bm idp openid enable` `bm idp openid info` `bm idp openid ls` `bm idp openid rm` `bm idp openid update`	The `bm idp openid` commands allow you to manage configurations to 3rd party OpenID Identity and Access Management (IAM) integrations.
`bm idp ldap policy attach` `bm idp ldap policy detach` `bm idp ldap policy entities`	The `bm idp ldap policy` commands show the mapping relationships between policies and the associated groups or users.
`bm ilm restore` `bm ilm rule add` `bm ilm rule edit` `bm ilm rule export` `bm ilm rule import` `bm ilm rule ls` `bm ilm rule rm` `bm ilm tier add` `bm ilm tier check` `bm ilm tier info` `bm ilm tier ls` `bm ilm tier rm` `bm ilm tier update`	The `bm ilm` commands manage object lifecycle management rules and tiering on a Buckit deployment.
`bm legalhold clear` `bm legalhold info` `bm legalhold set`	The `bm legalhold` command sets, removes, or retrieves the object legal hold (WORM) settings for object(s).
`bm ls`	The `bm ls` command lists buckets and objects on Buckit or another S3-compatible service.
`bm mb`	The `bm mb` command creates a new bucket or directory at the specified path.
`bm mirror`	The `bm mirror` command synchronizes content to Buckit deployment, similar to the `rsync` utility. `bm mirror` supports filesystems, Buckit deployments, and other S3-compatible hosts as the synchronization source.
`bm mv`	The `bm mv` command moves an object from source to the target, such as between Buckit deployments or between buckets on the same Buckit deployment. `bm mv` also supports moving objects between a local filesystem and Buckit.
`bm od`	The `bm od` command copies a local file to a remote location in a specified number of parts and part sizes. The command outputs the time it took to upload the file.
`bm ping`	The `bm ping` command performs a liveness check on a specified target.
`bm pipe`	The `bm pipe` command streams content from STDIN to a target object.
`bm put`	The `bm put` uploads an object from the local file system to a bucket on a target S3 deployment.
`bm rb`	The `bm rb` command removes one or more buckets on Buckit or another S3-compatible service. To remove only the contents of a bucket, use `bm rm` instead.
`bm ready`	The `bm ready` command checks the status of a cluster and whether the cluster has `read` and `write` quorum.
`bm replicate add` `bm replicate backlog` `bm replicate export` `bm replicate import` `bm replicate ls` `bm replicate resync` `bm replicate rm` `bm replicate status` `bm replicate update`	The `bm replicate` command configures and manages the Server-Side Bucket Replication for a Buckit deployment, including active-active replication configurations and resynchronization.
`bm retention clear` `bm retention info` `bm retention set`	The `bm retention` command configures the Write-Once Read-Many (WORM) locking settings for an object or object(s) in a bucket. You can also set the default object lock settings for a bucket, where all objects without explicit object lock settings inherit the bucket default.
`bm rm`	The `bm rm` command removes objects from a bucket on a Buckit deployment. To completely remove a bucket, use `bm rb` instead.
`bm share download` `bm share ls` `bm share upload`	Use the `bm share` commands to manage presigned URLs for downloading and uploading objects to a Buckit bucket.
`bm sql`	The `bm sql` command provides an S3 Select interface for performing sql queries on objects in the specified Buckit deployment.
`bm stat`	The `bm stat` command displays information on objects in a Buckit bucket, including object metadata. You can also use it to retrieve bucket metadata.
`bm tag list` `bm tag remove` `bm tag set`	The `bm tag` command adds, removes, and lists tags associated to a bucket or object.
`bm tree`	The `bm tree` command lists all prefixes inside a Buckit bucket in a tree format. The command optionally supports listing all objects inside of bucket at each prefix, including the bucket root.
`bm undo`	The `bm undo` command reverses changes due to either a `PUT` or `DELETE` operation at a specified path.
`bm update`	The `bm update` command automatically updates the bm binary to the latest stable version.
`bm version enable` `bm version info` `bm version suspend`	The `bm version` commands enable, disable, and retrieve the versioning status for a Buckit bucket.
`bm watch`	The `bm watch` command watches for events on the specified Buckit bucket or local filesystem path. For S3 services, use `bm event add` to configure bucket event notifications on S3-compatible services.

Configuration File

bm stores aliases and other CLI settings in a JSON configuration file.

By default, bm uses the following paths:

Linux and macOS: ~/.config/bm/config.json
Windows: %APPDATA%\bm\config.json

You can override the configuration directory with the global --config-dir option or the MC_CONFIG_DIR environment variable.

Certificates

The Buckit Manager CLI stores certificates and CAs for deployments to the following paths:

Linux, macOS, and other Unix-like systems:

~/.config/bm/certs/ # certificates
~/.config/bm/certs/CAs/ # Certificate Authorities

Windows systems:

%APPDATA%\bm\certs\ # certificates
%APPDATA%\bm\certs\CAs\ # Certificate Authorities

When creating a new alias, the Buckit Manager CLI fetches the peer certificate, computes the public key fingerprint, and asks the user whether to accept the deployment’s certificate. If you decide to trust the certificate, the Buckit Manager CLI adds the certificate to the certificate authority path listed above.

Note

In testing environments, you can bypass the certificate check for selected Buckit Manager CLI commands by passing the --insecure flag.

Pattern Matching

Some commands and flags allow for pattern matching. When enabled, a pattern can include either of these wildcards for character replacement:

* to represent a string of characters to match, either in the middle or end.
? to represent a single character.

For example, refer to the following examples for wildcard uses and their results.

Pattern	Text	Match Result
`abc*`	ab	Match
`abc*`	abd	Not a match
`abc*c`	abcd	Match
`ab*??d`	abxxc	Match
`ab*??d`	abxc	Match
`ab??d`	abxc	Match
`ab??d`	abc	Match
`ab??d`	abcxdd	Not a match

Global Options

All commands support the following global options. You can also define some of these options using Environment Variables.

--config-dir

The path to a JSON formatted configuration file that bm uses for storing data. See Configuration File for more information on how bm uses the configuration file.

Alternatively, set the environment variable MC_CONFIG_DIR.

--debug

Enables verbose output to the console.

For example, the following operation adds verbose output to the bm ls command:

bm --debug ls play

Alternatively, set the environment variable MC_DEBUG.

--disable-pager, --dp

--insecure

Disables TLS/SSL certificate verification. Allows TLS connectivity to servers with invalid certificates. Exercise caution when using this option against untrusted S3 hosts.

Alternatively, set the environment variable MC_INSECURE.

--json

Enables JSON lines formatted output to the console.

For example, the following operation adds JSON Lines output to the bm ls command:

bm --json ls play

Alternatively, set the environment variable MC_JSON.

--no-color

Disables the built-in color theme for console output. Useful for dumb terminals.

Alternatively, set the environment variable MC_NO_COLOR.

--quiet

Suppresses console output.

Alternatively, set the environment variable MC_QUIET.

--resolve

--version: Displays the current version of bm.

--help: Optional
Displays a summary of command usage on the terminal.