MinIO Client (mc)

The MinIO Client mc command line tool 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 mc commandline tool is built for compatibility with the AWS S3 API and is tested MinIO and AWS S3 for expected functionality and behavior.

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

mc has the following syntax:

mc [GLOBALFLAGS] COMMAND --help

See Command Quick Reference for a list of supported commands.

AGPLv3

mc is AGPLv3 licensed Free and Open Source (FOSS) software.

Applications integrating mc may trigger AGPLv3 compliance requirements. MinIO Commericial Licensing is the best option for applications which trigger AGPLv3 obligations where open-sourcing the application is not an option.

Quickstart

1) Install mc

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

The following commands add a temporary extension to your system PATH for running the mc utility. Defer to your operating system instructions for making permanent modifications to your system PATH.

Alternatively, execute mc by navigating to the parent folder and running ./mc --help

64-bit Intel

curl https://dl.min.io/client/mc/release/linux-amd64/mc \
  --create-dirs \
  -o $HOME/minio-binaries/mc

chmod +x $HOME/minio-binaries/mc
export PATH=$PATH:$HOME/minio-binaries/

mc --help

64-bit PPC

curl https://dl.min.io/client/mc/release/linux-ppc64le/mc \
  --create-dirs \
  -o ~/minio-binaries/mc

chmod +x $HOME/minio-binaries/mc
export PATH=$PATH:$HOME/minio-binaries/

mc --help
brew install minio/stable/mc
mc --help

Open the following file in a browser:

https://dl.min.io/client/mc/release/windows-amd64/mc.exe

Execute the file by double clicking on it, or by running the following in the command prompt or powershell:

\path\to\mc.exe --help

Installation from source is intended for developers and advanced users and requires a working Golang environment. See How to install Golang.

Run the following commands in a terminal environment to install mc from source:

go get -d github.com/minio/mc
cd ${GOPATH}/src/github.com/minio/mc
make

To update a source-based installation, use go get -u. mc update does not support source-based installations.

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 mc alias set command to add an Amazon S3-compatible service to the mc configuration.

bash +o history
mc alias set ALIAS HOSTNAME ACCESS_KEY SECRET_KEY
bash -o history
  • Replace ALIAS with a name to associate to the S3 service. mc 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. Specifying only the mc config host add command starts an input prompt for entering the required values.

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

mc alias set myminio https://minioserver.example.net ACCESS_KEY SECRET KEY
mc alias set myS3 https://s3.amazon.com/endpoint ACCESS_KEY SECRET KEY
mc alias set myGCS https://storage.googleapis.com/endpoint ACCESS_KEY SECRET KEY

3) Test the Connection

Use the mc admin info command to test the connection to the newly added MinIO deployment:

mc admin info myminio

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 MinIO 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 mc commands:

Command

Description

The mc alias commands provide a convenient interface for managing the list of S3-compatible hosts that mc can connect to and run operations against.

mc commands that operate on S3-compatible services require specifying an alias for that service.

mc cat

The mc 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.

mc cp

The mc cp command copies objects to or from a MinIO deployment, where the source can MinIO or a local filesystem.

mc diff

The mc diff mc computes the differences between two filesystem directories or MinIO buckets. mc diff lists only those objects which are missing or which differ in size. mc diff does not compare the contents of objects.

The mc encrypt command sets, updates, or disables the default bucket Server-Side Encryption (SSE) mode. MinIO automatically encrypts objects using the specified SSE mode.

The mc event command supports adding, removing, and listing the bucket event notifications.

MinIO automatically sends triggered events to the configured notification targets. MinIO supports notification targets like AMQP (RabbitMQ), Redis, ElasticSearch, NATS and PostgreSQL. See MinIO Bucket Notifications for more information.

mc find

The mc find command supports searching for objects on a MinIO deployment. You can also use the command to search for files on a filesystem.

mc head

The mc head command displays the first n lines of an object, where n is an argument specified to the command.

The mc ilm command supports managing object lifecycle management rules on a MinIO deployment.

Use this command to set both Object Transition (“Tiering”) and Object Expiration rules on a bucket.

The mc legalhold command sets, removes, or retrieves the Object Legal Hold (WORM) settings for object(s).

mc ls

The mc ls command lists buckets and objects on MinIO or another S3-compatible service.

mc mb

The mc mb command creates a new bucket or directory at the specified path.

mc mirror

The mc mirror command synchronizes content to MinIO deployment, similar to the rsync utility. mc mirror supports filesystems, MinIO deployments, and other S3-compatible hosts as the synchronization source.

mc mv

The mc mv command moves an object from source to the target, such as between MinIO deployments or between buckets on the same MinIO deployment. mc mv also supports moving objects between a local filesystem and MinIO.

The mc policy 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.

mc rb

The mc rb command removes one or more buckets on MinIO or another S3-compatible service.

To remove only the contents of a bucket, use mc rm instead.

The mc 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.

The mc replicate command configures and manages the Server-Side Bucket Replication for a MinIO deployment, including active-active replication configurations and resynchronization.

mc rm

The mc rm command removes objects from a bucket on a MinIO deployment. To completely remove a bucket, use mc rb instead.

The mc share download and mc share upload commands generate presigned URLs for downloading and uploading objects to a MinIO bucket.

mc sql

The mc sql command provides an S3 Select interface for performing sql queries on objects in the specified MinIO deployment.

mc stat

The mc stat command displays information on objects in a MinIO bucket, including object metadata.

The MinIO Client mc support commands provides tools for analyzing deployment health or performance and for running diagnostics. You can also register your deployment with MinIO SUBNET and upload generated health reports for further analysis by MinIO engineering.

The mc tag command adds, removes, and lists tags associated to a bucket or object.

mc tree

The mc tree command lists all prefixes inside a MinIO bucket in a tree format. The command optionally supports listing all objects inside of bucket at each prefix, including the bucket root.

mc update

The mc update command automatically updates the mc binary to the latest stable version.

mc version

The mc version command enables, suspends, and retrieves the versioning configuration for a MinIO bucket.

mc watch

The mc watch command watches for events on the specified MinIO bucket or local filesystem path. For S3 services, use mc event add to configure bucket event notifications on S3-compatible services.

mc also includes an administration extension for managing MinIO deployments. See mc admin for more complete documentation.

Configuration File

mc uses a JSON formatted configuration file used for storing certain kinds of information, such as the aliases for each configured S3-compatible service.

For Linux and OSX, the default configuration file location is ~/.mc/config.json.

For Windows, mc attempts to construct a default file path by trying specific environment variables. If a variable is unset, mc moves to the next variable. If all attempts fail, mc returns an error. The following list describes each possible file path location in the order mc checks them:

  1. HOME\.mc\config.json

  2. USERPROFILE\.mc\config.json

  3. HOMEDRIVE+HOMEPATH\.mc\config.json

You can use the --config-dir

Global Options

All commands support the following global options:

--debug

Enables verbose output to the console.

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

mc --debug ls play
--config-dir

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

--JSON

Enables JSON lines formatted output to the console.

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

mc --JSON ls play
--no-color

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

--quiet

Suppresses console output.

--insecure

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

--version

Displays the current version of mc.