Welcome to the upcoming version of the MinIO Documentation! The content on this page is under active development and may change at any time. If you can't find what you're looking for, check our legacy documentation. Thank you for your patience.

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 (AWS Signature v2 and v4).

mc has the following syntax:

mc [FLAGS] COMMAND [COMMAND FLAGS | -h] [ARGUMENTS...] ALIAS

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:

Stable

docker pull minio/mc
docker run minio/mc admin info play

Edge

Do not use bleeding-edge deployments of MinIO in production environments

docker pull minio/mc:edge
docker run minio/mc:edge admin info server play

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) Add an 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 Identity and 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

mc alias

The mc alias command provides 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 data from one or more sources to a target S3-compatible service.

mc diff

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

mc encrypt

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

For more information on configuring SSE, see Server-Side Object Encryption

mc event

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 querying for objects on an S3-compatible host. 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.

mc ilm

The mc ilm command manages object lifecycle management rules on a bucket. See the AWS documentation on Object Lifecycle Management for more information.

mc legalhold

The mc legalhold command enables or disables object legal hold. Enabling legal hold on an object prevents any modification or deletion of the object and is equivalent to setting Write-Once Read-Only (WORM) mode on the object.

mc lock

Deprecated since RELEASE.2020-09-18T00-13-21Z. Use mc retention.

mc ls

The mc ls command lists all buckets and objects on the target S3-compatible service. For targets on a filesystem, mc ls has the same functionality as the ls command.

mc mb

The mc mb command creates a new bucket or directory at the specified path. For targets on an S3-compatible service, mc mb creates a new bucket. For targets on a filesystem, mc mb has equivalent functionality to mkdir -p.

mc mirror

The mc mirror command synchronizes content to an S3-compatible host, similar to the rsync utility. mc mirror supports both filesystems and S3-compatible hosts as the synchronization source.

mc mv

The mc mv command moves data from one or more sources to a target S3-compatible service.

mc policy

The mc policy command supports setting or removing anonymous policies to a bucket and its contents using AWS S3 JSON policies. Buckets with anonymous policies allow public access where clients can perform any action granted by the policy without.

mc rb

The mc rb command removes a bucket and all its contents on the target S3-compatible service.

Removing a bucket with mc rb also removes any configurations associated to that bucket. To remove only the contents of a bucket, use mc rm instead.

mc retention

The mc retention command configures the Write-Once Read-Many (WORM) object lock 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.

mc rm

The mc rm command removes objects on a target S3-compatible service. To completely remove a bucket, use mc rb instead.

mc share

The mc share command generates temporary URLs with integrated access credentials for uploading or downloading objects to an S3-compatible host. The temporary URL expires after a configurable time limit.

mc sql

The mc sql command provides an S3 Select interface for performing sql queries on objects in the specified S3-compatible service.

mc stat

The mc stat command displays information on objects contained in the specified S3-compatible service bucket. mc stat has similar functionality as the stat command when used on a filesystem path.

mc tag

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

mc tree

The mc tree command lists buckets and directories in a tree format.

mc update

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

mc version

The mc version command enables or disables bucket versioning.

mc watch

The mc watch command watches for events on the specified S3-compatible service bucket or local filesystem path. For S3 services, use mc event 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.